自适应卡片模板化 SDK

自适应卡片模板化 SDK 可以轻松地在任何受支持的平台上使用真实数据填充卡片模板。

请阅读此内容以了解自适应卡片模板化的概述。

重要

2020 年 5 月候选版中的中断性变更

我们一直在努力让模板功能发布，现在我们终于进入最后阶段了！接近发布时，我们必须进行一些轻微的重大变更。

自2020年5月起的重大变更

绑定语法已从 {...} 更改为 ${...}.
- 例如： "text": "Hello {name}" 变为 "text": "Hello ${name}"
JavaScript API 不再包含对象 EvaluationContext 。只需将数据传递到 expand 函数即可。有关完整详细信息，请参阅 SDK 页。
重新设计了 .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 自定义函数，并使用 funtion 设置字符串的格式。

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

故障排除

问：为什么我会遇到 AdaptiveTemplateException 调用 expand()？
答：如果错误消息类似于行中的“<冒犯项>”，则<“行号>”的格式不正确，表示“$data： 'pair”。
请确保为“$data”提供的值是有效的 JSON，例如数字、布尔值、对象和数组，或者遵循自适应模板语言的正确语法，并且该条目在行号的数据上下文中存在。

问：为什么在调用 expand() 时会遇到 ArgumentNullException？
答：如果错误消息类似于“检查是否已设置父数据上下文，或者请在行<”行号>“处输入”<冒犯项>“的非 null 值。
这表明请求的数据绑定不存在数据上下文。请确保已设置根数据上下文（如果存在），确保任何数据上下文都可用于当前绑定，如行号指示。

问：当与模板一起使用时，为何使用 RFC 3389 格式的日期/时间，例如“2017-02-14T06：08：00Z”不适用于 TIME/DATE 函数？
答： .NET sdk nuget 版本 1.0.0-rc.0 展示了此行为。后续版本中更正了此行为。 json.Net 反序列化程序的默认行为更改日期/时间格式字符串，并为后续版本禁用该字符串。请使用 formatDateTime（）函数将日期/时间字符串格式设置为 RFC 3389，如本示例所示，也可以绕过 TIME/DATE 函数，只需使用 formatDateTime（）。有关 formatDateTime（）的详细信息，请转到此处。

Last updated on 2025-07-03

通过