アダプティブカードテンプレートの言語

[アーティクル]
08/28/2023

テンプレートを使用すると、アダプティブカードのレイアウトからデータを分離することができます。テンプレート言語は、テンプレートの作成に使用される構文です。

アダプティブカードテンプレートの概要については、こちらをお読みください。

重要

2020 年 5 月リリース候補での破壊的変更

Microsoft は、テンプレートのリリースに向けて懸命に取り組んでおり、いよいよ最終段階に入りました。リリースにあたり、細かな破壊的変更をいくつか加える必要がありました。

2020 年 5 月時点での破壊的変更

バインディング構文が {...} から ${...} に変更されました
- たとえば、"text": "Hello {name}" が "text": "Hello ${name}" になります。

データへのバインド

テンプレートの作成は、カードの "非静的" コンテンツを "バインド式" に置き換えるのと同じほど簡単です。

静的カードペイロード

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

テンプレートペイロード

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

バインド式は、静的なコンテンツを配置できる任意の場所に配置できます
バインディング構文は ${ で始まり、} で終わります。例: ${myProperty}
オブジェクト階層のサブオブジェクトにアクセスするには、"ドット表記" を使用します。例: ${myParent.myChild}
正常な null 処理を行うことにより、オブジェクトグラフの null プロパティにアクセスした場合に例外が発生しないようにできます
配列内のキーまたは項目によってプロパティを取得するには、"インデクサー構文" を使用します。例: ${myArray[0]}

データの提供

テンプレートが利用できるようになったら、テンプレートに指定するデータを提供します。これには、次の 2 つの方法があります。

オプション A:テンプレートペイロード内にインラインで提供する。データを、AdaptiveCard テンプレートペイロード内にインラインで提供できます。これは、$data 属性をルートの AdaptiveCard オブジェクトに追加するだけで行えます。
オプション B:別個のデータオブジェクトとして提供する。このオプションでは、2 つの別個のオブジェクト template および data を、実行時にテンプレート SDK に提供します。こちらの方が一般的なアプローチです。なぜなら、通常は、まずテンプレートを作成し、その後に動的なデータを提供することが必要になるからです。

オプション 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

サンプルデータエディター - "プレビューモード" の場合にデータバインドカードを表示するには、ここでサンプルデータを指定します。このペインには、既存のサンプルデータからデータ構造を設定する小さなボタンがあります。
[Preview Mode]$プレビューモード$ - ツールバーのこのボタンを押すことで、編集エクスペリエンスとサンプルデータによるプレビューエクスペリエンスを切り替えることができます。
[Open Sample]$サンプルを開く$ - さまざまなサンプルペイロードを開くには、このボタンをクリックします。

高度なバインド

バインドスコープ

さまざまなバインドスコープにアクセスするための予約済みキーワードがいくつかあります。

{
    "${<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 は、$data が配列であるため、3 回繰り返されます。 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"
        }
    ]
}

組み込み関数

テンプレート言語が完成するには、さまざまなヘルパー関数が必要です。アダプティブカードテンプレートは、Adaptive Expression Language (AEL) 上に構築されています。これは、さまざまなプラットフォームで評価可能な式を宣言するためのオープンスタンダードです。また、これは "Logic Apps" の適切なスーパーセットでもあるため、Power Automate などと同様の構文を使用できます。

これは、組み込み関数のほんの一例にすぎません。

Adaptive Expression Language の事前組み込み関数の完全なリストをご確認ください。

条件付き評価

if(式, trueValue, falseValue)

if の例

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

JSON の解析

json(jsonString) - JSON 文字列の解析

json の例

次に示すのは、message プロパティが JSON でシリアル化された文字列である Azure DevOps の応答です。この文字列内の値にアクセスするには、テンプレートで 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"
        }
    ]
}

テンプレートの作成

現在のところ、テンプレートの "パーツ" をまとめて作成することはサポートされていません。ただし、いくつかのオプションが検討中で、近日中にさらに詳しくお知らせできる予定です。ぜひご意見をお寄せください。

例

更新されたサンプルページで、すべての種類の新しいテンプレートカードをご確認いただけます。

アダプティブ カード テンプレートの言語