アダプティブカードデザイナーを使用してウィジェットテンプレートを作成する

2025-06-10

注

一部の情報はプレリリース製品に関連しており、商用リリース前に大幅に変更される可能性があります。 Microsoft は、ここで提供される情報に関して明示的または黙示的な保証を行いません。

Von Bedeutung

このトピックで説明する機能は、ビルド 25217 以降の Windows の開発チャネルプレビュービルドで使用できます。 Windows のプレビュービルドの詳細については、Windows 10 Insider Previewを参照してください。

Windows ウィジェットの UI と相互作用は、アダプティブカード使用して実装されます。各ウィジェットには、ビジュアルテンプレートと、必要に応じて、アダプティブカードスキーマに準拠する JSON ドキュメントを使用して定義されたデータテンプレートが用意されています。この記事では、単純なウィジェットテンプレートを作成する手順について説明します。

この記事の例は、整数値を表示し、ユーザーがウィジェットの UI のボタンをクリックして値をインクリメントできるようにする単純なカウントウィジェットです。このテンプレート例では、データバインディングを使用して、データコンテキストに基づいて UI を自動的に更新します。

アプリはウィジェットプロバイダーを実装してウィジェットテンプレートやデータを生成および更新し、ウィジェットホストに渡す必要があります。 win32 アプリでウィジェットプロバイダーを実装記事では、以下の手順で生成するカウントウィジェットのウィジェットプロバイダーを実装するための詳細なガイダンスを提供します。

アダプティブカードデザイナー

アダプティブカードデザイナーは、アダプティブカードの JSON テンプレートを簡単に生成できるオンライン対話型ツールです。デザイナーを使用すると、ウィジェットテンプレートをビルドするときに、レンダリングされたビジュアルとデータバインディングの動作をリアルタイムで確認できます。リンクに従ってデザイナーを開きます。デザイナーは、このチュートリアルのすべての手順で使用されます。

プリセットから空のテンプレートを作成する

ページの上部にある ホストアプリの選択 ドロップダウンから、[ウィジェットボード] を選択します。これにより、アダプティブカードのコンテナーサイズがウィジェットでサポートされるサイズに設定されます。ウィジェットでは、小、中、および大のサイズがサポートされていることに注意してください。既定のテンプレートプリセットのサイズは、小さなウィジェットに適したサイズです。ウィジェット内に収まるように設計されたコンテンツに置き換えるため、コンテンツが境界線をオーバーフローしても心配しないでください。

ページの下部には 3 つのテキストエディターがあります。カードペイロードエディターラベルが付けられているものには、ウィジェットの UI の JSON 定義が含まれています。サンプルデータエディターラベルが付いたエディターには、ウィジェットの省略可能なデータコンテキストを定義する JSON が含まれています。データコンテキストは、ウィジェットのレンダリング時にアダプティブカードに動的にバインドされます。アダプティブカードのデータバインディングの詳細については、「アダプティブカードテンプレート言語」を参照してください。

3 番目のテキストエディターには、サンプルホストデータエディターラベルが付けられます。このエディターは、ページの他の 2 つのエディターの下に折りたたまれる場合があることに注意してください。その場合は、[+] をクリックしてエディターを展開します。ウィジェットホストアプリでは、ウィジェットテンプレートで使用できるホストプロパティを指定して、現在のプロパティ値に基づいてさまざまなコンテンツを動的に表示できます。 Widgets Board では、次のホストプロパティがサポートされています。

プロパティ	価値	説明
host.widgetSize	「小」、「中」、または「大」	ピン留めされたウィジェットのサイズ。
ホスト.テーマ	「明るい」または「暗い」	ウィジェットボードが表示されているデバイスの現在のテーマ。
host.isSettingsPayload	正または誤	この値が true の場合、ユーザーはウィジェットのコンテキストメニューの [ ウィジェットのカスタマイズ ] ボタンをクリックしました。このプロパティ値を使用して、カスタマイズ設定 UI 要素を表示できます。これは、 IWidgetProvider2.OnCustomizationRequested を使用してウィジェットプロバイダーアプリの JSON ペイロードを変更する代替方法です。詳細については、「ウィジェットのカスタマイズの実装」を参照してください。
host.isHeaderSupported	正または誤	この値が true の場合、ヘッダーのカスタマイズがサポートされます。詳細については、「 isHeaderSupported」を参照してください。
host.isHeader	正または誤	この値が true の場合、ホストはウィジェットヘッダーのレンダリング専用のペイロードを要求します。
host.isWebサポートされている	正または誤	この値が false の場合、ホストは現在、ウィジェットの Web コンテンツの読み込みをサポートしていません。この場合、Web ウィジェットにはウィジェットプロバイダーによって提供されるフォールバック JSON ペイロードが表示されますが、この値を使用してコンテンツをさらにカスタマイズできます。詳細については、「Web ウィジェットプロバイダー」を参照してください。
host.isUserContextAuthenticated	正または誤	この値が false の場合、サポートされているアクションは Action.OpenUrl のみです。対話機能の制限がある場合、 isUserContextAuthenticated の値を使用してウィジェットのコンテンツを適切に調整できます。

ページの上部にある [ホストアプリの選択] ドロップダウンの横にある [コンテナーのサイズ] ドロップダウンと [テーマ] ドロップダウンを使用すると、エディターでサンプルホスト JSON を手動で編集することなく、これらのプロパティを設定できます。

新しいカードを作成する

ページの左上隅にある [新しいカード]をクリックします。 [ 作成] ダイアログで、[空のカード]を選択します。空のアダプティブカードが表示されます。また、サンプルデータエディターの JSON ドキュメントが空であることがわかります。

作成するカウントウィジェットは非常に単純で、4 TextBlock 要素と、ウィジェットのボタンを定義する Action.Execute型のアクション 1 つだけで構成されます。

TextBlock 要素を追加する

ページの左側にある Card 要素 ペインからプレビューウィンドウの空のアダプティブカードにドラッグして、4 つの TextBlock 要素を追加します。この時点で、ウィジェットのプレビューは次の図のようになります。コンテンツはウィジェットの境界線の外側にもう一度オーバーフローしますが、これは次の手順で修正されます。

アダプティブカードが進行中です。新しい TextBlock というテキストを含む 4 行のウィジェットが表示されます。テキストの 4 行は、ウィジェットの下罫線をオーバーフローします。

条件付きレイアウトの実装

カードペイロードエディター は、追加した TextBlock 要素を反映するように更新されました。本文オブジェクトの JSON 文字列を次のように置き換えます。

"body": [
    {
        "type": "TextBlock",
        "text": "You have clicked the button ${count} times"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if medium",
        "$when": "${$host.widgetSize==\"medium\"}"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if small",
        "$when": "${$host.widgetSize==\"small\"}"
    },
    {
        "type": "TextBlock",
        "text": "Rendering only if large",
        "$when": "${$host.widgetSize==\"large\"}"
    }
]

アダプティブカードテンプレート言語では、$when プロパティは、関連する値が true に評価されたときに、含まれる要素が表示されることを指定します。値が false に評価された場合、含まれる要素は表示されません。この例の body 要素では、3 つの TextBlock 要素の 1 つが表示され、残りの 2 つは $host.widgetSize プロパティの値に応じて非表示になります。アダプティブカードでサポートされる条件の詳細については、「$whenを使用した条件付きレイアウト」を参照してください。

プレビューは次の図のようになります。

アダプティブカードが進行中です。前の手順で示した JSON ペイロードで指定されたテキストを含む 4 行のウィジェットが表示されます。条件付きで要素を非表示にする代わりに、すべての要素が表示され、画像の下の境界線がオーバーフローします。

条件付きステートメントはプレビューに反映されていないことに注意してください。これは、デザイナーがウィジェットホストの動作をシミュレートしていないためです。ページの上部にある [プレビューモードの] ボタンをクリックして、シミュレーションを開始します。ウィジェットのプレビューは次の図のようになります。

アダプティブカードが進行中です。JSON ペイロードで指定されたテキストを含む 2 行のウィジェットが表示されます。小さいサイズの TextBlock のみがレンダリングされます。

コンテナーサイズ ドロップダウンから [中] を選択し、プレビューが中サイズの TextBlock のみを表示するように切り替えることに注意してください。プレビューのコンテナーもサイズを変更し、プレビューを使用して、サポートされているサイズごとに UI がウィジェットコンテナー内に収まるようにする方法を示します。

データコンテキストにバインドする

このウィジェットの例では、"count" という名前のカスタム状態プロパティを使用します。現在のテンプレートでは、最初の TextBlock の値に変数参照 $countが含まれていることを確認できます。ウィジェットがウィジェットボードで実行されている場合、ウィジェットプロバイダーは、データペイロードをアセンブルしてウィジェットホストに渡す役割を担います。デザイン時に、サンプルデータエディター を使用して、データペイロードのプロトタイプを作成し、さまざまな値がウィジェットの表示にどのように影響するかを確認できます。空のデータペイロードを次の JSON に置き換えます。

{"count": "2"}

プレビューでは、最初の TextBlockのテキストに、カウント プロパティに指定された値が挿入されます。

アダプティブカードが進行中です。テキストの最初の行に、データペイロードの値 2 が含まれるようになりました。

ボタンを追加する

次の手順では、ウィジェットにボタンを追加します。ウィジェットホストでは、ユーザーがボタンをクリックすると、ホストはウィジェットプロバイダーに要求を行います。この例では、ウィジェットプロバイダーはカウント値をインクリメントし、更新されたデータペイロードを返します。この操作にはウィジェットプロバイダーが必要であるため、アダプティブカードデザイナーではこの動作を表示できませんが、デザイナーを使用して UI 内のボタンのレイアウトを調整することはできます。

アダプティブカードでは、対話型要素は アクション 要素で定義されます。カードペイロードエディターの本文要素の直後に、次の JSON ブロックを追加します。必ず、body 要素の右角かっこ (]) の後にコンマを追加してください。または、デザイナーが書式設定エラーを報告します。

,
"actions": [                                                      
    {                                                               
        "type": "Action.Execute",                               
        "title": "Increment",                                   
        "verb": "inc"                                           
    }                                                               
]

この JSON 文字列では、型プロパティは、表されるアクションの種類を指定します。ウィジェットでは、"Action.Execute" アクションの種類のみがサポートされます。 タイトル には、アクションのボタンに表示されるテキストが含まれています。動詞プロパティは、ウィジェットホストがウィジェットプロバイダーに送信して、アクションに関連付けられている意図を伝えるアプリ定義の文字列です。ウィジェットは複数のアクションを持つ場合があり、ウィジェットプロバイダーコードは要求の動詞の値をチェックして、実行するアクションを決定します。

最終的なアダプティブカード。2 行のテキスト行の後に、[増分] というテキストが表示された青いボタンが表示されます。

次のコード一覧は、JSON ペイロードの最終バージョンを示しています。

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6",
    "body": [
    {
      "type": "TextBlock",
      "text": "You have clicked the button ${count} times"
    },
    {
      "type": "TextBlock",
       "text": "Rendering Only if Small",
      "$when": "${$host.widgetSize==\"small\"}"
    },
    {
      "type": "TextBlock",
      "text": "Rendering Only if Medium",
      "$when": "${$host.widgetSize==\"medium\"}"
    },
    {
      "type": "TextBlock",
      "text": "Rendering Only if Large",
      "$when": "${$host.widgetSize==\"large\"}"
    }
    ],
   "actions": [
    {
      "type": "Action.Execute",
      "title": "Increment",
      "verb": "inc"
    }
  ]
}

設定ペイロードの例

次のコード一覧は、 host.isSettingsPayload プロパティを使用して、ユーザーが [ウィジェットのカスタマイズ ] ボタンをクリックしたときに別のコンテンツを表示する JSON ペイロードの簡単な例を示しています。

{
    "type": "AdaptiveCard",
    "body": [
    {
        "type": "Container",
        "items":[
            {
                "type": "TextBlock",
                "text": "Content payload",
                "$when": "${!$host.isSettingsPayload}"
            }
        ]
    },
    {
        "type": "Container",
        "items":[
            {
                "type": "TextBlock",
                "text": "Settings payload",
                "$when": "${$host.isSettingsPayload}"
            }
        ]
    }
],
"actions": [
    {
    "type": "Action.Submit",
    "title": "Increment",
    "verb": "inc",
    "$when": "${!$host.isSettingsPayload}"
    },
    {
    "type": "Action.Submit",
    "title": "Update Setting",
    "verb": "setting",
    "$when": "${$host.isSettingsPayload}"
    }
],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6"
}

次の方法で共有

アダプティブ カード デザイナーを使用してウィジェット テンプレートを作成する

カウント ウィジェット

アダプティブ カード デザイナー

プリセットから空のテンプレートを作成する

新しいカードを作成する

TextBlock 要素を追加する

条件付きレイアウトの実装

データ コンテキストにバインドする

ボタンを追加する

完全なウィジェット テンプレート

設定ペイロードの例

フィードバック

その他のリソース

カウントウィジェット

アダプティブカードデザイナー

データコンテキストにバインドする

完全なウィジェットテンプレート