如何用JSON构建跨平台交互卡片？Adaptive Cards全指南

价值定位：为什么你需要Adaptive Cards？

你是否曾遇到这样的困境：为Microsoft Teams开发的通知卡片在Outlook中格式错乱，为Cortana技能设计的交互界面在Windows Timeline中完全无法显示？在多平台交互日益复杂的今天，如何确保信息展示的一致性已成为开发者面临的普遍挑战。

Adaptive Cards提供了一种革命性的解决方案——用JSON定义一次，在任何平台一致呈现。这个由微软开发的开源项目打破了平台间的交互壁垒，让你的内容在Teams、Outlook、Cortana等10+平台上保持统一的用户体验。

术语小贴士：Adaptive Card是一种JSON格式的卡片内容，包含结构化数据和布局信息，由客户端渲染器负责在不同平台上转化为原生UI元素。

实操检验清单

• [ ] 确认你的产品需要在至少两个以上平台展示交互内容
• [ ] 列出当前跨平台内容展示面临的主要问题
• [ ] 评估Adaptive Cards能否解决这些特定问题

场景化应用：三大核心领域解决方案

协作工具：Microsoft Teams中的动态工作流

当团队需要实时协作处理项目任务时，传统的文本通知往往无法传递复杂信息。Adaptive Cards让你在Teams中创建交互式任务卡片，实现状态更新、审批流程和数据收集的一体化。

技术卡片：Teams卡片核心特性

• 支持Action.Submit直接提交表单数据
• 可集成Bot Framework实现消息回调
• 支持自适应布局响应不同设备尺寸

{
  "type": "AdaptiveCard",
  "version": "1.5",
  "body": [
    {
      "type": "TextBlock",
      "text": "项目进度审批",
      "size": "Large",
      "weight": "Bolder"
    },
    {
      "type": "FactSet",
      "facts": [
        { "title": "项目名称", "value": "客户管理系统" },
        { "title": "当前进度", "value": "75%" },
        { "title": "负责人", "value": "张三" }
      ]
    }
  ],
  "actions": [
    {
      "type": "Action.Submit",
      "title": "批准",
      "data": { "action": "approve" }
    },
    {
      "type": "Action.Submit",
      "title": "拒绝",
      "data": { "action": "reject" }
    }
  ]
}

邮件系统：Outlook中的可操作消息

想象一下，当你收到会议邀请邮件时，无需打开日历应用，直接在邮件中就能完成接受/拒绝操作。Adaptive Cards让Outlook邮件从静态信息展示转变为交互式工作空间。

避坑指南：Outlook兼容性注意事项

• Windows版Outlook支持完整功能集
• Outlook Web Access部分支持Action.Submit
• Mac版Outlook对某些高级布局支持有限

智能助手：Cortana的可视化交互界面

当用户通过语音与Cortana交互时，Adaptive Cards提供直观的视觉反馈，将复杂信息结构化展示，支持用户通过点击快速完成操作，而无需记忆复杂的语音指令。

实操检验清单

• [ ] 根据业务需求选择适合的应用场景
• [ ] 确认目标平台的功能支持情况
• [ ] 设计符合用户习惯的卡片交互流程

技术实践：从零基础到深度集成

5分钟上手：零代码体验

你不需要编写任何代码就能体验Adaptive Cards的强大功能。Adaptive Cards Designer提供了可视化编辑界面，让你通过拖拽元素快速创建卡片原型。

快速体验步骤：

1. 访问Adaptive Cards Designer
2. 从左侧组件库拖拽TextBlock到画布
3. 在右侧属性面板修改文本内容和样式
4. 切换不同宿主预览效果（Teams/Outlook等）
5. 导出JSON代码或直接分享卡片

深度集成：开发指南

当你需要将Adaptive Cards集成到应用中时，官方SDK提供了完整的开发支持。以下是Node.js环境中的集成示例：

安装SDK：

npm install adaptivecards

渲染卡片代码：

// 导入AdaptiveCards库
const AdaptiveCards = require('adaptivecards');

// 初始化渲染器
const renderer = new AdaptiveCards.AdaptiveCardRenderer();

// 配置宿主风格（可选）
const hostConfig = new AdaptiveCards.HostConfig({
  fontFamily: "Segoe UI, Arial, sans-serif",
  fontSize: {
    small: 12,
    default: 14,
    medium: 16,
    large: 20,
    extraLarge: 24
  }
});
renderer.hostConfig = hostConfig;

// 定义卡片JSON
const cardJson = {
  "type": "AdaptiveCard",
  "version": "1.5",
  "body": [
    {
      "type": "TextBlock",
      "text": "Hello, Adaptive Cards!",
      "size": "Large"
    }
  ]
};

// 渲染卡片
const card = AdaptiveCards.AdaptiveCard.parse(cardJson);
const htmlElement = renderer.renderCard(card);

// 添加到DOM
document.body.appendChild(htmlElement);

避坑指南：版本兼容性

• 不同平台支持的Adaptive Cards版本不同
• 生产环境中建议使用version字段明确指定版本
• 复杂功能（如Table）需要v1.5及以上版本支持

实操检验清单

• [ ] 成功安装Adaptive Cards SDK
• [ ] 运行基础渲染示例
• [ ] 自定义宿主配置以匹配应用风格
• [ ] 实现卡片交互事件处理

生态拓展：平台集成与未来趋势

生态图谱：各平台集成要点

平台	最低支持版本	核心特性	限制
Microsoft Teams	v1.0	完整交互支持	无明显限制
Outlook	v1.2	部分交互支持	移动端功能有限
Cortana	v1.0	语音+视觉结合	布局复杂度受限
Windows Timeline	v1.0	活动记录展示	无交互能力
Web Chat	v1.5	全部最新特性	需自行实现渲染器

高级特性探索

Adaptive Cards 1.5及以上版本引入了表格组件，支持复杂数据展示：

表格组件示例：

{
  "type": "Table",
  "columns": [
    { "width": 20 },
    { "width": 50 },
    { "width": 30 }
  ],
  "firstRowAsHeaders": true,
  "rows": [
    [
      { "type": "TextBlock", "text": "ID" },
      { "type": "TextBlock", "text": "项目名称" },
      { "type": "TextBlock", "text": "状态" }
    ],
    [
      { "type": "TextBlock", "text": "P001" },
      { "type": "TextBlock", "text": "客户管理系统" },
      { "type": "TextBlock", "text": "进行中" }
    ]
  ]
}

决策树：如何选择合适的卡片类型

1. 信息展示为主 → 使用TextBlock+Image组合
2. 表单收集 → Input.*元素+Action.Submit
3. 数据列表 → Table（v1.5+）或ColumnSet
4. 复杂交互 → Action.ShowCard嵌套
5. 跨平台兼容 → 限制在v1.2特性集内

实操检验清单

• [ ] 确定目标集成平台及对应版本支持
• [ ] 选择适合业务需求的卡片类型
• [ ] 评估是否需要使用高级特性
• [ ] 制定跨平台兼容性测试计划

通过Adaptive Cards，你可以构建真正跨平台的交互体验，减少重复开发工作，确保用户在任何设备上都能获得一致的体验。无论是企业协作工具、邮件系统还是智能助手，Adaptive Cards都能帮助你打造更高效、更直观的用户界面。

现在就开始尝试吧——用JSON定义你的第一张Adaptive Card，开启跨平台交互的新可能！