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

注意

一部の情報はリリース前の製品に関する事項であり、正式版がリリースされるまでに大幅に変更される可能性があります。 Microsoft は、ここに記載されている情報について、明示または黙示を問わず、一切保証しません。

重要

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

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

カウント ウィジェット

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

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

アダプティブ カード Designer

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

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

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

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

3 番目のテキスト エディターには、 サンプル ホスト データ エディターというラベルが付けられます。 このエディターは、ページの他の 2 つのエディターの下に折りたたまれる場合があることに注意してください。 その場合は、+をクリックしてエディターを展開します。 ウィジェット ボードなどのウィジェット ホスト アプリには、ウィジェットのサイズとテーマを示す 2 つのプロパティがあります。 これらのプロパティの名前は host.widgetSize と host.hostTheme です。 サポートされているサイズは、"small"、"medium"、"large" です。 サポートされているテーマは、"light" と "dark" です。 ウィジェット テンプレートでは、これらのプロパティの現在の値に基づいてさまざまなコンテンツを動的に表示できます。 サイズとテーマの変更にウィジェットがどのように応答するかを確認するには、エディターでこれらのプロパティの値を調整するか、ページの上部にある [ホスト アプリの選択] ドロップダウンの横にある [コンテナー サイズ] ドロップダウンと [テーマ] ドロップダウンでこれらの値を設定することもできます。

新しいカードを作成する

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

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

TextBlock 要素を追加する

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

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

カード ペイロード エディターは、追加した TextBlock 要素を反映するように更新されました。 body オブジェクトの 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を使用した条件付きレイアウト」を参照してください。

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

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

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

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

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

{"count": "2"}

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

ボタンを追加する

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

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

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

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

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

次のコードリストは、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"
    }
  ]
}