アダプティブ カード テンプレート SDK

アダプティブ カード テンプレート SDK を使用すると、サポートされている任意のプラットフォームで カード テンプレート に実際のデータを簡単に設定できます。

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

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

1. バインド構文が {...} から ${...}に変更されました。
   • 例: "text": "Hello {name}" は次のようになります。 "text": "Hello ${name}"
2. JavaScript API にはEvaluationContextオブジェクトが含まれなくなりました。 expand関数にデータを渡すだけです。 詳細については、 SDK のページ を参照してください。
3. .NET API は、JavaScript API とより密接に一致するように再設計されました。 詳細については、以下を参照してください。

JavaScript

アダプティブカード テンプレート ライブラリは、npm と CDN を介して利用できます。 完全なドキュメントについては、パッケージのリンクを参照してください。

npm

npm install adaptivecards-templating

CDN

<script src="https://unpkg.com/adaptivecards-templating/dist/adaptivecards-templating.min.js"></script>

使用方法

次のサンプルでは、カードをレンダリングするために アダプティブカード ライブラリもインストールしていることを前提としています。

カードのレンダリングを計画していない場合は、 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());

.NET

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);

カスタム関数

カスタム関数は、事前構築済みの関数に加えて、アダプティブ式ライブラリに追加できます。

次の例では、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);

トラブルシューティング

質問 なぜexpand()の呼び出しでAdaptiveTemplateExceptionが発生するのでしょうか？
Ａ。 行に "<offending item>" のようなエラー メッセージが表示される場合、'<行番号>' の 形式が '$data : ' pair" に対して正しくありません。
"$data" に指定された値が、数値、ブール値、オブジェクト、配列などの有効な json であるか、アダプティブ テンプレート言語の正しい構文に従っており、エントリが行番号のデータ コンテキストに存在することを確認してください。

質問 expand()を呼び出すときにArgumentNullExceptionが発生するのはなぜですか？
Ａ。 エラー メッセージが表示される場合 は、親データ コンテキストが設定されているかどうかを確認するか、 '<offending item>' の null 以外の値を行 '<行番号>' に入力してください。
これは、要求されたデータ バインディングのデータ コンテキストが存在しないことを示します。 ルート データ コンテキストが設定されていることを確認してください。存在する場合は、行番号で示されているように、任意のデータ コンテキストが現在のバインディングで使用できることを確認してください。

質問 テンプレートで使用する場合に"2017-02-14T06:08:00Z" などの RFC 3389 形式の日付/時刻が TIME/DATE 関数で機能しないのはなぜですか?
Ａ。 .NET sdk nuget バージョン 1.0.0-rc.0 では、この動作が示されます。 この動作は、以降のリリースで修正されます。 json.Net のデシリアライザーは、既定の動作で日付/時刻書式指定文字列を変更しますが、これは以降のリリースで無効になります。 この例に示すように、formatDateTime() 関数を使用して日付/時刻文字列を RFC 3389 に書式設定するか、TIME/DATE 関数をバイパスして formatDateTime() を使用してください。 formatDateTime() の詳細については、 こちらをご覧ください。