Web 小工具提供者

你可以用 URL 提供的 HTML 來填充 Windows 小工具，而不是用 調適型卡片 定義其主體。 你的服務提供者仍然提供一個自適應卡片 JSON payload，指定內容網址。 先從在 C# Windows 應用程式 實作小工具提供者或在 win32 應用程式（C++/WinRT）實作小工具提供者開始，然後加入這裡所述的網頁內容功能。

本文中的資源與訊息 API 是在 Windows 應用程式 SDK 1.6.3 中引入的。 使用目前支援的穩定版，來自 Windows 應用程式 SDK 發布頻道，並在支援網頁內容的小工具主機 Windows 11 裝置上測試。

C# 範例是封裝式桌面小工具提供者的程式片段。 將 using Microsoft.Windows.Widgets.Providers; 和 using Windows.Storage.Streams; 新增至 provider 的原始檔案。 在新增 IWidgetResourceProvider 或 IWidgetProviderMessage 時，繼續實作 IWidgetProvider。

指定內容 URL

使用 WidgetManager.UpdateWidget 傳送 JSON payload。 指定一個帶有 webUrl 欄位的元資料物件，指向 HTML 內容。 為不支援載入網頁內容的主機提供 Adaptive Card 主體 作為備援內容，而不是讓這些主機只剩下空白小工具。

{
    "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.isWebSupported模板屬性表示主機是否支援網頁內容。 當你需要進一步調整備用呈現時，會用它。 詳情請參閱 Windows widget host 屬性。

處理資源要求

元件提供者可以在提供者套件清單檔案的Definition元素中，指定WebRequestFilter屬性的一個網路請求過濾字串。 每當元件內容透過 URI 請求與篩選條件相符的資源時，該請求會被攔截並重新導向元件提供者的 IWidgetResourceProvider.OnResourceRequested 實作。

篩選模式採用 比對模式中描述的格式。 必要時使用 Punycode 。 過濾器必須與 webURL 指定的來源相符。 所有內容類型的請求在匹配時都會被重新導向，因此請將過濾條件限定為你的提供者所處理的資源。 詳情請參閱 Widget provider package manifest XML 格式。

為了處理資源請求，元件提供者必須實作 IWidgetResourceProvider 介面。

internal class WidgetProvider : IWidgetProvider, IWidgetResourceProvider

在 OnResourceRequested 中，將 WidgetResourceRequestedArgs.Response 設為包含該資源的 WidgetResourceResponse 。 此範例將一個請求的 URL 映射到已打包的影像。 在你的應用程式包中包含 Assets\image.png 作為內容。 RandomAccessStreamReference.CreateFromUri 支援 ms-appx 配置，因此你可以在不等待檔案查詢的情況下建立串流參考。

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

這個同步範例不需要延後物件。 如果你的實作在設定回應前需要等待工作完成，請在回調回傳前呼叫 GetDeferral，並在 finally 區塊中將其完成。 依照應用程式的錯誤處理政策處理並回報非同步故障。

如果你沒有設定回應，系統會從網路上擷取資源。 你可以在該擷取作業之前修改 args.Request 上的 WidgetResourceRequest.Headers。 只在你信任的來源請求中新增憑證;僅有篩選條件匹配並不代表授權發送代幣。

處理來自 Web 內容的訊息

為了接收透過 window.chrome.webview.postMessage JavaScript 方法發布的元件內容中的字串訊息，元件提供者可以實作 IWidgetProviderMessage 介面並實作 OnMessageReceived 方法。

internal class WidgetProvider : IWidgetProvider, IWidgetProviderMessage

將回呼加入你的提供程序類別：

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

使用 WidgetManager.SendMessageToContent 向小工具的網頁內容發送訊息。 從 WidgetContext.Id 傳遞 widget instance ID，而不是從套件清單中傳出定義 ID。 同一定義的多個實例會有不同的實例 ID。

從提供者回調呼叫以下輔助程式，傳遞目標實例的 WidgetContext，例如 CreateWidget 或 OnActionInvoked 接收到的內容。 序列化結構化訊息，而非用字串插值建構 JSON，這樣包含引號或反斜線的值仍有效。

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

網頁內容透過 window.chrome.webviewmessage 事件以字串形式接收訊息。 如果你像這個範例中序列化 JSON，請解析網頁內容中的字串。 詳情請參閱 PostWebMessageAsString 及 WebView2 JavaScript API。

限制和需求

Important

這項功能僅適用於歐洲經濟區 （EEA） 的使用者。

網頁小工具供應商不是資訊提供者。 關於儀表板資訊流及其區域需求，請參見 儀表板與資訊來源提供者。 關於獨立的 PWA 資訊清單與 Service Worker 實作路徑，請參見 建構 PWA 驅動的小工具。

  • 上次更新時間：