卡片操作

项目
11/07/2024

Microsoft Teams 中机器人和消息扩展使用的卡片支持以下活动 CardAction 类型：

注意

当CardAction从连接器使用时，Microsoft 365 组的连接器卡的操作与 potentialActions 不同。

类型	Action
`openUrl`	在默认浏览器中打开 URL。
`messageBack`	从选择按钮或点击卡片的用户向机器人发送消息和有效负载。向聊天流发送单独的消息。
`imBack`	从选择按钮或点击卡片的用户向机器人发送消息。从用户发送到机器人的这一消息对所有对话参与者可见。
`invoke`	从选择按钮或点击卡片的用户向机器人发送消息和有效负载。此消息不可见。
`signin`	启动 OAuth 流，允许机器人连接安全服务。

注意

Teams 不支持上表中未列出的 CardAction 类型。
Teams 不支持 potentialActions 属性。
卡片操作不同于 Bot Framework 或 Azure 机器人服务中建议的操作。
如果将卡片操作用作消息扩展的一部分，则在卡片提交到频道之前，操作将不起作用。当卡片位于“撰写消息”框中时，操作将不起作用。

操作类型 openUrl

openUrl 操作类型指定要在默认浏览器中启动的 URL。

注意

机器人不会收到任何已选择按钮的通知。
URL 不支持包含数字的计算机名称。例如，不支持 userhostname123 等主机名。

通过 openUrl，你可以创建具有以下属性的操作：

属性	说明
`title`	显示为按钮标签。
`value`	此字段必须包含完整且格式正确的 URL。

以下代码显示 JSON 中的 openUrl 操作类型的示例：

{
    "type": "openUrl",
    "title": "Tabs in Teams",
    "value": "https://msdn.microsoft.com/microsoft-teams/tabs"
}

以下代码显示 C# 中的 openUrl 操作类型的示例：

var button = new CardAction()
{
    Type = ActionTypes.OpenUrl,
    Title = "Tabs in Teams",
    Value = "https://learn.microsoft.com/microsoftteams/platform/"
};

以下代码显示 JavaScript 中的 openUrl 操作类型的示例：

CardFactory.actions([
{
    type: 'openUrl',
    title: 'Tabs in Teams',
    value: 'https://learn.microsoft.com/microsoftteams/platform/'
}])

操作类型 messageBack

通过 messageBack，你可以创建具有以下属性的完全自定义操作：

属性	说明
`title`	显示为按钮标签。
`displayText`	可选。执行操作时由用户在聊天流中使用。此文本不会发送到机器人。
`value`	执行操作时发送到机器人。可以对操作的上下文进行编码，例如唯一标识符或 JSON 对象。
`text`	执行操作时发送到机器人。使用此属性可简化机器人开发。代码可以检查单个顶级属性以调度机器人逻辑。

的灵活性 messageBack 意味着代码不能仅仅通过使用 displayText在历史记录中留下可见的用户消息。

以下代码显示 JSON 中的 messageBack 操作类型的示例：

{
  "buttons": [
    {
    "type": "messageBack",
    "title": "My MessageBack button",
    "displayText": "I clicked this button",
    "text": "User just clicked the MessageBack button",
    "value": "{\"property\": \"propertyValue\" }"
    }
  ]
}

value 属性可以是序列化的 JSON 字符串或 JSON 对象。

以下代码显示 C# 中的 messageBack 操作类型的示例：

var button = new CardAction()
{
    Type = ActionTypes.MessageBack,
    Title = "My MessageBack button",
    DisplayText = "I clicked this button",
    Text = "User just clicked the MessageBack button",
    Value = "{\"property\": \"propertyValue\" }"
};

以下代码显示 JavaScript 中的 messageBack 操作类型的示例：

CardFactory.actions([
{
    type: 'messageBack',
    title: "My MessageBack button",
    displayText: "I clicked this button",
    text: "User just clicked the MessageBack button",
    value: {property: "propertyValue" }
}])

入站消息示例

replyToId 包含卡片操作来自的消息的 ID。如果要更新消息，请使用它。

以下代码显示入站消息的示例：

{
   "text":"User just clicked the MessageBack button",
   "value":{
      "property":"propertyValue"
   },
   "type":"message",
   "timestamp":"2017-06-22T22:38:47.407Z",
   "id":"f:5261769396935243054",
   "channelId":"msteams",
   "serviceUrl":"https://smba.trafficmanager.net/amer-client-ss.msg/",
   "from":{
      "id":"29:102jd210jd010icsoaeclaejcoa9ue09u",
      "name":"John Smith"
   },
   "conversation":{
      "id":"19:malejcou081i20ojmlcau0@thread.skype;messageid=1498171086622"
   },
   "recipient":{
      "id":"28:76096e45-119f-4736-859c-6dfff54395f7",
      "name":"MyBot"
   },
   "entities":[
      {
        "locale": "en-US",
        "country": "US",
        "platform": "Windows",
        "timezone": "America/Los_Angeles",
        "type": "clientInfo" 
      }
   ],
   "channelData":{
      "channel":{
         "id":"19:malejcou081i20ojmlcau0@thread.skype"
      },
      "team":{
         "id":"19:12d021jdoijsaeoaue0u@thread.skype"
      },
      "tenant":{
         "id":"bec8e231-67ad-484e-87f4-3e5438390a77"
      }
   },
        "replyToId": "1575667808184",
}

操作类型 imBack

imBack 操作会触发向机器人返回消息，就像用户在正常聊天消息中键入一样。频道中的用户和所有其他用户都可以看到按钮响应。

通过 imBack，你可以创建具有以下属性的操作：

属性	说明
`title`	显示为按钮标签。
`value`	此字段必须包含聊天中使用的文本字符串，因此会发送回机器人。这是在机器人中处理以执行所需逻辑的消息文本。

注意

value 字段是一个简单的字符串。不支持格式化或隐藏字符。

以下代码显示 JSON 中的 imBack 操作类型的示例：

{
    "type": "imBack",
    "title": "More",
    "value": "Show me more"
}

以下代码显示 C# 中的 imBack 操作类型的示例：

var button = new CardAction()
{
    Type = ActionTypes.ImBack,
    Title = "More",
    Value = "Show me more"
};

以下代码显示 JavaScript 中的 imBack 操作类型的示例：

CardFactory.actions([
{
    type: "imBack",
    title: "More",
    value: "Show me more"
}])

操作类型 invoke

该 invoke 操作用于调用对话 (TeamsJS v1.x) 中称为任务模块。

invoke 操作包含三个属性，即 type、title 和 value。

通过 invoke，你可以创建具有以下属性的操作：

属性	说明
`title`	显示为按钮标签。
`value`	此属性可以包含字符串、字符串化 JSON 对象或 JSON 对象。

以下代码显示 JSON 中的 invoke 操作类型的示例：

{
    "type": "invoke",
    "title": "Option 1",
    "value": {
        "option": "opt1"
    }
}

当用户选择该按钮时，机器人会收到包含一些其他信息的 value 对象。

注意

活动类型是 invoke，而不是 activity.Type == "invoke" 的 message。

以下代码显示 C# 中的 invoke 操作类型的示例：

var button = new CardAction()
{
    Title = "Option 1",
    Type = "invoke",
    Value = "{\"option\": \"opt1\"}"
};

以下代码显示 Node.js 中的 invoke 操作类型的示例：

CardFactory.actions([
{
    type: "invoke",
    title: "Option 1",
    value: {
        option: "opt1"
    }
}])

传入调用消息的示例

顶级 replyToId 属性包含卡片操作来自的消息的 ID。如果要更新消息，请使用它。

以下代码显示传入调用消息的示例：

{
    "type": "invoke",
    "value": {
        "option": "opt1"
    },
    "timestamp": "2017-02-10T04:11:19.614Z",
    "localTimestamp": "2017-02-09T21:11:19.614-07:00",
    "id": "f:6894910862892785420",
    "channelId": "msteams",
    "serviceUrl": "https://smba.trafficmanager.net/amer-client-ss.msg/",
    "from": {
        "id": "29:1Eniglq0-uVL83xNB9GU6w_G5a4SZF0gcJLprZzhtEbel21G_5h-
    NgoprRw45mP0AXUIZVeqrsIHSYV4ntgfVJQ",
        "name": "John Doe"
    },
    "conversation": {
        "id": "19:97b1ec61-45bf-453c-9059-6e8984e0cef4_8d88f59b-ae61-4300-bec0-caace7d28446@unq.gbl.spaces"
    },
    "recipient": {
        "id": "28:8d88f59b-ae61-4300-bec0-caace7d28446",
        "name": "MyBot"
    },
    "entities": [
        {
            "locale": "en-US",
            "country": "US",
            "platform": "Web",
            "type": "clientInfo"
        }
    ],
    "channelData": {
        "channel": {
            "id": "19:dc5ba12695be4eb7bf457cad6b4709eb@thread.skype"
        },
        "team": {
            "id": "19:712c61d0ef384e5fa681ba90ca943398@thread.skype"
        },
        "tenant": {
            "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
        }
    },
    "replyToId": "1575667808184"
}

signin 操作类型启动允许机器人与安全服务连接的 OAuth 流。有关详细信息，请参阅机器人中的身份验证流。

Teams 还支持仅由自适应卡片使用的自适应卡片操作。

以下代码显示 JSON 中的 signin 操作类型的示例：

{
"type": "signin",
"title": "Click me for signin",
"value": "https://signin.com"
}

以下代码显示 C# 中的 signin 操作类型的示例：

var button = new CardAction()
{
    Type = ActionTypes.Signin,
    Title = "Click me for signin",
    Value = "https://signin.com"
};

以下代码显示 JavaScript 中的 signin 操作类型的示例：

CardFactory.actions([
{
    type: "signin",
    title: "Click me for signin",
    value: "https://signin.com"
}])

自适应卡片操作

自适应卡片支持以下六种操作类型：

Action.OpenUrl：打开指定的 URL。
Action.Submit：将提交操作的结果发送到机器人。
Action.ShowCard：调用对话并将子卡呈现到该对话中。仅当设置为 popup 时 ShowCardActionMode ，才需要处理此问题。
Action.ToggleVisibility：显示或隐藏卡中的一个或多个元素。
Action.Execute：收集输入字段，与可选数据字段合并，并将事件发送到客户端。
Action.ResetInputs：重置自适应卡片中输入的值。

Action.Submit

Action.Submit type 用于收集输入、合并 data 属性以及向机器人发送事件。当用户选择提交操作时，Teams 会向机器人发送消息活动，其中包括用户在键值对中输入的所有输入字段和卡有效负载中定义的隐藏数据。

在自适应卡片架构中 data ，Action.Submit 的属性为或 stringobject。提交操作对于每个数据属性的行为不同：

string：字符串提交操作会自动将消息从用户发送到机器人，并在对话历史记录中可见。
object：对象提交操作会自动将用户提供的不可见消息发送到包含隐藏数据的机器人。对象提交操作在 text 属性为空时填充活动的值属性。

Action.Submit 等效于 Bot Framework 操作。你还可以修改自适应卡片 Action.Submit 有效负载，以支持在 Action.Submit 的 data 对象中使用 msteams 属性的现有 Bot Framework 操作。在下data定义 msteams 属性时，Teams 客户端定义的行为Action.Submit。 msteams如果未在架构中定义属性，Action.Submit则其工作方式类似于常规 Bot Framework 调用操作，其中;提交操作触发对机器人的调用，机器人使用输入字段中定义的所有输入值接收有效负载。

注意

机器人不会接收用户输入，除非用户通过按钮（例如 “保存” 或“ 提交”）在自适应卡片中提交其操作。例如，机器人不会将用户操作（例如从多个选项中选择一个选项或填写表单中的字段）视为输入，除非用户提交这些操作。
使用 Bot Framework 操作添加到 msteams 数据不适用于自适应卡片对话框。
Teams 不支持主要或破坏性 ActionStyle 。
应用有 5 秒的时间响应调用消息。

示例

下面是卡有效负载的示例Action.Submit：

有效负载由文本输入字段 "id": "text-1" 和隐藏的数据有效负载 "hiddenKey": 123.45组成。

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.5",
  "fallbackText": "fallback text for sample 01",
  "speak": "This is adaptive card sample 1",
  "body": [
    {
      "type": "Container",
      "items": [
        {
          "id": "text-1",
          "type": "Input.Text"
        }
      ]
    }
  ],
  "actions": [
    {
      "type": "Action.Submit",
      "data": {
        "hiddenKey": 123.45
      }
    }
  ]
}

屏幕截图显示了带有“提交”按钮的自适应卡片示例。

下面是用户在输入字段中键入内容并选择“ 提交”时机器人的传入活动示例。属性 value 在属性中包括用户的输入， text-1 以及属性中的 hiddenKey 隐藏数据有效负载：


{
 "type": "message",
 "timestamp": "2023-07-18T23:45:41.699Z",
 "localTimestamp": "2023-07-18T16:45:41.699-07:00",
 "id": "f:9eb18f56-2259-8fa4-7dfc-111ffff58e67",
 "channelId": "msteams",
 "serviceUrl": "https://smba.trafficmanager.net/amer/",
 "from": {
   "id": "29:1E0NZYNZFQOCUI8zM9NY_EhlCsWgNbLGTHUNdBVX2ob8SLjhltEhQMPi07Gr6MLScFeS8SrKH1WGvJSiVKThnyw",
   "name": "Megan Bowen",
   "aadObjectId": "97b1ec61-45bf-453c-9059-6e8984e0cef4"
 },
 "conversation": {
   "conversationType": "personal",
   "tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47",
   "id": "a:1H-RowZ3FrIheyjTupPnoCC6JvOLB5pCWms1xwqvAJG97j61D18EuSennYZE6tyfbQrnfIN3uIcwpOx73mg10hHp_uoTMMQlXhXosIu_q7QVCaYiW6Ch3bPWAitUw4aSX"
 },
 "recipient": {
   "id": "28:159e1c0f-15ef-4597-a8c6-44ba1fd89b78",
   "name": "Mushroom"
 },
 "entities": [
   {
     "locale": "en-US",
     "country": "US",
     "platform": "Web",
     "timezone": "America/Los_Angeles",
     "type": "clientInfo"
   }
 ],
 "channelData": {
   "tenant": {
     "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
   },
   "source": {
     "name": "message"
   },
   "legacy": {
     "replyToId": "1:1XFuAl7wF96vl6iAQk9tqus0uFrB89uujGpld-Qm-XEw"
   }
 },
 "replyToId": "1689723936016",
 "value": {
   "hiddenKey": 123.45,
   "text-1": "HELLO"
 },
 "locale": "en-US",
 "localTimezone": "America/Los_Angeles"
}

操作按钮的条件启用

可以使用 conditionallyEnabled 属性禁用操作按钮，直到用户更改至少一个所需输入的值。此属性只能与和 Action.Execute 操作一起使用Action.Submit。对于有条件启用的按钮，如果 isEnabled 属性设置为 false，则无论输入如何，都会禁用操作。

下面是属性的定义方式 conditionallyEnabled ：

属性	类型	必需	说明
`conditionallyEnabled`	Boolean	✔️	控制是否仅在用户至少填充了一个必需输入时启用操作。

以下卡有效负载显示有条件启用的按钮：

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.5",
    "body": [
        {
            "type": "Input.Text",
            "placeholder": "Placeholder text",
            "label": "Required text input",
            "isRequired": true,
            "id": "text"
        },
        {
            "type": "Input.Date",
            "label": "Required date input",
            "isRequired": true,
            "id": "date"
        }
    ],
    "actions": [
        {
            "type": "Action.Submit",
            "title": "Submit",
            "conditionallyEnabled": true
        },
        {
            "type": "Action.Submit",
            "title": "Permanently disabled button",
            "isEnabled": false
        }
    ]
}

Disabled

Enabled

表单完成反馈

可以使用自适应卡片生成表单完成反馈。向机器人发送响应时，表单完成消息显示在自适应卡片中。消息可以是两种类型：错误或成功：

错误：当发送到机器人的响应不成功时， 出现错误，将显示“重试” 消息。出现此错误的原因多种多样，例如：
- 请求过多
- 同一会话上的多个并发操作
- 服务依赖项问题
- 网关超时

成功：当发送到机器人的响应成功时， 将显示“你的响应已发送到应用” 消息。

屏幕截图显示了自适应卡片中的成功消息。

可以选择“ 关闭 ”或“切换聊天”以消除消息。

如果不想显示成功消息，请在属性中msTeamsfeedback将属性hidetrue设置为。下面是一个示例：

   "content": {
       "type": "AdaptiveCard",
       "title": "Card with hidden footer messages",
       "version": "1.0",
       "actions": [
       {
           "type": "Action.Submit",
           "title": "Submit",
           "msTeams": {
               "feedback": {
               "hide": true
               }
           }
       }
       ]
   }

有关机器人中的卡片和卡片的详细信息，请参阅卡片文档。

包含 messageBack 操作的自适应卡片

若要包含 messageBack 具有自适应卡片的操作，请在对象中包含 msteams 以下详细信息：

注意

如果需要，可以在 data 对象中包含其他隐藏属性。

属性	说明
`type`	设置为 `messageBack`。
`displayText`	可选。执行操作时由用户在聊天流中使用。此文本不会发送到机器人。
`value`	执行操作时发送到机器人。可以对操作的上下文进行编码，例如唯一标识符或 JSON 对象。
`text`	执行操作时发送到机器人。使用此属性可简化机器人开发。代码可以检查单个顶级属性以调度机器人逻辑。

以下代码显示包含 messageBack 操作的自适应卡片的示例：

{
  "type": "Action.Submit",
  "title": "Click me for messageBack",
  "data": {
    "msteams": {
        "type": "messageBack",
        "displayText": "I clicked this button",
        "text": "text to bots",
        "value": "{\"bfKey\": \"bfVal\", \"conflictKey\": \"from value\"}"
    }
  }
}

包含 imBack 操作的自适应卡片

若要包含 imBack 具有自适应卡片的操作，请在对象中包含 msteams 以下详细信息：

注意

字段 value 是不支持格式设置或隐藏字符的简单字符串。

属性	说明
`type`	设置为 `imBack`。
`value`	需要在聊天中回显的字符串。

以下代码显示包含 imBack 操作的自适应卡片的示例：

{
  "type": "Action.Submit",
  "title": "Click me for imBack",
  "data": {
    "msteams": {
        "type": "imBack",
        "value": "Text to reply in chat"
    }
  }
}

若要包含 signin 具有自适应卡片的操作，请在对象中包含 msteams 以下详细信息：

注意

如果需要，可以在 data 对象中包含其他隐藏属性。

属性	说明
`type`	设置为 `signin`。
`value`	设置为要重定向到的 URL。

以下代码显示包含 signin 操作的自适应卡片的示例：

{
  "type": "Action.Submit",
  "title": "Click me for signin",
  "data": {
    "msteams": {
        "type": "signin",
        "value": "https://signin.com"
    }
  }
}

包含 invoke 操作的自适应卡片

若要包含 invoke 具有自适应卡片的操作，请在对象中包含 msteams 以下详细信息：

注意

如果需要，可以在 data 对象中包含其他隐藏属性。

属性	说明
`type`	设置为 `task/fetch`。
`data`	设置值。

以下代码显示包含 invoke 操作的自适应卡片的示例：

{
  "type": "Action.Submit",
  "title": "submit",
  "data": {
    "msteams": {
        "type": "task/fetch"
    }
  }
}

属性	说明
`type`	设置为 `invoke`。
`value`	设置要显示的值。

以下代码显示包含 invoke 操作和其他有效负载数据的自适应卡片的示例：

[
  {
    "type": "Action.Submit",
    "title": "submit with object value",
    "data": {
      "ab": "xy",
      "msteams": {
        "type": "invoke",
        "value": { "a": "b" }
      }
    }
  },
  {
    "type": "Action.Submit",
    "title": "submit with stringified json value",
    "data": {
      "ab": "xy",
      "msteams": {
        "type": "invoke",
        "value": "{ \"a\": \"b\"}"
      }
    }
  }
]

代码示例

S.No。	卡	说明	.NET	Node.js	Python	Java	清单
1	自适应卡片操作	此示例展示了自适应卡片中支持的不同操作。	View	View	NA	NA	View
2	使用卡片	介绍所有卡类型，包括缩略图、音频、媒体等。在欢迎用户 + 多提示机器人的基础上，在欢迎消息中显示卡，这些按钮将路由到相应对话框。	View	View	View	View	不适用
3	自适应卡片	演示多轮次对话框如何使用卡获取名称和年龄的用户输入。	View	View	View	View	不适用
4	卡片格式设置	此示例演示有条件地启用的按钮。	View	View	NA	NA	NA

后续步骤

自适应卡的通用操作

通过

卡片操作

操作类型 openUrl

操作类型 messageBack

入站消息示例

操作类型 imBack

操作类型 invoke

传入调用消息的示例

自适应卡片操作

Action.Submit

示例

操作按钮的条件启用

表单完成反馈

包含 messageBack 操作的自适应卡片

包含 imBack 操作的自适应卡片

包含 invoke 操作的自适应卡片

代码示例

后续步骤

另请参阅

其他资源

通过

卡片操作

操作类型 openUrl

操作类型 messageBack

入站消息示例

操作类型 imBack

操作类型 invoke

传入调用消息的示例

操作类型登录

自适应卡片操作

Action.Submit

示例

操作按钮的条件启用

表单完成反馈

包含 messageBack 操作的自适应卡片

包含 imBack 操作的自适应卡片

具有登录操作的自适应卡片

包含 invoke 操作的自适应卡片

代码示例

后续步骤

另请参阅

其他资源