Web widget-szolgáltatók

A Windows-widgetben egy URL-címről kiszolgált HTML-t jeleníthet meg ahelyett, hogy a törzsét Adaptív kártyák segítségével határozná meg. A szolgáltató továbbra is egy adaptív kártya JSON-adattartalmát biztosítja, amely megadja a tartalom URL-címét. Kezdje a widget-szolgáltató implementálásával egy C# Windows-alkalmazás vagy egy widgetszolgáltató implementálásával egy win32-alkalmazásban (C++/WinRT), majd adja hozzá az itt ismertetett webes tartalomfunkciókat.

A cikkben szereplő erőforrás- és üzenetkezelési API-k az Windows App SDK 1.6.3-ban jelentek meg. Használja a Windows App SDK kiadási csatornáinak egyikéből származó jelenleg támogatott stabil kiadást, és tesztelje egy Windows 11 eszközön egy webes tartalmat támogató widget-gazdagéppel.

A C#-példák egy csomagolt asztali widget-szolgáltató töredékei. Adja hozzá a(z) using Microsoft.Windows.Widgets.Providers; és using Windows.Storage.Streams; elemeket a szolgáltató forrásfájljához. Továbbra is valósítsa meg az IWidgetProvider felületet, amikor hozzáadja az IWidgetResourceProvider vagy IWidgetProviderMessage elemet.

A tartalom URL-címének megadása

Küldje el a JSON-adatcsomagját a WidgetManager.UpdateWidget használatával. Adjon meg egy metaadat-objektumot egy webUrl-mezővel , amely a HTML-tartalomra mutat. Az adaptív kártya törzsét tartalék tartalomként adja meg azon hosztok számára, amelyek nem támogatják a webes tartalmak betöltését, ahelyett, hogy ezek a hosztok üres widgettel maradnának.

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

A $host.isWebSupported sablontulajdonság azt jelzi, hogy a gazdagép támogatja-e a webes tartalmat. Akkor használja, ha tovább kell igazítania a tartalék megjelenítést. További részletekért lásd: Windows widgetgazda tulajdonságai.

Erőforrás-kérelmek kezelése

A widget-szolgáltatók a szolgáltató csomagjegyzékfájljának Definíció elemének WebRequestFilter attribútumában megadhatnak egy webes kérés szűrősztringet egy widgethez. Amikor a widget tartalma olyan erőforrást kér URI alapján, amely megfelel a szűrőnek, a kérést elfogják és átirányítják a widget szolgáltatójának IWidgetResourceProvider.OnResourceRequested implementációjára.

A szűrőminta a Match Patterns alatt leírt formátumot használja. Szükség esetén használja a Punycode-ot . A szűrőnek meg kell egyeznie a webUrl által megadott eredettel. A rendszer az összes tartalomtípusra vonatkozó kéréseket átirányítja, ha egyeznek a szűrővel, ezért korlátozza a szűrőt a szolgáltató által kezelt erőforrásokra. További részletekért tekintse meg a widget-szolgáltató csomagjegyzékének XML-formátumát.

Az erőforrás-kérelmek kezeléséhez a vezérlőszolgáltatóknak implementálniuk kell az IWidgetResourceProvider felületet.

internal class WidgetProvider : IWidgetProvider, IWidgetResourceProvider

Az OnResourceRequested metódusban állítsa be a WidgetResourceRequestedArgs.Response értéket az erőforrást tartalmazó WidgetResourceResponse értékre. Ez a példa egy kért URL-címet egy becsomagolt image-re képez le. Foglalja bele a(z) Assets\image.png fájlt tartalomként az alkalmazáscsomagba. A RandomAccessStreamReference.CreateFromUri támogatja az ms-appx sémát, így anélkül hozhatja létre a streamhivatkozást, hogy megvárná a fájlkeresést.

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

Ehhez a szinkron példához nincs szükség elhalasztásra. Ha az implementáció a válasz beállítása előtt aszinkron munkára vár, hívja meg a GetDeferral függvényt, mielőtt a visszahívás visszatér, és fejezze be egy finally blokkban. Aszinkron hibák kezelése és jelentése az alkalmazás hibakezelési szabályzatának megfelelően.

Ha nem állít be válaszüzenetet, a rendszer lekéri az erőforrást a weből. Módosíthatja a WidgetResourceRequest.Headers értékét a args.Request elemén a lekérés előtt. Csak olyan eredetekhez tartozó kérésekhez adjon hozzá hitelesítő adatokat, amelyekben megbízik; a szűrőegyezés önmagában nem jogosít fel token küldésére.

Webes tartalmakba érkező és onnan érkező üzenetek kezelése

Ha sztringüzeneteket szeretne fogadni a widget tartalmából, amelyet a window.chrome.webview.postMessage JavaScript metódussal tettek közzé, a widget-szolgáltatók implementálhatják az IWidgetProviderMessage felületet, és implementálhatják az OnMessageReceived metódust .

internal class WidgetProvider : IWidgetProvider, IWidgetProviderMessage

Adja hozzá a callbacket a szolgáltató osztályához:

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

Üzenet küldése egy widget webes tartalmába a WidgetManager.SendMessageToContent használatával. Adja meg a widgetpéldány-azonosítót WidgetContext.Id, nem pedig a csomagjegyzék definícióazonosítóját. Egy definíció több példánya különböző példányazonosítókkal rendelkezik.

Hívja meg a következő segítőt egy szolgáltatói visszahívásból, és adja át a célpéldányhoz tartozó WidgetContextet, például a CreateWidget vagy az OnActionInvoked által kapott környezetet. Szerializálja a strukturált üzeneteket a JSON sztringinterpolációval történő létrehozása helyett, így az idézőjeleket vagy fordított perjeleket tartalmazó értékek érvényesek maradnak.

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

A webes tartalom sztringként fogadja az üzenetet a window.chrome.webviewmessage eseményen keresztül. Ha szerializálja a JSON-t, mint ebben a példában, elemezze a karakterláncot a webes tartalmában. További részletekért lásd: PostWebMessageAsString és a WebView2 JavaScript API.

Korlátozások és követelmények

Important

Ez a funkció csak az Európai Gazdasági Térség (EGT) felhasználói számára érhető el.

A web widget-szolgáltatók nem hírcsatorna-szolgáltatók. Az irányítópult-adatfolyamokról és azok regionális követelményeiről az Irányítópultok és az adatfolyam-szolgáltatók című témakörben olvashat. A különálló PWA-manifest és service worker implementálási útvonaláról további információt a PWA-alapú widgetek létrehozása című témakörben talál.

  • Utolsó frissítés időpontja: