使用「調適型卡片設計工具」建立小組件範本

發行項
03/19/2024

注意

針對發行前產品的部分相關資訊，在產品正式發行時可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

重要

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

Windows Widget 的 UI 和互動是使用調適型卡片來實作。每個小工具都會提供可視化範本，以及選擇性地使用符合「調適型卡片」結構的 JSON 文件來定義的資料範本。本文將逐步引導您完成建立簡單小工具範本的步驟。

本文中的範例是顯示整數值的簡易計數小工具，可讓使用者按一下小工具 UI 中的按鈕來遞增值。此範例範本會使用資料繫結，根據資料內容自動更新 UI。

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

調適型卡片設計工具

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

從預設建立空白範本

在頁面頂端的 [選取主機應用程式] 下拉式清單中，選擇 [Widgets Board]。這會根據小工具支援的尺寸，設定「調適型卡片」的容器大小。請注意，小工具支援小型、中型和大型大小。預設範本預設的大小是適合小型小工具的正確大小。如果內容超出邊界，不用擔心，因為我們將以適合小工具內部的設計內容來替換它。

頁面底部有三個文字編輯器。標示為卡片承載編輯器的編輯器，包含小工具 UI 的 JSON 定義。標示為範例資料編輯器的編輯器，包含可定義小工具選擇性資料內容的 JSON。轉譯小工具時，資料內容會動態繫結至「調適型卡片」。如需「調適型卡片」中資料繫結的詳細資訊，請參閱調適型卡片範本語言。

第三個文字編輯器會標示為範例主機資料編輯器。請注意，此編輯器可能會摺疊在該頁面的其他兩個編輯器下方。如果是這樣，請按一下 [+] 來展開編輯器。小工具主機應用程式，例如 Widgets Board 有兩個指出小工具的大小和主題的屬性。這些屬性名為 host.widgetSize 和 host.hostTheme。支援的大小為「小」、「中」和「大」。支援的主題為「淺色」和「深色」。您的小工具範本可以根據這些屬性的目前值，動態顯示不同的內容。若要查看小工具如何回應大小和主題的變更，您可以在編輯器中調整這些屬性的值，也可以在頁面頂端的 [選取主機應用程式] 下拉式清單旁的 [容器大小] 和 [主題] 下拉式清單中設定這些值。

建立新卡片

在頁面左上角，按一下 [新增卡片]。在 [建立] 對話方塊中，選取 [空白卡片]。您現在應該會看到空白的「調適型卡片」。您也會注意到範例資料編輯器中的 JSON 檔是空的。

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

新增 TextBlock 元素

從頁面左側的 [卡片元素] 窗格中將四個 [TextBlock] 元素拖曳到預覽窗格中的空白調適型卡片上。此時，小工具預覽看起來應該像下列影像。內容再次溢出小工具邊界，但這將在接下來的步驟中解決。

進行中的調適型卡片。它會顯示包含新 TextBlock 文字的四行小工具。四行文字會溢位小工具的下框線。

實作條件式版面配置

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

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

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

進行中的調適型卡片。它會顯示小工具，其中包含上一個步驟中所顯示 JSON 承載中指定的文字四行。除了有條件地隱藏元素，所有元素都是可見的，而且會溢位影像的下框線。

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

進行中的調適型卡片。它會顯示包含 JSON 承載中所指定文字的兩行小工具。只會轉譯小型大小的 TextBlock。

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

繫結至資料內容

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

{"count": "2"}

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

進行中的調適型卡片。第一行文字現在包含數據承載中的值 2。

新增按鈕

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

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

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

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

最後的調適型卡片。文字 Increment 的藍色按鈕會顯示在兩個文字行之後。

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

共用方式為

計數小工具