調適型卡片範本語言

發行項
08/28/2023

範本化可讓您將調適型卡片中的資料與版面配置分隔開來。範本語言是用來撰寫範本的語法。

請參閱此內容以取得調適型卡片範本化概觀

重要

2020 年 5 月發行候選版本中的重大變更

我們一直很努力地發行範本化，最終得以在家中大展身手！我們必須在發行結束時，進行一些次要的重大變更。

至 2020 年 5 月的重大變更

繫結語法已從 {...} 變更為 ${...}
- 例如："text": "Hello {name}" 會變成 "text": "Hello ${name}"

繫結至資料

撰寫範本的方式很簡單，只要以「系結運算式」取代卡片的「非靜態」內容即可。

靜態卡承載

{
   "type": "TextBlock",
   "text": "Matt"
}

範本承載

{
   "type": "TextBlock",
   "text": "${firstName}"
}

放置靜態內容的位置即可放置系結運算式
繫結語法會以 ${ 開頭，並以 } 結尾。例如，${myProperty}
使用 點標記法 來存取物件階層的子物件。例如，${myParent.myChild}
正常的 Null 處理可確保當您存取物件圖形中的 Null 屬性時，不會收到例外狀況
使用索引子語法，依索引鍵或陣列中的項目來擷取屬性例如，${myArray[0]}

提供資料

既然您有了範本，就會想要提供讓其完整的資料。您有兩個選項可完成此動作：

選項 A：內嵌在範本承載內。您可以在 AdaptiveCard 範本承載內提供內嵌資料。若要這麼做，只需將 $data 屬性新增至根 AdaptiveCard 物件。
選項 B：當做個別的資料物件。使用此選項時，您會在執行階段提供兩個不同的物件給範本化 SDK：template 和 data。這會是較常用的方法，因為您通常會建立範本，並想要稍後提供動態資料。

選項 A：內嵌資料

{
    "type": "AdaptiveCard",
    "$data": {
        "employee": {
            "name": "Matt",
            "manager": { "name": "Thomas" },
            "peers": [{
                "name": "Andrew" 
            }, { 
                "name": "Lei"
            }, { 
                "name": "Mary Anne"
            }, { 
                "name": "Adam"
            }]
        }
    },
    "body": [
        {
            "type": "TextBlock",
            "text": "Hi ${employee.name}! Here's a bit about your org..."
        },
        {
            "type": "TextBlock",
            "text": "Your manager is: ${employee.manager.name}"
        },
        {
            "type": "TextBlock",
            "text": "3 of your peers are: ${employee.peers[0].name}, ${employee.peers[1].name}, ${employee.peers[2].name}"
        }
    ]
}

選項 B：將範本與資料分隔開來

或者 (且更有可能的是)，您也可以建立不含資料的可重複使用卡片範本。這個範本可以儲存為檔案，並新增至原始檔控制。

EmployeeCardTemplate.json

{
    "type": "AdaptiveCard",
    "body": [
        {
            "type": "TextBlock",
            "text": "Hi ${employee.name}! Here's a bit about your org..."
        },
        {
            "type": "TextBlock",
            "text": "Your manager is: ${employee.manager.name}"
        },
        {
            "type": "TextBlock",
            "text": "3 of your peers are: ${employee.peers[0].name}, ${employee.peers[1].name}, ${employee.peers[2].name}"
        }
    ]
}

然後，在執行階段使用範本化 SDK 加以載入並提供資料。

JavaScript 範例

使用 adaptivecards-templating 套件。

var template = new ACData.Template({ 
    // EmployeeCardTemplate goes here
});

// Specify data at runtime
var card = template.expand({
    $root: {
        "employee": {
            "name": "Matt",
            "manager": { "name": "Thomas" },
            "peers": [{
                "name": "Andrew" 
            }, { 
                "name": "Lei"
            }, { 
                "name": "Mary Anne"
            }, { 
                "name": "Adam"
            }]
        }
    }
});

// Now you have an AdaptiveCard ready to render!

設計工具支援

調適型卡片設計工具已更新為支援範本化。

試試看： https://adaptivecards.io/designer

範例資料編輯器 - 在此指定範例資料，以在「預覽模式」中檢視資料系結卡片。此窗格中有一個小按鈕可從現有的範例資料填入資料結構。
預覽模式 - 按下工具列按鈕，即可在編輯體驗和範例資料預覽體驗之間切換
開啟範例 - 按一下此按鈕即可開啟各種範例承載

進階繫結

繫結範圍

有幾個保留關鍵字可存取各種繫結範圍。

{
    "${<property>}": "Implicitly binds to `$data.<property>`",
    "$data": "The current data object",
    "$root": "The root data object. Useful when iterating to escape to parent object",
    "$index": "The current index when iterating"
}

將資料內容指派給元素

若要將「資料內容」指派給任何元素，請將 $data 屬性新增至元素。

{
    "type": "Container",
    "$data": "${mySubObject}",
    "items": [
        {
            "type": "TextBlock",
            "text": "This TextBlock is now scoped directly to 'mySubObject': ${mySubObjectProperty}"
        },
        {
            "type": "TextBlock",
            "text": "To break-out and access the root data, use: ${$root}"
        }
    ]
}

在陣列中重複項目

如果調適型卡片元素的 $data 屬性繫結至陣列，則系統會針對陣列中的每個項目重複此元素本身。
屬性值中所使用的任何繫結運算式 (${myProperty}) 都將侷限在陣列內的個別項目。
如果繫結至字串陣列，則請使用 ${$data} 來存取個別的字串元素。例如，"text": "${$data}"

例如，下面的 TextBlock 會重複 3 次，原因就是 $data 是陣列。請注意 text 屬性如何繫結至陣列中個別物件的 name 屬性。

{
    "type": "Container",
    "items": [
        {
            "type": "TextBlock",
            "$data": [
                { "name": "Matt" }, 
                { "name": "David" }, 
                { "name": "Thomas" }
            ],
            "text": "${name}"
        }
    ]
}

產生的結果：

{
    "type": "Container",
    "items": [ 
        {
            "type": "TextBlock",
            "text": "Matt"
        },
        {
            "type": "TextBlock",
            "text": "David"
        }
        {
            "type": "TextBlock",
            "text": "Thomas"
        }
    ]
}

內建函式

所有範本化語言一定都要使用一套豐富的 Helper 函式才能完成。調適型卡片範本化是建置在調適型運算式語言 (AEL) 之上，AEL 是一種開放式標準，用於宣告可在許多不同平台上評估的運算式。因為其是「邏輯應用程式」的適當超集，所以您可以使用類似的語法，如 Power Automate 等。

這只是內建函式的小型取樣。

查看調適型運算式語言預建函式的完整清單。

條件式評估

if(expression, trueValue, falseValue)

if 範例

{
    "type": "TextBlock",
    "color": "${if(priceChange >= 0, 'good', 'attention')}"
}

剖析 JSON

json(jsonString) - 剖析 JSON 字串

json 範例

這是 Azure DevOps 的回應，其中 message 屬性是經過 JSON 序列化的字串。為了存取字串內的值，我們需要在範本中使用 json 函式。

資料

{
    "id": "1291525457129548",
    "status": 4,
    "author": "Matt Hidinger",
    "message": "{\"type\":\"Deployment\",\"buildId\":\"9542982\",\"releaseId\":\"129\",\"buildNumber\":\"20180504.3\",\"releaseName\":\"Release-104\",\"repoProvider\":\"GitHub\"}",
    "start_time": "2018-05-04T18:05:33.3087147Z",
    "end_time": "2018-05-04T18:05:33.3087147Z"
}

使用方式

{
    "type": "TextBlock",
    "text": "${json(message).releaseName}"
}

產生的結果

{
    "type": "TextBlock",
    "text": "Release-104"
}

自訂函式

自訂函式可透過範本化 SDK 中的 API 來支援。

具有 `$when` 的條件式版面配置

若要在符合條件時放置整個元素，請使用 $when 屬性。如果 $when 評估為 false，則不會對使用者顯示元素。

{
    "type": "AdaptiveCard",
    "$data": {
        "price": "35"
    },
    "body": [
        {
            "type": "TextBlock",
            "$when": "${price > 30}",
            "text": "This thing is pricy!",
            "color": "attention",
        },
         {
            "type": "TextBlock",
            "$when": "${price <= 30}",
            "text": "Dang, this thing is cheap!",
            "color": "good"
        }
    ]
}

組成範本

目前不支援將範本「組件」組合在一起。但我們正在探索各種選項，希望能盡快與您分享。歡迎您對此提出任何想法！

範例

瀏覽已更新的範例頁面以探索各種新的範本化卡片。

共用方式為

調適型卡片範本語言

至 2020 年 5 月的重大變更

繫結至資料

靜態卡承載

範本承載

提供資料

選項 A：內嵌資料

選項 B：將範本與資料分隔開來

設計工具支援

進階繫結

繫結範圍

將資料內容指派給元素

在陣列中重複項目

內建函式

條件式評估

剖析 JSON

自訂函式

具有 `$when` 的條件式版面配置

組成範本

範例

其他資源

共用方式為

調適型卡片範本語言

至 2020 年 5 月的重大變更

繫結至資料

靜態卡承載

範本承載

提供資料

選項 A：內嵌資料

選項 B：將範本與資料分隔開來

設計工具支援

進階繫結

繫結範圍

將資料內容指派給元素

在陣列中重複項目

內建函式

條件式評估

剖析 JSON

自訂函式

具有 $when 的條件式版面配置

組成範本

範例

其他資源

具有 `$when` 的條件式版面配置