アダプティブ カード テンプレートの言語Adaptive Cards Template Language

• 05/18/2020
• • m
  • o

テンプレートを使用すると、アダプティブ カードの レイアウト から データ を分離することができます。Templating enables the separation of data from layout in your Adaptive Card. テンプレート言語は、テンプレートの作成に使用される構文です。The template language is the syntax used to author a template.

アダプティブ カード テンプレートの概要については、こちらをお読みください。Please read this for an overview of Adaptive Card Templating

2020 年 5 月時点での破壊的変更Breaking changes as of May 2020

1. バインディング構文が {...} から ${...} に変更されましたThe binding syntax changed from {...} to ${...}
   • たとえば、"text": "Hello {name}" が "text": "Hello ${name}" になります。For Example: "text": "Hello {name}" becomes "text": "Hello ${name}"

データへのバインドBinding to data

テンプレートの作成は、カードの "非静的" コンテンツを "バインド式" に置き換えるのと同じほど簡単です。Writing a template is as simple as replacing the "non-static" content of your card with "binding expressions".

静的カード ペイロードStatic card payload

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

テンプレート ペイロードTemplate payload

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

• バインド式は、静的なコンテンツを配置できる任意の場所に配置できますBinding expressions can be placed just about anywhere that static content can be
• バインディング構文は ${ で始まり、} で終わります。The binding syntax starts with ${ and ends with }. 例: ${myProperty}E.g., ${myProperty}
• オブジェクト階層のサブオブジェクトにアクセスするには、"ドット表記" を使用します。Use Dot-notation to access sub-objects of an object hierarchy. 例: ${myParent.myChild}E.g., ${myParent.myChild}
• 正常な null 処理を行うことにより、オブジェクト グラフの null プロパティにアクセスした場合に例外が発生しないようにできますGraceful null handling ensures you won't get exceptions if you access a null property in an object graph
• 配列内のキーまたは項目によってプロパティを取得するには、"インデクサー構文" を使用します。Use Indexer syntax to retrieve properties by key or items in an array. 例: ${myArray[0]}E.g., ${myArray[0]}

データの提供Providing the data

テンプレートが利用できるようになったら、テンプレートに指定するデータを提供します。Now that you have a template, you'll want to provide the data that makes it complete. これには、次の 2 つの方法があります。You have two options to do this:

1. オプション A:テンプレート ペイロード内にインラインで提供する。Option A: Inline within the template payload. データを、AdaptiveCard テンプレート ペイロード内にインラインで提供できます。You can provide the data inline within the AdaptiveCard template payload. これは、$data 属性をルートの AdaptiveCard オブジェクトに追加するだけで行えます。To do so, simply add a $data attribute to the root AdaptiveCard object.
2. オプション B:別個のデータ オブジェクトとして提供する。Option B: As a separate data object. このオプションでは、2 つの別個のオブジェクト template および data を、実行時に テンプレート SDK に提供します。With this option you provide two separate objects to the Templating SDK at runtime: the template and the data. こちらの方が一般的なアプローチです。なぜなら、通常は、まずテンプレートを作成し、その後に動的なデータを提供することが必要になるからです。This will be the more common approach, since typically you will create a template and want to provide dynamic data later.

オプション A:インライン データOption A: Inline data

{
    "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:データからテンプレートを分離するOption B: Separating the template from the data

より一般的なのは、データが含まれていない、再利用可能なカード テンプレートを作成する方法です。Alternatively (and more likely), you'll create a re-usable card template without including the data. このテンプレートは、ファイルとして保存し、ソース管理に追加できます。This template could be stored as a file and added to source control.

EmployeeCardTemplate.jsonEmployeeCardTemplate.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 を使用して実行時にデータを指定できます。Then load it up and provide the data at runtime using the Templating SDKs.

JavaScript の例JavaScript example

adaptivecards-templating パッケージを使用します。Using the adaptivecards-templating package.

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!

デザイナーのサポートDesigner Support

アダプティブ カード デザイナーが更新され、テンプレートがサポートされるようになりました。The Adaptive Card Designer has been updated to support templating.

こちらでお試しいただけます: https://adaptivecards.io/designerTry it out at: https://adaptivecards.io/designer

• [Sample Data Editor](サンプル データ エディター) - ここでサンプル データを指定すると、データがバインドされたカードを [Preview Mode](プレビュー モード) で表示できます。Sample Data Editor - Specify sample data here to view the data-bound card when in "Preview Mode." このペインには、既存のサンプル データから [Data Structure](データ構造) を設定するための小さなボタンがあります。There is a small button in this pane to populate the Data Structure from the existing sample data.
• [Preview Mode](プレビュー モード) - ツールバーのこのボタンを押すことで、編集エクスペリエンスとサンプル データによるプレビュー エクスペリエンスを切り替えることができます。Preview Mode - Press the toolbar button to toggle between the edit-experience and the sample-data-preview experience
• [Open Sample](サンプルを開く) - さまざまなサンプル ペイロードを開くには、このボタンをクリックします。Open Sample - click this button to open various sample payloads

高度なバインドAdvanced binding

バインド スコープBinding scopes

さまざまなバインド スコープにアクセスするための予約済みキーワードがいくつかあります。There are a few reserved keywords to access various binding scopes.

{
    "${<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"
}

データ コンテキストを要素に割り当てるAssigning a data context to elements

"データ コンテキスト" を要素に割り当てるには、$data 属性をその要素に追加します。To assign a "data context" to any element add a $data attribute to the element.

{
    "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}"
        }
    ]
}

配列内の項目を繰り返すRepeating items in an array

• アダプティブ カード要素の $data プロパティが 配列 にバインドされている場合、その 要素自体が配列内の各項目に対して繰り返されます。If an Adaptive Card element's $data property is bound to an array, then the element itself will be repeated for each item in the array.
• プロパティ値で使用されるすべてのバインド式 (${myProperty}) は、配列内の 個々の項目 にスコープ設定されます。Any binding expressions (${myProperty}) used in property values will be scoped to the individual item within the array.
• 文字列の配列にバインドする場合は、${$data} を使用して個々の文字列要素にアクセスします。If binding to an array of strings, use ${$data} to access the individual string element. 例: "text": "${$data}"E.g., "text": "${$data}"

たとえば、次の TextBlock は、$data が配列であるため、3 回繰り返されます。For example, the TextBlock below will be repeated 3 times since it's $data is an array. text プロパティが、配列内の個々のオブジェクトの name プロパティにどのようにバインドされているかにご注目ください。Notice how the text property is bound to the name property of an individual object within the array.

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

結果:Resulting in:

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

組み込み関数Built-in functions

テンプレート言語が完成するには、さまざまなヘルパー関数が必要です。No templating language is complete without a rich suite of helper functions. アダプティブ カード テンプレートは、Adaptive Expression Language (AEL) 上に構築されています。これは、さまざまなプラットフォームで評価可能な式を宣言するためのオープン スタンダードです。Adaptive Card Templating is built on top of the Adaptive Expression Language (AEL), which is an open standard for declaring expressions that can be evaluated on many different platforms. また、これは "Logic Apps" の適切なスーパーセットでもあるため、Power Automate などと同様の構文を使用できます。And it's a proper superset of "Logic Apps", so you can use similar syntax as Power Automate, etc.

これは、組み込み関数のほんの一例にすぎません。This is just a small sampling of the built-in functions.

Adaptive Expression Language の事前組み込み関数 の完全なリストをご確認ください。Check out the full list of Adaptive Expression Language Pre-built functions.

条件付き評価Conditional evaluation

• if(式, trueValue, falseValue)if(expression, trueValue, falseValue)

if の例if example

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

JSON の解析Parsing JSON

• json(jsonString) - JSON 文字列の解析json(jsonString) - Parse a JSON string

json の例json example

次に示すのは、message プロパティが JSON でシリアル化された文字列である Azure DevOps の応答です。This is an Azure DevOps response where the message property is a JSON-serialized string. この文字列内の値にアクセスするには、テンプレートで json 関数を使用する必要があります。In order to access values within the string, we need to use the json function in our template.

データData

{
    "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"
}

使用状況Usage

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

結果Resulting In

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

カスタム関数Custom functions

カスタム関数は、テンプレート SDK の API を介してサポートされています。Custom functions are supported via APIs in the Templating SDKs.

$when を使用した条件付きレイアウトConditional layout with $when

条件が満たされた場合に要素全体を削除するには、$when プロパティを使用します。To drop an entire element if a condition is met, use the $when property. $when が false と評価されると、その要素はユーザーに表示されません。If $when evaluates to false the element will not appear to the user.

{
    "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"
        }
    ]
}

テンプレートの作成Composing templates

現在のところ、テンプレートの "パーツ" をまとめて作成することはサポートされていません。Currently there is no support for composing template "parts" together. ただし、いくつかのオプションが検討中で、近日中にさらに詳しくお知らせできる予定です。But we are exploring options and hope to share more soon. ぜひご意見をお寄せください。Any thoughts here welcome!

例Examples

更新されたサンプル ページで、すべての種類の新しいテンプレート カードをご確認いただけます。Browse the updated Samples page to explore all sorts of new templated cards.