如何让HTML渲染的Adaptive Card在Teams中对接任务模块？

核心原理 #

直接在Teams里发送的Adaptive Card，按钮点击由Teams客户端原生转发事件到你的微服务；而HTML渲染的卡片需要手动模拟这个事件触发流程——通过Teams JS SDK调用任务模块，同时传递原卡片的action参数给微服务，以此对齐原生卡片的效果。

具体实现步骤 #

• 引入Teams JS SDK
  确保React项目中已引入Teams JS SDK，未安装的话执行：

  npm install @microsoft/teams-js
  

• 监听Adaptive Card按钮点击事件
  不要依赖HTML原生点击事件，使用adaptivecards-react提供的onExecuteAction属性捕获按钮触发的Adaptive Card Action：

  import React, { useEffect } from 'react';
  import AdaptiveCard from 'adaptivecards-react';
  import * as microsoftTeams from '@microsoft/teams-js';
  
  const MyAdaptiveCard = () => {
    // 替换为你的实际Adaptive Card JSON
    const cardPayload = {
      "type": "AdaptiveCard",
      "version": "2.1",
      "actions": [
        {
          "type": "Action.OpenUrl",
          "title": "打开任务模块",
          "url": "https://your-task-service-url"
        },
        {
          "type": "Action.Submit",
          "title": "提交任务",
          "data": { "actionType": "submitTask", "payload": {} }
        }
      ]
    };
  
    const handleCardAction = async (action) => {
      // 确保Teams SDK已初始化
      await microsoftTeams.initialize();
  
      if (action.type === 'Action.OpenUrl') {
        // 调用Teams任务模块API，对齐原生卡片的打开逻辑
        microsoftTeams.tasks.startTask(
          {
            url: action.url,
            width: 600,
            height: 500,
            title: action.title
          },
          (taskResult) => {
            // 任务模块关闭后的回调，可同步结果到页面
            console.log('任务模块返回:', taskResult);
          }
        );
      } else if (action.type === 'Action.Submit') {
        // 向微服务发送Submit请求，和Bot接收的参数格式保持一致
        fetch('https://your-handler-service-url', {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            // 可选：带上Teams上下文信息做验证
            'Teams-Context': JSON.stringify(await microsoftTeams.getContext())
          },
          body: JSON.stringify(action.data)
        })
        .then(res => res.json())
        .then(response => {
          // 处理微服务返回结果
          console.log('提交响应:', response);
        });
      }
    };
  
    // 组件挂载时初始化Teams SDK
    useEffect(() => {
      microsoftTeams.initialize().catch(err => console.error('Teams SDK初始化失败:', err));
    }, []);
  
    return (
      <AdaptiveCard
        payload={cardPayload}
        onExecuteAction={handleCardAction}
        hostConfig={{
          // 配置样式匹配Teams默认风格
          fontFamily: '"Segoe UI", "Helvetica Neue", sans-serif',
          containerStyles: {
            default: {
              backgroundColor: '#ffffff'
            }
          }
        }}
      />
    );
  };
  
  export default MyAdaptiveCard;
  

• 确保Teams环境上下文有效性
  如果你的HTML页面嵌入在Teams Tab中，必须在组件挂载时初始化Teams SDK，这样才能正常调用任务模块API，同时可获取Teams上下文信息用于请求验证，防止非法请求。

• 微服务端兼容处理
  微服务需要同时兼容两种请求来源：

  • 原生Teams卡片的Bot Framework Activity请求
  • HTML卡片发送的直接HTTP请求
    统一请求参数格式，比如都以action.data中的内容作为核心请求体，避免重复开发处理逻辑。

关键注意事项 #

• 禁止直接绑定HTML按钮的onClick事件，adaptivecards-react会自动管理卡片DOM，通过onExecuteAction能更可靠地捕获Adaptive Card的标准Action事件。
• 如果页面不在Teams环境中（比如外部网页），无法使用Teams JS SDK调用任务模块，此时可直接跳转Action.OpenUrl指定的URL，或发送POST请求到Submit对应的服务地址。
• 若使用Action.Submit，需确保微服务端的权限验证逻辑能覆盖HTML请求的场景，比如通过Teams上下文信息做身份校验。

内容的提问来源于stack exchange，提问作者Parag Jadhav