アダプティブ カード テンプレート SDK
アダプティブ カード テンプレート SDK を使用すると、サポートされている任意のプラットフォームで実際のデータを使用してカード テンプレートを設定しやすくなります。
アダプティブ カード テンプレートの概要については、こちらをお読みください。
重要
2020 年 5 月リリース候補での破壊的変更
Microsoft は、テンプレートのリリースに向けて懸命に取り組んでおり、いよいよ最終段階に入りました。 リリースにあたり、細かな破壊的変更をいくつか加える必要がありました。
- バインディング構文が
{...}
から${...}
に変更されました。- たとえば、
"text": "Hello {name}"
が"text": "Hello ${name}"
になります。
- たとえば、
- JavaScript API に
EvaluationContext
オブジェクトが含まれなくなりました。 単にデータをexpand
関数に渡すだけです。 詳細については、SDK ページを参照してください。 - .NET API は、JavaScript API により近づくように再設計されました。 詳細については、以下を参照してください。
adaptivecards-templating ライブラリは、npm か CDN から入手できます。 完全なドキュメントについては、パッケージ リンクを参照してください。
npm install adaptivecards-templating
<script src="https://unpkg.com/adaptivecards-templating/dist/adaptivecards-templating.min.js"></script>
次のサンプルでは、カードをレンダリングするために adaptivecards ライブラリも既にインストールされていることを前提としています。
カードをレンダリングする予定がない場合は、parse
と render
のコードを削除できます。
import * as ACData from "adaptivecards-templating";
import * as AdaptiveCards from "adaptivecards";
// Define a template payload
var templatePayload = {
"type": "AdaptiveCard",
"version": "1.0",
"body": [
{
"type": "TextBlock",
"text": "Hello ${name}!"
}
]
};
// Create a Template instance from the template payload
var template = new ACData.Template(templatePayload);
// Expand the template with your `$root` data object.
// This binds it to the data and produces the final Adaptive Card payload
var cardPayload = template.expand({
$root: {
name: "Matt Hidinger"
}
});
// OPTIONAL: Render the card (requires that the adaptivecards library be loaded)
var adaptiveCard = new AdaptiveCards.AdaptiveCard();
adaptiveCard.parse(cardPayload);
document.getElementById('exampleDiv').appendChild(adaptiveCard.render());
dotnet add package AdaptiveCards.Templating
// Import the library
using AdaptiveCards.Templating;
var templateJson = @"
{
""type"": ""AdaptiveCard"",
""version"": ""1.2"",
""body"": [
{
""type"": ""TextBlock"",
""text"": ""Hello ${name}!""
}
]
}";
// Create a Template instance from the template payload
AdaptiveCardTemplate template = new AdaptiveCardTemplate(templateJson);
// You can use any serializable object as your data
var myData = new
{
Name = "Matt Hidinger"
};
// "Expand" the template - this generates the final Adaptive Card payload
string cardJson = template.Expand(myData);
事前に組み込まれている関数に加えて、カスタム関数も Adaptive Expression ライブラリに追加できます。
次の例では、stringFormat カスタム関数を追加し、その関数を使用して文字列を書式設定しています。
string jsonTemplate = @"{
""type"": ""AdaptiveCard"",
""version"": ""1.0"",
""body"": [{
""type"": ""TextBlock"",
""text"": ""${stringFormat(strings.myName, person.firstName, person.lastName)}""
}]
}";
string jsonData = @"{
""strings"": {
""myName"": ""My name is {0} {1}""
},
""person"": {
""firstName"": ""Andrew"",
""lastName"": ""Leader""
}
}";
AdaptiveCardTemplate template = new AdaptiveCardTemplate(jsonTemplate);
var context = new EvaluationContext
{
Root = jsonData
};
// a custom function is added
AdaptiveExpressions.Expression.Functions.Add("stringFormat", (args) =>
{
string formattedString = "";
// argument is packed in sequential order as defined in the template
// For example, suppose we have "${stringFormat(strings.myName, person.firstName, person.lastName)}"
// args will have following entries
// args[0]: strings.myName
// args[1]: person.firstName
// args[2]: strings.lastName
if (args[0] != null && args[1] != null && args[2] != null)
{
string formatString = args[0];
string[] stringArguments = {args[1], args[2] };
formattedString = string.Format(formatString, stringArguments);
}
return formattedString;
});
string cardJson = template.Expand(context);
Q. expand()
を呼び出す AdaptiveTemplateException が発生するのはなぜですか?
A. "行 '<行番号>' の '<問題のある項目>' が '$data : ' ペアの正しい形式ではありません" のようなエラー メッセージが表示される場合:
"$data" に指定されている値が、数値、ブール値、オブジェクト、配列などの有効な JSON であるか、アダプティブ テンプレート言語の正しい構文に従っていること、および、その行番号のデータ コンテキストにエントリが存在することをご確認ください。
Q. expand()
を呼び出す ArgumentNullException が発生するのはなぜですか?
A. "親データ コンテキストが設定されているかご確認ください。または、行 '<行番号>' の '<問題のある項目>' に対して null 以外の値を入力してください" のようなエラー メッセージが表示される場合:
これは、要求されたデータ バインディングのデータ コンテキストが存在しないことを示します。 ルート データ コンテキストが設定されていることをご確認ください。存在する場合は、行番号で示されている現在のバインドでデータ コンテキストが使用可能であることをご確認ください。
Q. RFC 3389 形式の日付/時刻 (例: "2017-02-14T06:08:00Z") をテンプレートと共に使用すると、TIME または DATE 関数で機能しないのはなぜですか?
A. .NET SDK NuGet バージョン 1.0.0-rc.0 でこの動作が発生します。 この動作は、今後のリリースで修正されます。 json.Net デシリアライザーの既定の動作で日付または時刻形式の文字列が変更され、今後のリリースで無効になります。 この例で示すように formatDateTime() 関数を使用して日付または時刻形式の文字列を RFC 3389 に設定するか、TIME または DATE 関数をバイパスして formatDateTime() のみを使用してください。 formatDateTime() の詳細については、こちらをご覧ください。