Web ウィジェット プロバイダー

アダプティブ カードを使用して本文を定義する代わりに、URL から提供される HTML をWindows ウィジェットに表示できます。 プロバイダーは引き続き、コンテンツ URL を指定するアダプティブ カード JSON ペイロードを提供します。 まず、C# Windows アプリでウィジェット プロバイダーを実装するか、win32 アプリ (C++/WinRT) でウィジェット プロバイダーを実装してから、ここで説明する Web コンテンツ機能を追加します。

この記事で扱うリソース API とメッセージング API は Windows アプリ SDK 1.6.3 で導入されました。 Windows アプリ SDK のリリース チャネルから現在サポートされている安定版を使用し、Web コンテンツに対応したウィジェット ホストを備える Windows 11 デバイスでテストしてください。

C# の例は、パッケージ化されたデスクトップ ウィジェット プロバイダー向けのコード断片です。 プロバイダーのソース ファイルに using Microsoft.Windows.Widgets.Providers; と using Windows.Storage.Streams; を追加します。 IWidgetResourceProvider または IWidgetProviderMessage を追加する場合も、引き続き IWidgetProvider を実装してください。

コンテンツ URL を指定する

WidgetManager.UpdateWidget を使用して JSON ペイロードを送信します。 HTML コンテンツを指す webUrl フィールドを持つメタデータ オブジェクトを指定します。 空のウィジェットをそれらのホストに残すのではなく、Web コンテンツの読み込みをサポートしていないホストのフォールバック コンテンツとして Adaptive Card の body を含めます。

{
    "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 テンプレート プロパティは、ホストが Web コンテンツをサポートしているかどうかを示します。 フォールバック プレゼンテーションをさらに調整する必要がある場合に使用します。 詳細については、Windows ウィジェット ホストのプロパティを参照してください。

リソース要求の処理

ウィジェット プロバイダーは、プロバイダーのパッケージ マニフェスト ファイルの Definition 要素の WebRequestFilter 属性で、ウィジェットの Web 要求フィルター文字列を指定できます。 ウィジェット コンテンツがフィルターに一致する URI によってリソースを要求するたびに、要求がインターセプトされ、ウィジェット プロバイダーの IWidgetResourceProvider.OnResourceRequested の実装にリダイレクトされます。

フィルター パターンでは、「 一致パターン」で説明されている形式が使用されます。 必要に応じて Punycode を使用します。 フィルターは webUrl で指定されたオリジンと一致する必要があります。 すべてのコンテンツ タイプに対する要求は一致した場合はリダイレクトされるため、フィルターをプロバイダーが処理するリソースに制限してください。 詳細については、「 ウィジェット プロバイダー パッケージ マニフェスト XML 形式」を参照してください。

リソース要求を処理するには、ウィジェット プロバイダーが IWidgetResourceProvider インターフェイスを 実装する必要があります。

internal class WidgetProvider : IWidgetProvider, IWidgetResourceProvider

OnResourceRequested で、WidgetResourceRequestedArgs.Response を、リソースを含む WidgetResourceResponse に設定します。 この例では、要求された URL をパッケージ化されたイメージに対応付けます。 アセット\image.png をアプリ パッケージのコンテンツとして含めてください。 RandomAccessStreamReference.CreateFromUri はms-appx スキームをサポートしているため、ファイルの検索を await せずにストリーム参照を作成できます。

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 ブロック内で延期した処理を完了してください。 アプリのエラー処理ポリシーに従って非同期エラーを処理して報告します。

応答を設定しない場合、システムは Web からリソースを取得します。 そのフェッチの前に、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 を使用して、ウィジェットの Web コンテンツにメッセージを送信します。 パッケージ マニフェストの定義 ID ではなく、 WidgetContext.Id からウィジェット インスタンス ID を渡します。 1 つの定義の複数のインスタンスに異なるインスタンス ID があります。

プロバイダーのコールバックから次のヘルパーを呼び出し、CreateWidget または OnActionInvoked で受け取ったコンテキストなど、対象インスタンスの WidgetContext を渡します。 引用符やバックスラッシュを含む値でも有効な JSON を維持できるよう、文字列補間で 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);
}

Web コンテンツは、window.chrome.webviewmessageイベントを通じて、メッセージを文字列として受信します。 この例のように JSON をシリアル化する場合は、Web コンテンツ側でその文字列を解析してください。 詳細については、PostWebMessageAsString と WebView2 JavaScript APIを参照してください。

制限事項と要件

Important

この機能は、欧州経済地域 (EEA) のユーザーのみが使用できます。

Web ウィジェット プロバイダーはフィード プロバイダーではありません。 ダッシュボードのフィードと地域ごとの要件については、「ダッシュボードとフィード プロバイダー」を参照してください。 個別の PWA マニフェストとサービス ワーカー実装パスについては、PWA ドリブン ウィジェットをビルドするを参照してください。

  • 最終更新: