調適型卡片範本化 SDK

調適型卡片範本化 SDK 可讓您輕鬆地在任何支援平台上使用實際資料填入卡片範本。

請參閱此內容以取得調適型卡片範本化概觀

重要

2020 年 5 月發行候選版本中的重大變更

我們一直很努力地發行範本化，最終得以在家中大展身手！ 我們必須在發行結束時，進行一些次要的重大變更。

至 2020 年 5 月的重大變更

1. 繫結語法已從 {...} 變更為 ${...}。
   • 例如："text": "Hello {name}" 會變成 "text": "Hello ${name}"
2. JavaScript API 不再包含 EvaluationContext 物件。 只要將您的資料傳遞至 expand 函式即可。 如需完整詳細資料，請參閱 SDK 頁面。
3. 重新設計 .NET API 以使其更符合 JavaScript API。 如需完整詳細資料，請參閱下文。

JavaScript

adaptivecards-templating 程式庫可在 npm 上和透過 CDN 來取得。 如需完整文件，請參閱套件連結。

npm

npm install adaptivecards-templating

CDN

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

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

疑難排解

Q. 為什麼我會遇到 AdaptiveTemplateException 呼叫 expand()？
A. 如果您的錯誤訊息在行上看起來像是 ' < offending item > '，' < line number > ' 對於 '$data ： ' pair' 的格式不正確。
請確定提供給 「$data」 的值是有效的 json，例如 number、boolean、object 和 array，或遵循調適型範本語言的正確語法，而且專案存在於行號的資料內容中。

Q. 為什麼我會遇到 ArgumentNullException 呼叫 expand()？
A. 如果錯誤訊息看起來類似「檢查是否已設定父資料內容」，或請在行號 'line number > ' 輸入非 Null 值作為 「 << 違規專案 > 」。
其表示要求的資料繫結不存在任何資料內容。 請確定已設定根資料內容 (如果有的話)，確保所有資料內容都可供目前的繫結使用，如行號所指示。

Q. 為什麼與範本搭配使用時，RFC 3389 格式的日期/時間 (例如 "2017-02-14T06:08:00Z") 不適用於時間/日期函數？
A. .NET sdk nuget 版本 1.0.0-rc.0 會表現此行為。 後續版本中會修正此行為。 json.Net deserilizer 的預設行為會變更日期/時間格式字串，並會在後續版本中停用。 請使用 formatDateTime() 函式將日期/時間字串格式化為 RFC 3389，如此範例所示，或者您可以略過時間/日期函式，並只使用 formatDateTime()。 如需 formatDateTime() 的詳細資訊，請移至這裡。