調適型卡片範本化 SDK
調適型卡片範本化 SDK 可讓您輕鬆地在任何支援平台上使用實際資料填入卡片範本。
請參閱此內容以取得調適型卡片範本化概觀
重要
2020 年 5 月發行候選版本中的重大變更
我們一直很努力地發行範本化,最終得以在家中大展身手! 我們必須在發行結束時,進行一些次要的重大變更。
- 繫結語法已從
{...}
變更為${...}
。- 例如:
"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);
除了預建函式以外,還可以將自訂函式新增至調適型運算式程式庫。
在下列範例中,會新增 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() 的詳細資訊,請移至這裡。