Web-Widget-Anbieter

Sie können ein Windows Widget mit HTML füllen, das von einer URL bereitgestellt wird, anstatt dessen Inhalt mit Adaptive Karten zu definieren. Ihr Anbieter stellt weiterhin eine JSON-Nutzlast für adaptive Karten bereit, die die Inhalts-URL angibt. Beginnen Sie mit der Implementierung eines Widgetanbieters in einer C#-Windows-App oder implementieren Sie einen Widgetanbieter in einer Win32-App (C++/WinRT) und fügen Sie dann die hier beschriebenen Webinhaltsfunktionen hinzu.

Die Ressourcen- und Messaging-APIs in diesem Artikel wurden in Windows App SDK 1.6.3 eingeführt. Verwenden Sie eine aktuell unterstützte stabile Version aus den Windows App SDK-Releasekanälen, und testen Sie auf einem Windows 11-Gerät mit einem Widgethost, der Webinhalte unterstützt.

Die C#-Beispiele sind Fragmente für einen Anbieter für paketierte Desktop-Widgets. Fügen Sie using Windows.Storage.Streams; und using Microsoft.Windows.Widgets.Providers; zur Quelldatei des Anbieters hinzu. Implementieren Sie IWidgetProvider weiterhin, wenn Sie IWidgetResourceProvider oder IWidgetProviderMessage hinzufügen.

Angeben der Inhalts-URL

Senden Sie Ihre JSON-Nutzlast mit WidgetManager.UpdateWidget. Geben Sie ein Metadatenobjekt mit einem WebUrl-Feld an, das auf den HTML-Inhalt verweist. Fügen Sie einen Adaptive-Karten-Textkörper als Fallbackinhalt für Hosts hinzu, die das Laden von Webinhalten nicht unterstützen, anstatt diese Hosts mit einem leeren Widget zurückzulassen.

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6",
    "body": [
        {
            "type": "TextBlock",
            "text": "Open the app to view this content.",
            "wrap": true
        }
    ],
    "metadata": {
        "webUrl": "https://contoso.com/widgetprovider.html"
    }
}

Die $host.isWebSupported Vorlageneigenschaft gibt an, ob der Host Webinhalte unterstützt. Verwenden Sie sie, wenn Sie die Fallbackpräsentation weiter anpassen müssen. Weitere Informationen finden Sie unter Windows Widget-Host-Eigenschaften.

Umgang mit Ressourcenanforderungen

Widgetanbieter können eine Webanforderungsfilterzeichenfolge für ein Widget im WebRequestFilter-Attribut des Definition-Elements in der Paketmanifestdatei des Anbieters angeben. Wann immer der Widget-Inhalt eine Ressource mit einer URI anfordert, die den Filter erfüllt, wird die Anforderung abgefangen und zur Implementierung von IWidgetResourceProvider.OnResourceRequested umgeleitet.

Das Filtermuster verwendet das in Match Patterns beschriebene Format. Verwenden Sie bei Bedarf Punycode. Der Filter muss mit dem von webUrl angegebenen Ursprung übereinstimmen. Anfragen für alle Inhaltstypen werden bei Übereinstimmungen umgeleitet. Beschränken Sie den Filter daher auf Ressourcen, die Ihr Anbieter verarbeitet. Ausführliche Informationen finden Sie im XML-Format des Widget-Anbieterpaketmanifests.

Um Ressourcenanforderungen zu verarbeiten, müssen Widgetanbieter die IWidgetResourceProvider-Schnittstelle implementieren.

internal class WidgetProvider : IWidgetProvider, IWidgetResourceProvider

Legen Sie in OnResourceRequestedWidgetResourceRequestedArgs.Response auf ein WidgetResourceResponse fest, das die Ressource enthält. In diesem Beispiel wird eine angeforderte URL einem verpackten Bild zugeordnet. Fügen Sie Assets\image.png als Inhalt in Ihr App-Paket ein. RandomAccessStreamReference.CreateFromUri unterstützt das ms-appx-Schema, sodass Sie den Datenstromverweis erstellen können, ohne auf eine Dateisuche zu warten.

void IWidgetResourceProvider.OnResourceRequested(WidgetResourceRequestedArgs args)
{
    if (args.Request.Uri == "https://contoso.com/logo-image")
    {
        var imageUri = new System.Uri("ms-appx:///Assets/image.png");
        var content = RandomAccessStreamReference.CreateFromUri(imageUri);
        var response = new WidgetResourceResponse(content, "OK", 200);
        response.Headers.Add("Content-Type", "image/png");
        args.Response = response;
    }
}

In diesem synchronen Beispiel wird kein Deferral benötigt. Wenn in Ihrer Implementierung vor dem Festlegen der Antwort noch Arbeit aussteht, rufen Sie GetDeferral auf, bevor der Rückruf zurückkehrt, und schließen Sie sie in einem finally Block ab. Behandeln und melden Sie asynchrone Fehler gemäß der Fehlerbehandlungsrichtlinie Ihrer App.

Wenn Sie keine Response festlegen, ruft das System die Ressource aus dem Web ab. Sie können WidgetResourceRequest.Headers auf args.Request vor diesem Abruf ändern. Fügen Sie Anfragen nur dann Anmeldeinformationen, wenn Sie deren Herkunft vertrauen; eine Filterübereinstimmung allein ist keine Berechtigung, ein Token zu senden.

Umgang mit Nachrichten zu und von Webinhalten

Um Zeichenfolgenmeldungen vom Inhalt des Widgets zu empfangen, der mit der Methode window.chrome.webview.postMessage JavaScript gepostet wurde, können Widgetanbieter die IWidgetProviderMessage-Schnittstelle implementieren und die OnMessageReceived-Methode implementieren.

internal class WidgetProvider : IWidgetProvider, IWidgetProviderMessage

Fügen Sie den Callback zu Ihrer Provider-Klasse hinzu:

public void OnMessageReceived(WidgetMessageReceivedArgs args)
{
    System.Console.WriteLine($"Message received from widget {args.WidgetContext.Id}: {args.Message}");
}

Senden Sie eine Nachricht an den Webinhalt eines Widgets mit WidgetManager.SendMessageToContent. Übergeben Sie die Widgetinstanz-ID aus WidgetContext.Id, nicht die Definitions-ID aus dem Paketmanifest. Mehrere Instanzen einer Definition weisen unterschiedliche Instanz-IDs auf.

Rufen Sie das folgende Hilfsprogramm von einem Anbieterrückruf auf, und übergeben Sie den WidgetContext für die Zielinstanz, z. B. den Kontext, der von CreateWidget oder OnActionInvoked empfangen wurde. Serialisieren Sie strukturierte Nachrichten, anstatt JSON mit Zeichenfolgeninterpolation zu erstellen, sodass Werte, die Anführungszeichen oder umgekehrte Schrägstriche enthalten, gültig bleiben.

private static void SendLocationToWidget(WidgetContext widgetContext, string location)
{
    string message = System.Text.Json.JsonSerializer.Serialize(
        new { current_location = location });
    WidgetManager.GetDefault().SendMessageToContent(widgetContext.Id, message);
}

Der Webinhalt empfängt die Nachricht als Zeichenfolge über das Ereignis window.chrome.webviewmessage. Wenn Sie JSON wie in diesem Beispiel serialisieren, parsen Sie die Zeichenfolge in Ihrem Webinhalt. Ausführliche Informationen finden Sie unter PostWebMessageAsString und der WebView2-JavaScript-API.

Einschränkungen und Anforderungen

Important

Dieses Feature ist nur für Benutzer im Europäischen Wirtschaftsraum (EWR) verfügbar.

Web-Widget-Anbieter sind keine Feedanbieter. Informationen zu Dashboardfeeds und ihren regionalen Anforderungen finden Sie unter Dashboards und Feedanbieter. Informationen zum separaten PWA-Manifest- und Service-Worker-Implementierungspfad finden Sie unter PWA-gesteuerte Widgets erstellen.

  • Zuletzt aktualisiert um