自适应卡片模板化

2025-07-03

我们很高兴分享有助于创建、 重复使用和共享自适应卡片的新工具的预览版。

重要

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

模板化候选版本包括一些轻微的中断性变更，如果你一直在使用较旧的包，则应注意这些更改。有关详细信息，请参阅下文。

自2020年5月起的重大变更

绑定语法已从 {...} 更改为 ${...}.
- 例如： "text": "Hello {name}" 变为 "text": "Hello ${name}"
JavaScript API 不再包含对象 EvaluationContext 。只需将数据传递到 expand 函数即可。有关完整详细信息，请参阅 SDK 页。
重新设计了 .NET API 以更紧密地匹配 JavaScript API。有关完整详细信息，请参阅 SDK 页。

模板化如何帮助你

模板化使数据与自适应卡片中的布局分离。

它有助于设计一张卡片，然后用实际数据填充卡片

目前，无法使用自适应卡片设计器创建卡片，并利用该 JSON 将 动态内容填充到有效负载中。为了实现此目的，必须编写自定义代码来生成 JSON 字符串，或使用对象模型 SDK 生成表示卡片的 OM 并将其序列化为 JSON。在任一情况下，设计器都是一次性单向操作，在将卡片设计转换为代码后，以后调整卡片设计变得困难。

它使通过网络的传输数据量变小

假设可以在 客户端上直接组合模板和数据。这意味着，如果多次使用相同的模板，或者想要使用新数据对其进行更新，则只需将新数据发送到设备，并且可以重复使用同一模板。

它可帮助你从所提供的数据创建外观出色的卡片

我们认为自适应卡片很棒，但如果你不必为想要向用户显示的所有内容编写自适应卡片，该怎么办？使用模板服务（如下所述），我们可以创建一个世界，每个人都可以在任何类型的数据上参与、发现和共享模板。

在自己的项目、组织或整个 Internet 中共享。

AI 和其他服务可以改善用户体验

通过将数据与内容分开，它为 AI 和其他服务打开了一扇大门，以“推理”我们看到的卡片中的数据，并提高用户工作效率或帮助我们找到内容。

什么是自适应卡片模板化？

它由 3 个主要组件组成：

模板语言是用于创作模板的语法。设计器甚至让你可以在设计时通过包含“样本数据”来预览模板。
模板化 SDK 将存在于所有受支持的自适应卡片平台上。通过这些 SDK，可以在后端或直接在客户端上使用真实数据填充模板。
模板服务是一项概念证明服务，允许任何人查找、参与和共享一组已知模板。

模板语言

模板语言是用于创作自适应卡片模板的语法。

注释

请通过打开一个新选项卡来遵循以下示例进行操作。

https://adaptivecards.io/designer

单击 “预览模式 ”按钮，在设计模式和预览模式之间切换。

设计器屏幕截图

新更新的设计器添加了对创作模板的支持，并提供 示例数据 以在设计时预览卡片。

将以下示例粘贴到卡片有效负载编辑器窗格中：

EmployeeCardTemplate.json

{
    "type": "AdaptiveCard",
    "version": "1.0",
    "body": [
        {
            "type": "ColumnSet",
            "style": "accent",
            "bleed": true,
            "columns": [
                {
                    "type": "Column",
                    "width": "auto",
                    "items": [
                        {
                            "type": "Image",
                            "url": "${photo}",
                            "altText": "Profile picture",
                            "size": "Small",
                            "style": "Person"
                        }
                    ]
                },
                {
                    "type": "Column",
                    "width": "stretch",
                    "items": [
                        {
                            "type": "TextBlock",
                            "text": "Hi ${name}!",
                            "size": "Medium"
                        },
                        {
                            "type": "TextBlock",
                            "text": "Here's a bit about your org...",
                            "spacing": "None"
                        }
                    ]
                }
            ]
        },
        {
            "type": "TextBlock",
            "text": "Your manager is: **${manager.name}**"
        },
        {
            "type": "TextBlock",
            "text": "Your peers are:"
        },
        {
            "type": "FactSet",
            "facts": [
                {
                    "$data": "${peers}",
                    "title": "${name}",
                    "value": "${title}"
                }
            ]
        }
    ]
}

然后将下面的 JSON 数据粘贴到 示例数据编辑器中。

示例数据 帮助你准确地看到在运行时处理实际数据时卡片的显示效果。

EmployeeData

{
    "name": "Matt",
    "photo": "https://pbs.twimg.com/profile_images/3647943215/d7f12830b3c17a5a9e4afcc370e3a37e_400x400.jpeg",
    "manager": {
        "name": "Thomas",
        "title": "PM Lead"
    },
    "peers": [
        {
            "name": "Lei",
            "title": "Sr Program Manager"
        },
        {
            "name": "Andrew",
            "title": "Program Manager II"
        },
        {
            "name": "Mary Anne",
            "title": "Program Manager"
        }
    ]
}

单击 “预览模式 ”按钮。您应该能够根据上面提供的示例数据看到卡片渲染。随时可以调整示例数据并实时观看卡片更新。

恭喜，你刚刚创作了第一个自适应卡片模板！接下来，让我们了解如何使用实际数据填充模板。

详细了解模板语言

SDK 支持

模板化 SDK 使可以使用真实数据填充模板。

注释

目前，模板化 SDK 适用于 .NET 和 NodeJS。随着时间的推移，我们将为所有剩余的自适应卡平台（如 iOS、Android、UWP 等）发布模板化 SDK。

平台	包装	安装	文档
JavaScript		`npm install adaptivecards-templating`	文档
.NET		`dotnet add package AdaptiveCards.Templating`	文档

JavaScript 示例

下面的 JavaScript 显示了用于使用数据填充模板的一般模式。

var template = new ACData.Template({ 
    // Card Template JSON
});

var card = template.expand({
    $root: {
        // Data Fields
    }
});

// Now you have an AdaptiveCard ready to render!

C# 示例

下面的 C# 显示了用于使用数据填充模板的常规模式。

var template = new AdaptiveCards.Templating.AdaptiveCardTemplate(cardJson);
   
var card = template.Expand(new {Key="Value"});

// Now you have an AdaptiveCard ready to render!

详细了解模板化 SDK

模板服务

自适应卡片模板服务是一项概念证明服务，允许任何人查找、参与和共享一组已知模板。

如果要显示某些数据，但不想为它编写自定义自适应卡片，则它非常有用。

用于获取模板的 API 是直接的，但该服务实际上提供了更多功能，包括分析数据并查找可能适合你的模板的功能。

HTTP GET https://templates.adaptivecards.io/graph.microsoft.com/Profile.json

所有模板都是存储在 GitHub 存储库中的平面 JSON 文件，因此任何人都可以像任何其他开源代码一样参与这些文件。

详细了解卡片模板服务

接下来是什么以及发送反馈

模板化和数据分离使我们更接近我们的使命：“应用和服务之间的生态系统标准化内容交换”。我们在此领域有很多内容要推出，因此请保持关注，告诉我们它在 GitHub 上的效果！

通过