Web 小组件提供程序

2025-06-10

在最新版本中，实现 Windows 小组件的应用可以选择使用从远程 URL 提供的 HTML 填充小组件内容。以前，小部件的内容仅能以从提供程序传递到小部件板的 JSON 负载中的自适应卡片架构格式提供。由于 Web 小组件提供程序仍必须提供自适应卡片 JSON 有效负载，因此应遵循在 C# Windows 应用中实现小组件提供程序或在 win32 应用中实现小组件提供程序（C++/WinRT）中的小组件提供程序的步骤。

指定内容 URL

小组件提供程序通过调用 WidgetManager.UpdateWidget 将 JSON 有效负载传递给小组件板。对于网页插件，与其提供定义插件内容的正文对象，不如指定一个空的正文对象，并且要包含一个带有webUrl字段的元数据对象，以指向将为插件提供 HTML 内容的 URL。

{ 
    "type": "AdaptiveCard", 
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", 
    "version": "1.6", 
    "body": [], 
    "metadata": 
    { 
        "webUrl": "https://www.contoso.com/widgetprovider.html" 
    } 
}

处理资源请求

小组件提供程序可以在其包清单文件的 Definition 元素的 WebRequestFilter 属性中为小组件指定一个 Web 请求筛选器字符串。每当小组件内容通过与筛选器匹配的 URI 请求资源时，都会截获请求并将其重定向到小组件提供程序的 IWidgetResourceProvider.OnResourceRequested 实现。

筛选器模式使用匹配模式中所述的格式表示。注册中的筛选器字符串必须在必要时使用 Punycode 。匹配时，将重定向所有内容类型，因此筛选器应仅解析为希望通过应用程序中的 IWidgetResourceProvider 获取的内容。有关小组件提供程序包清单格式的详细信息，请参阅小组件提供程序包清单 XML 格式。

若要处理资源请求，小组件提供程序必须实现 IWidgetResourceProvider 接口。

internal class WidgetProvider : IWidgetProvider, IWidgetResourceProvider

在 OnResourceRequested 方法的实现中，小组件提供程序可以通过将 WidgetResourceRequestedArgs.Response 属性设置为包含所请求资源的 WidgetResourceResponse 对象来提供请求的资源。异步获取资源时，提供程序应通过调用 WidgetResourceRequestedArgs.GetDeferral 请求延迟，然后在设置资源时完成延迟。

async void IWidgetResourceProvider.OnResourceRequested(WidgetResourceRequestedArgs args)
{
    var deferral = args.GetDeferral();

    if (args.Request.Uri.Length > 0)
    {
        if (args.Request.Uri == "https://contoso.com/logo-image")
        {
            string fullPath = Windows.ApplicationModel.Package.Current.InstalledPath + "/Assets/image.png";
            var file = await StorageFile.GetFileFromPathAsync(fullPath);
            var response = new WidgetResourceResponse(RandomAccessStreamReference.CreateFromFile(file), "OK", 200);
            response.Headers.Add("Content-Type", "image/png");
            args.Response = response;
        }
    }

    deferral.Complete();
}

如果提供程序未在传递到方法的 WidgetResourceRequestedArgs 对象上设置响应，系统将从 Web 检索资源。在这种情况下，提供程序可以选择修改 WidgetResourceRequestedArgs.Request 对象的 Headers 属性，例如提供用户上下文或令牌，系统将在从 Web 检索资源时使用更新的标头。

处理与 Web 内容之间的消息传递

若要从已使用 window.chrome.webview.postMessage JavaScript 方法发布的小组件内容接收字符串消息，小组件提供程序可以实现 IWidgetProviderMessage 接口并实现 OnMessageReceived 方法。

internal class WidgetProvider : IWidgetProvider, IWidgetProviderMessage
...
public void OnMessageReceived(WidgetMessageReceivedArgs args)
{
    Console.WriteLine($"Message received from widget {args.WidgetContext.Id}: {args.Message}");
}

小组件提供程序可以通过调用 WidgetManager.SendMessage 将消息发送到小组件的 Web 内容。必须提供消息发送到的小组件的 ID，该 ID 是在提供者的包配置文件中 Definition 元素的 Id 属性中指定的值。有关详细信息，请查看部件提供程序包清单 XML 格式。消息字符串可以是简单文本，也可以是 Web 内容解释的对象序列化形式。有关详细信息，请参阅 PostWebMessageAsString。

var message = $"{{ \"current_location\": \"{ ___location }\" }}";
WidgetManager.GetDefault().SendMessageToContent("Weather_Widget", message);

限制和要求

此功能仅适用于欧盟经济区（OEC）中的用户。在欧洲经济区，已安装的实现信息流提供商的应用可以在小组件板中提供内容信息流。

通过

指定内容 URL

处理资源请求

处理与 Web 内容之间的消息传递

限制和要求

其他资源