使用適應卡設計器建立小部件範本

備註

某些資訊與發行前產品有關，在正式發行產品之前可能會大幅修改。 Microsoft 對於此處提供的資訊，不做任何明確或隱含的保證。

這很重要

從版本 25217 開始，此主題中描述的功能可在 Windows 的開發通道預覽版本中取得。 如需 Windows 預覽組建的資訊，請參閱 Windows 10 Insider Preview。

Windows 小工具的 UI 和互動是以調適型卡片 實現的。 每個 Widget 都提供一個視覺範本，還有一個選擇性的資料範本，這些範本是透過符合 Adaptive Cards 架構的 JSON 文件來定義的。 本文將逐步引導您完成建立簡單小工具範本的步驟。

計數小工具

本文中的範例是一個顯示整數值的簡單計數小工具，用戶可以通過點擊小工具介面中的按鈕來遞增這個值。 此範例範本會使用數據系結，根據數據內容自動更新UI。

應用程式必須實作小工具提供者，以產生和更新小工具範本和/或數據，並將其傳遞至小工具主機。 本文 在 win32 應用程式中實現小工具提供者 提供逐步指引，以實現我們在下列步驟中將產生的計算小工具提供者。

調適型卡片設計工具

調 適型卡片設計 工具是在線互動式工具，可讓您輕鬆地產生調適型卡片的 JSON 範本。 使用設計器，您可以在建置小工具範本時，即時查看渲染的視覺效果和資料綁定行為。 請遵循連結來開啟設計工具，此連結將用於本逐步解說中的所有步驟。

從預設建立空白範本

在頁面頂端，從 [選取主機應用程式] 下拉式清單中，選擇 [小工具面板]。 這會設定調適型卡片的容器大小，以符合小组件支援的大小。 請注意，小工具支援小型、中型和大型大小。 默認範本預設的大小是小型小工具的正確大小。 別擔心內容會超出邊界，我們將用專為適合小工具內部設計的內容來替換它。

頁面底部有三個文本編輯器。 標示為 的卡片負載編輯器 包含小工具 UI 的 JSON 定義。 標示為 範例資料編輯器 的編輯器包含 JSON，這些 JSON 可用來定義您的小工具的可選資料情境。 服務小工具渲染時，數據內容會動態系結至自適應卡片。 如需調適型卡片中數據系結的詳細資訊，請參閱 調適型卡片範本語言。

第三個文字編輯器被標示為 範例主機數據編輯器。 請注意，此編輯器可能會折疊在頁面的其他兩個編輯器下方。 如果是，請按兩下 [+] 展開編輯器。 Widget 主應用程式可以指定主機屬性，讓您在 Widget 範本中根據這些屬性值動態顯示不同的內容。 Widgets Board 支援下列主機屬性。

房產	價值觀	說明
host.widgetSize	「小」、「中」或「大」	釘選小工具的大小。
host.hostTheme	“淺色” 或 “深色”	顯示 Widgets 面板之裝置的目前主題。
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 的值可根據互動性限制來適當調整小工具的內容。

頁面頂端 [選取主機應用程式] 下拉式清單旁的 [容器大小] 和 [主題] 下拉式清單可讓您設定這些屬性，而不需在編輯器中手動編輯範例主機 JSON。

建立新的卡片

在頁面左上角，按兩下 [[新增卡片]。 在 建立 對話框中，選取 空白卡片。 您現在應該會看到一張空的自適應卡片。 您也會注意到範例數據編輯器中的 JSON 檔是空的。

我們將建立的計數小工具非常簡單，只包含 4 個 TextBlock 元素，以及一個動作，類型為 Action.Execute，用來定義小工具的按鈕。

新增 TextBlock 元素

將四個 TextBlock 元素從頁面左側的 Card 元素 窗格拖曳到預覽窗格中的空白自適應卡片上。 此時，小工具預覽看起來應該像下圖。 內容會再次溢出小工具的邊框，但這將會在接下來的步驟中修正。

實作條件式配置

卡片承載編輯器 已更新，以反映我們新增的 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\"}"
    }
]

在 Adaptive Cards 範本語言中，$when 屬性會指定當相關值評估為 true 時，顯示包含的元素。 如果值評估為 false，則不會顯示包含的元素。 在我們的範例中，在 主體 元素內，會依 屬性的值顯示三個 $host.widgetSize 元素中的一個，而另兩個則會被隱藏。 如需調適型卡片中支援之條件的詳細資訊，請參閱 $when條件式配置。

現在預覽看起來應該像下圖：

請注意，條件語句不會反映在預覽中。 這是因為設計師沒有模擬小工具主機的行為。 按兩下頁面頂端的 [預覽模式 ] 按鈕，以啟動模擬。 小工具預覽現在看起來像下圖：

從 [容器大小] 下拉式清單中，選取 "中" 並注意預覽切換為只顯示中等大小的 TextBlock。 預覽中的容器也會變更大小，示範如何使用預覽來確保UI符合每個支援大小的Widget容器。

系結至數據內容

我們的範例小工具會使用名為 「count」 的自定義狀態屬性。 您可以在目前的樣本中看到，第一個 TextBlock 的值包含變數參考 $count。 當小工具在 Widgets Board 中執行時，小工具提供者會負責組合數據承載，並將其傳遞至小工具主機。 在設計階段，您可以使用 範例數據編輯器 來製作資料負載的原型，並查看不同數值如何影響 Widget 的顯示。 以下列 JSON 取代空的數據承載。

{"count": "2"}

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

新增按鈕

下一個步驟是將按鈕新增至我們的小工具。 在小工具主機中，當使用者按下按鈕時，主機會向小工具提供者提出要求。 在此範例中，小工具提供者會遞增計數值，並傳回更新後的資料載荷。 由於這項作業需要小工具提供者，因此您無法在調適型卡片設計工具中檢視此行為，但您仍然可以使用設計工具來調整 UI 內按鈕的配置。

使用調適型卡片時，互動式元素會以 動作 元素定義。 在卡片承載編輯器中的 本文 元素後面，直接新增下列 JSON 區塊。 請務必在 body 元素的右方括號 （]） 後面加上逗號，否則設計工具會報告格式設定錯誤。

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

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

完整的小工具範本

下列程式代碼清單顯示 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"
    }
  ]
}

設定承載範例

下列程式代碼清單顯示 JSON 承載的簡單範例，該承載會使用 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.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"
}