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

アダプティブ カード ウィジェットの場合は、アダプティブ カード JSON テンプレートと、必要に応じて別の JSON データ ペイロードを使用して UI と対話を定義します。 この記事では、データ バインディングと条件付きレイアウトを含むカウント ウィジェット テンプレートについて説明します。 Windows ウィジェットは URL から HTML を表示することもできます。そのコンテンツ形式については、Web ウィジェット プロバイダーを参照してください。

カウント ウィジェット

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

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

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

アダプティブ カード デザイナーは、カード JSON を編集し、そのレイアウトとデータ バインディングをプレビューするためのオンライン ツールです。 デザイナーを開いてテンプレートを操作します。

Important

デザイナーは、独自のレンダラーとホスト オプションを使用します。 それが提供する機能が Widgets Board でサポートされている、または Windows 固有の $host 値を提供しているものと想定しないでください。 このチュートリアルは、ホスト プリセットまたはホスト データ エディターに依存しません。 サポートされているサイズとテーマごとに、Windows ウィジェット プロバイダーの最終的なテンプレートをテストします。

次の図は、現在の Designer インターフェイスではなく、カードのレイアウトを示しています。

空のカードから始める

カード ペイロード エディターには、カードの JSON 定義が含まれています。 その内容をこの空白カードに置き換えてください:

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6",
    "body": []
}

サンプル データ エディターには、省略可能な JSON データ コンテキストが含まれています。 そのデータをテンプレートにバインドする方法については、「アダプティブ カード Template Language」を参照してください。

Windows ウィジェット ホストのプロパティ

ウィジェット ボードは、実行時にホスト プロパティを提供します。 テンプレート式では、${$host.widgetSize} のように、$host を使用してこれらを参照します。 これらのプロパティは、プロバイダーのデータ ペイロードとは別です。 widgetSize フィールドをサンプル データに追加しても、 $host.widgetSizeは設定されません。

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

カウント ウィジェットでは、ボタン用に 4 つの TextBlock 要素と 1 つの Action.Execute アクションが使用されます。

TextBlock 要素を追加する

デザイナーの要素パレットから 4 つの TextBlock 要素を追加するか、カード JSON に直接追加します。 条件付きレイアウトを適用する前に、次に示すように、カードには 4 行のテキストが含まれます。

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

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

カード ペイロード エディターで、body 配列を次のコードに置き換えます。

"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 つの $host.widgetSize 要素の 1 つが表示され、もう 2 つは非表示になります。 アダプティブ カードでサポートされる条件についての詳細は、Conditional layout with $whenを参照してください。

テンプレート式を評価しない場合、カードには 4 つのテキスト ブロックがすべて表示されます。

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

ウィジェット ボードで、 $host.widgetSize が "small" に設定されたテンプレートを評価すると、カウントの横に小さいサイズのテキスト ブロックのみが表示されます。

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

テンプレートをプロバイダーと統合した後、Widgets Board でピン留めされたウィジェットのサイズを変更し、一致するテキスト ブロックが表示されることを確認します。 ウィジェット プロバイダー マニフェストでテストする各サイズを宣言します。 Windows ホスト データのない汎用デザイナー プレビューでは、これらの条件を確認できません。

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

この例では、という名前のデータ プロパティを使用します。このプロパティは、最初の count で ${count} によって参照されます。 実行時に、プロバイダーはデータ ペイロードをウィジェット ホストに送信します。 デザイン時に、サンプル データ エディターで次の JSON を入力し、デザイナーのプレビューを有効にしてカウント バインドを確認します。 このサンプル データは、個別の Windows ホスト プロパティを提供しません。

{"count": "2"}

サンプル データとして {"count": "2"} を使用すると、テンプレートの展開時に、最初の TextBlock 内の ${count} が 2 に置き換えられます。 プレビューを有効にした後、デザイナーでこのバインドを確認します。 上記のように、Widgets Boardで個別の $host.widgetSize 条件を確認します。

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

ボタンを追加する

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

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

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

type プロパティで Action.Execute を選択すると、ウィジェット ホストがそのアクションをプロバイダーの OnActionInvoked コールバックに転送します。 URL に移動する場合は、代わりに Action.OpenUrl を使用します。このアクションでは、プロバイダーのコールバックは呼び出されません。 タイトルはボタンテキストを提供し、verbはプロバイダーが処理するアプリ定義の操作です。 $host.isUserContextAuthenticatedが false の場合は、Action.Execute 操作を提供しないでください。Action.OpenUrl のみがサポートされます。

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

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

次のコード一覧は、counting-widget 操作の最終的なテンプレートを示しています。 その Action.Execute ボタンには、認証されたユーザー コンテキストが必要です。 プロバイダーを使用してウィジェット ボードで動作を検証してください。Designer では、プロバイダーのインクリメント ハンドラーは実行されません。

{
    "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.Execute",
        "title": "Increment",
        "verb": "inc",
        "$when": "${!$host.isSettingsPayload}"
    },
    {
        "type": "Action.Execute",
        "title": "Update Setting",
        "verb": "setting",
        "$when": "${$host.isSettingsPayload}"
    }
],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6"
}