通过

Web 小组件提供程序

在最新版本中，实现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，这是提供程序包清单文件中 Definition 元素的 Id 属性中指定的值。 有关详细信息，请参阅 控件提供者软件包清单 XML 格式。 消息字符串可以是简单文本，也可以是 Web 内容解释的对象序列化形式。 有关详细信息，请参阅 PostWebMessageAsString。

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

限制和要求

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