使用 調適型卡片 Designer 來建立元件範本

Windows Widgets 的使用者介面與互動是以 調適型卡片實作。 每個小工具提供視覺化範本，並可選擇性地提供資料範本，這些範本皆以符合 調適型卡片 架構的 JSON 文件定義。 本文將引導你一步步建立一個簡單的小工具範本。

計數小工具

本文的範例是一個簡單的計數小工具，顯示整數值，使用者可透過點擊小工具介面中的按鈕來增加該值。 這個範例範本利用資料綁定，根據資料上下文自動更新使用者介面。

應用程式需要實作一個小工具提供者來產生和更新小工具範本和/或資料，並將它們傳給小工具主機。 文章 《在 Win32 應用程式中實作小工具提供者》提供了逐步指導，幫助實作我們將按照以下步驟產生的計數小工具的提供者。

調適型卡片 設計師

調適型卡片 Designer 是一款線上互動工具，可以輕鬆生成 調適型卡片 的 JSON 範本。 使用設計器，你可以在構建小工具範本時即時看到渲染出來的視覺效果和資料綁定行為。 點擊連結開啟設計器，該設計器將用於本次攻略中的所有步驟。

從預設建立一個空模板

在頁面頂端，從 「選擇主機應用程式 」下拉選單，選擇「小工具板」。 這會設定 Adaptive Card 容器大小，使其大小符合 widget 的支援。 請注意，小工具支援小型、中型和大型尺寸。 預設範本的大小是小工具的適當尺寸。 不用擔心內容會超出邊界，因為我們會用專為小工具設計的內容來替換。

頁面底部有三個文字編輯器。 標示為 卡片載荷編輯器 的內容包含您小工具介面的 JSON 定義。 名為 Sample Data Editor 的編輯器包含 JSON 定義了你小工具的可選資料上下文。 當 widget 被渲染時，資料上下文會動態地綁定到 Adaptive Card。 欲了解更多關於調適型卡片資料綁定的資訊，請參見 調適型卡片 模板語言。

第三個文字編輯器稱為 範例主機資料編輯器。 請注意，此編輯器可能會隱藏到頁面的其他兩個編輯器之下。 如果是的話，點擊 + 鍵展開編輯器。 小工具主機應用程式可以指定主機屬性，讓你在小工具範本中根據目前屬性值動態顯示不同內容。 小工具板支援以下主機屬性。

頁面頂端「選擇主機應用程式」下拉選單旁的容器大小和主題下拉選單，讓你能設定這些屬性，而不必手動編輯編輯器中的範例主機 JSON。

建立新卡片

在頁面左上角，點選 「新卡片」。 在 「建立 」對話框中，選擇 空白卡。 你現在應該會看到一張空的自適應卡。 你也會注意到範例資料編輯器中的 JSON 文件是空的。

我們將建立的計數小工具非常簡單，僅包含 4 個 TextBlock 元素和一個 Action.Execute 類型的動作，該動作定義了小工具的按鈕。

新增 TextBlock 元素

從頁面左側的卡片元素窗格拖曳到預覽窗格的空白自適應卡片上，新增四個 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 屬性指定當相關值值為真時，該元素會被顯示。 若值值為假，則該包含元素未被顯示。 在我們範例的 主體 元素中，三個 TextBlock 元素中的一個會顯示，另外兩個則隱藏，視屬性值 $host.widgetSize 而定。 欲了解更多關於 調適型卡片 中支援的條件，請參閱使用 $when 的條件式佈局。

現在預覽圖應該如下：

請注意，條件語句並未反映在預覽中。 這是因為設計者並沒有模擬小工具主機的行為。 點擊頁面頂端的 預覽模式 按鈕即可開始模擬。 小工具預覽現在看起來像以下圖片：

從 容器大小 下拉選單中選擇「中等」，並注意預覽畫面會切換成只顯示中等大小的 文字區塊 。 預覽中的容器會隨著大小的改變而調整，示範如何利用預覽來確保你的 UI 符合每一種支援大小的元件容器。

綁定到資料上下文

我們的範例小工具會使用一個名為「count」的自訂狀態屬性。 你可以在目前的範本中看到，第一個 TextBlock 的值包含變數參考 $count。 當小工具在 Widgets Board 執行時，小工具提供者負責組裝資料有效載荷並將其傳給小工具主機。 在設計時，你可以使用 範例資料編輯器 來原型化你的資料有效載荷，看看不同數值如何影響你的小工具顯示。 將空的資料有效載荷替換成以下 JSON。

{"count": "2"}

請注意，預覽現在會將第一個 TextBlock 的計數屬性指定值插入文字中。

新增按鈕

下一步是為我們的小工具新增一個按鈕。 在元件主機中，當使用者點擊按鈕時，主機會向元件提供者提出請求。 在此範例中，小工具提供者會遞增計數值並回傳更新的資料有效載荷。 因為這個操作需要 widget 提供者，你無法在 調適型卡片 Designer 中看到這個行為，但你仍然可以用 Designer 在 UI 中調整按鈕的配置。

使用調適型卡片，互動元素以 action 元素定義。 在卡片有效載荷編輯器中，直接在 主體 元素後加入以下 JSON 區塊。 務必在正文元素的閉合括號（]）後加上逗號，否則設計師會回報格式錯誤。

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

在這個 JSON 字串中， type 屬性指定所表示的動作類型。 小工具僅支援「Action.Execute」動作類型。 標題包含了動作按鈕上顯示的文字。 動詞屬性是應用程式定義的字串，元件主機會傳送給元件提供者，以傳達與動作相關的意圖。 一個元件可以有多個動作，元件提供者程式碼會檢查請求中動詞的值，以決定要採取什麼動作。

完整小工具範本

以下程式碼列表展示了 JSON payload 的最終版本。

{
    "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"
    }
  ]
}

設定負載範例

以下程式碼列表展示了一個簡單的 JSON payload 範例，該 payload 利用 host.isSettingsPayload 屬性，當使用者點擊 自訂小工具 按鈕時，顯示不同內容。

{
    "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"
}