アダプティブ カード テンプレートの言語
テンプレートを使用すると、アダプティブ カードのレイアウトからデータを分離することができます。 テンプレート言語は、テンプレートの作成に使用される構文です。
アダプティブ カード テンプレートの概要については、こちらをお読みください。
重要
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"
}
]
}
テンプレートの作成
現在のところ、テンプレートの "パーツ" をまとめて作成することはサポートされていません。 ただし、いくつかのオプションが検討中で、近日中にさらに詳しくお知らせできる予定です。 ぜひご意見をお寄せください。
例
更新されたサンプル ページで、すべての種類の新しいテンプレート カードをご確認いただけます。