Webbwidgetprovidrar

Du kan fylla en Windows-widget med HTML som serveras från en URL i stället för att definiera dess brödtext med Adaptive Cards. Providern tillhandahåller fortfarande en JSON-nyttolast för Adaptive Card som anger innehålls-URL:en. Börja med Implementera en widgetprovider i en C#-Windows App eller Implementera en widgetprovider i en win32-app (C++/WinRT) och lägg sedan till funktionerna för webbinnehåll som beskrivs här.

Resurs- och meddelande-API:erna i den här artikeln introducerades i Windows App SDK 1.6.3. Använd en stabil version som stöds från Windows App SDK versionskanaler och testa på en Windows 11-enhet med en widgetvärd som stöder webbinnehåll.

C#-exemplen är fragment för en paketerad skrivbordswidgetprovider. Lägg till using Microsoft.Windows.Widgets.Providers; och using Windows.Storage.Streams; till providerns källfil. Fortsätt att implementera IWidgetProvider när du lägger till IWidgetResourceProvider eller IWidgetProviderMessage.

Ange innehålls-URL:en

Skicka din JSON-nyttolast med WidgetManager.UpdateWidget. Ange ett metadataobjekt med ett webUrl-fält som pekar på HTML-innehållet. Inkludera en Adaptive Card body som reservinnehåll för värdar som inte stöder inläsning av webbinnehåll, i stället för att lämna dessa värdar med en tom widget.

{
    "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"
    }
}

$host.isWebSupportedmall-egenskapen anger om värden stöder webbinnehåll. Använd den när du behöver anpassa reservpresentationen ytterligare. Mer information finns i egenskaper för Windows-widgetvärd.

Hantera resursbegäranden

Widgetprovidrar kan ange en filtersträng för webbbegäran för en widget i attributet WebRequestFilter för definitionselementet i leverantörens paketmanifestfil. När widgetinnehållet begär en resurs av URI som matchar filtret kommer begäran att fångas upp och omdirigeras till widgetproviderns implementering av IWidgetResourceProvider.OnResourceRequested.

Filtermönstret använder formatet som beskrivs i Matchningsmönster. Använd Punycode om det behövs. Filtret måste matcha det ursprung som anges i webUrl. Begäranden för alla innehållstyper omdirigeras när de matchar, så begränsa filtret till resurser som leverantören hanterar. Mer information finns i Xml-format för widgetproviderpaketmanifest.

För att hantera resursbegäranden måste widgetprovidrar implementera gränssnittet IWidgetResourceProvider .

internal class WidgetProvider : IWidgetProvider, IWidgetResourceProvider

I OnResourceRequested anger du WidgetResourceRequestedArgs.Response som en WidgetResourceResponse som innehåller resursen. I det här exemplet mappas en begärd URL till en paketerad image. Inkludera Assets\image.png som innehåll i ditt apppaket. RandomAccessStreamReference.CreateFromUri stöder schemat ms-appx, så att du kan skapa strömreferensen utan att vänta på en filsökning.

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;
    }
}

Det här synkrona exemplet behöver inte något uppskov. Om implementeringen inväntar arbete innan du ställer in svaret anropar du GetDeferral innan återanropet returneras och slutför det i ett finally-block. Hantera och rapportera asynkrona fel enligt appens princip för felhantering.

Om du inte anger någon respons hämtar systemet resursen från webben. Du kan ändra WidgetResourceRequest.Headers på args.Request före hämtningen. Lägg bara till autentiseringsuppgifter för begäranden från ursprung som du litar på. Enbart en filtermatchning är inte auktorisering för att skicka en token.

Hantera meddelanden till och från webbinnehåll

Om du vill ta emot strängmeddelanden från widgetens innehåll som har publicerats med hjälp av metoden window.chrome.webview.postMessage JavaScript kan widgetprovidrar implementera gränssnittet IWidgetProviderMessage och implementera metoden OnMessageReceived .

internal class WidgetProvider : IWidgetProvider, IWidgetProviderMessage

Lägg till återanropet till din leverantörsklass:

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

Skicka ett meddelande till webbinnehållet i en widget med WidgetManager.SendMessageToContent. Skicka widgetinstans-ID:t från WidgetContext.Id, inte definitions-ID:t från paketmanifestet. Flera instanser av samma definition har olika instans-ID:n.

Anropa följande hjälpfunktion från ett provideråteranrop och skicka WidgetContext för målinstansen, till exempel kontexten som tas emot av CreateWidget eller OnActionInvoked. Serialisera strukturerade meddelanden i stället för att konstruera JSON med stränginterpolation, så värden som innehåller citattecken eller omvänt snedstreck förblir giltiga.

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);
}

Webbinnehållet tar emot meddelandet som en sträng via händelsen på window.chrome.webviewmessage. Om du serialiserar JSON som i det här exemplet, tolka strängen i ditt webbinnehåll. Mer information finns i PostWebMessageAsString och WebView2-JavaScript API.

Begränsningar och krav

Important

Den här funktionen är endast tillgänglig för användare i Europeiska ekonomiska samarbetsområdet (EES).

Webbwidgetleverantörer är inte feedleverantörer. För flöden för instrumentpaneler och deras regionala krav, se Instrumentpaneler och flödesleverantörer. För den separata PWA-manifest- och service worker-implementeringsvägen, se Skapa PWA-drivna widgetar.

  • Uppdaterades senast