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

對於 Adaptive Card 元件，請使用調適型卡片 JSON 範本定義 UI 和互動，並可選擇另一個獨立的 JSON 資料載荷。這篇文章會帶你了解一個帶有資料綁定和條件式佈局的計數小工具範本。 Windows 小工具也能從 URL 顯示 HTML;關於該內容格式，請參見網頁小工具提供者。

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

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

調適型卡片設計師

調適型卡片 Designer 是一款線上工具，用於編輯卡片 JSON 並預覽其版面配置與資料綁定。打開設計器來處理範本。

Important

The Designer 使用自己的渲染器和主機選項。不要以為它提供的功能是 Widgets Board 所支援，或是它提供 Windows 專屬的 $host 值。這個逐步指南不依賴主機預設或主機資料編輯器。在 Windows 小工具提供者中測試最終範本，針對每個支援的大小與主題進行測試。

下方圖片展示的是卡片的配置，而非目前的 Designer 介面。

從一張空白卡開始

卡片有效載荷編輯器包含卡片的 JSON 定義。用這張空白卡片取代其內容：

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

範例資料編輯器包含可選的 JSON 資料上下文。關於如何將資料綁定到範本的資訊，請參閱調適型卡片 Template Language。

Widgets Board 在執行時提供主機屬性。透過 ${$host.widgetSize} 在模板表達式中參考它們，例如 $host。這些屬性與您提供者的資料負載是分開的；在範例資料中加入 widgetSize 欄位並不會設定 $host.widgetSize。

房產	價值	說明
host.widgetSize	「小型」、「中型」或「大型」	固定小工具的大小。
主機主題	「光明」或「黑暗」	顯示小工具板的裝置的目前主題。
host.isSettingsPayload	真或假	當此值為真時，使用者已點擊小工具右鍵選單中的「自訂小工具」按鈕。你可以用這個屬性值來顯示自訂設定的 UI 元素。這是使用 IWidgetProvider2.OnCustomizationRequested 來更改 widget 提供者應用程式中 JSON payload 的另一種方法。更多資訊請參閱「實作小工具自訂」。
host.isHeaderSupported	真或假	當此值為真時，則支援標頭自訂功能。欲了解更多資訊，請參閱 isHeaderSupported。
host.isHeader	真或假	當此值為真時，主機正在請求專門用於渲染小工具標頭的有效載荷。
host.isWebSupported	真或假	當此值為假時，主機目前不支援載入小工具的網頁內容。此時，網頁小工具會顯示小工具提供者提供的備用 JSON 有效載荷，但此值可用來進一步自訂內容。欲了解更多資訊，請參閱網頁小工具提供者
host.isUserContextAuthenticated (用戶上下文已驗證)	真或假	當此值為假時，唯一支援的動作是 Action.OpenUrl。 isUserContextAuthenticated 的值可以用來適當調整小工具內容，考慮到互動性限制。

計數小工具使用四個 TextBlock 元素和一個 Action.Execute 動作用於其按鈕。

新增 TextBlock 元素

從設計師的元素調色盤新增四個 TextBlock 元素，或直接在卡片 JSON 中加入四個 TextBlock 元素。在套用條件式排版前，卡片有四行文字，如下圖所示。

一張正在進行中的自適應卡。它顯示一個包含四行文字的小工具，內容為「New TextBlock」。這四行文字溢出了小工具的底部邊框。

條件式佈局的實作

在 Card payload 編輯器中，將 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 屬性指定當相關值值為真時，該元素會被顯示。若值值為假，則該包含元素未被顯示。在我們範例的主體元素中，三個 TextBlock 元素中的一個會顯示，另外兩個則隱藏，視屬性值 $host.widgetSize 而定。欲了解更多關於調適型卡片中支援的條件，請參閱使用 $when 的條件式佈局。

在未評估範本運算式的情況下，卡片會顯示所有四個文字區塊：

一張正在進行中的自適應卡。它會顯示一個包含前一步 JSON payload 指定文字的四行小工具。與其說是條件式隱藏元素，所有元素都可見並溢出圖片底部邊框。

當 Widgets Board 評估將模板 $host.widgetSize 設為 "small"時，只有小尺寸文字區塊與計數並列：

正在製作中的自適應卡片。它顯示一個小工具，其中包含在 JSON payload 中指定的兩行文字。只有小尺寸的 TextBlock 會被渲染出來。

將範本與提供者整合後，請調整 Widgets 板中釘選的小工具大小，並檢查是否出現對應的文字區塊。在 widget provider manifest 中宣告你想測試的每個大小。沒有 Windows 主機資料的通用 Designer 預覽無法驗證這些狀況。

綁定到資料上下文

範例中使用了一個名為 count 的資料屬性，並在第一個 ${count} 中由參考。執行時，提供者會將資料有效載荷傳送給元件主機。在設計時，請在 範例資料 編輯器中輸入以下 JSON，並啟用設計師預覽以檢查計數綁定。這些範例資料未提供獨立的 Windows 主機屬性。

{"count": "2"}

以 {"count": "2"} 作為範例資料時，範本擴充會在第一個 2 中以 ${count} 取代。啟用預覽後，在設計器中檢查這個綁定。請如上所述，查看 Widgets 面板中的各項 $host.widgetSize 條件。

一張自適應卡正在進行中。第一行文字現在包含資料中的值 2。

新增按鈕

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

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

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

type 屬性會設為 Action.Execute，widget 主機會將其轉送至你的提供者的 OnActionInvoked 回呼。改用 Action.OpenUrl 來導航 URL；它不會觸發那個提供者回呼。標題提供按鈕文字，動詞則是服務提供者處理的應用程式定義操作。當 $host.isUserContextAuthenticated 為 false 時，請不要提供 Action.Execute 互動;只支援 Action.OpenUrl 。

最後一張自適應卡。在兩行文字下面會顯示一個藍色按鈕，按鈕上面有“Increment”文字。

以下程式碼列表展示了計數元件互動的最終範本。它的 Action.Execute 按鈕需要經過認證的使用者上下文。請在 Widgets Board 中使用你的提供者進行驗證；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"
    }
  ]
}

設定負載範例

以下程式碼列表展示了一個簡單的 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"
}

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-10-27

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

計數小工具

調適型卡片 設計師