Teams机器人PromptOptions选项无法显示为按钮如何解决

架构老林

2026-8-29

问题描述

使用Python开发Microsoft Teams机器人时，通过PromptOptions配置的选择项存在默认渲染限制：当选项数量超过3个，或单个选项文本长度较长时，Teams客户端不会将选项渲染为可点击按钮，而是自动转换为纯文本列表样式。原实现代码如下：

PromptOptions(
            prompt=MessageFactory.text("Hi \uD83D\uDC4B. How are you feeling today? "),
            choices=[Choice("Good"), Choice("Bad"), Choice("Sad"),Choice("Mad"),Choice("Glad"),Choice("Upside")],
        )

根本原因

这个现象是Teams客户端内置的固定渲染规则，不是代码逻辑错误。Bot Framework默认的Choice选项没有提供强制按钮渲染的配置参数，只要触发以下任意一个条件，客户端就会自动切换为列表渲染：

传入的选项总数量超过3个
单个选项的文本长度超过客户端规定的按钮文案长度阈值（不同端阈值略有差异，通常为10-15个字符）

可行解决方案

没有直接修改原生Choice渲染逻辑的方法，可通过以下三种绕开限制的方案实现按钮常驻效果：

方案1：使用自适应卡片（Adaptive Card）自定义按钮（推荐）
完全绕开原生Choice的渲染逻辑，自行构造自适应卡片结构，将所有选项定义为Action.Submit类型的提交按钮。这种方式下客户端会严格按照卡片定义渲染按钮，不会自动转换为列表，还可以自由控制按钮排版、样式。
参考实现代码：

from botbuilder.core import CardFactory, MessageFactory, PromptOptions

构造带按钮的自适应卡片

card_content = {
"type": "AdaptiveCard",
"version": "1.4",
"body": [
{"type": "TextBlock", "text": "Hi 👋. How are you feeling today?", "size": "medium"}
],
"actions": [
{"type": "Action.Submit", "title": "Good", "data": {"value": "Good"}},
{"type": "Action.Submit", "title": "Bad", "data": {"value": "Bad"}},
{"type": "Action.Submit", "title": "Sad", "data": {"value": "Sad"}},
{"type": "Action.Submit", "title": "Mad", "data": {"value": "Mad"}},
{"type": "Action.Submit", "title": "Glad", "data": {"value": "Glad"}},
{"type": "Action.Submit", "title": "Upside", "data": {"value": "Upside"}}
]
}
card_attachment = CardFactory.adaptive_card(card_content)
prompt_msg = MessageFactory.attachment(card_attachment)

构造PromptOptions时无需再传入choices参数

PromptOptions(prompt=prompt_msg)

注意：单张自适应卡片最多支持6个内联按钮，选项更多时可以分组排版或做二级交互。

- *方案2：使用内置富卡片的按钮组*
如果不需要复杂排版，可以直接用Bot Framework内置的Hero Card（主卡片），把所有选项放到卡片的`buttons`数组中，客户端同样会按按钮渲染，代码量比自适应卡片更少。
参考实现片段：
```python
from botbuilder.schema import ActionTypes

hero_card = CardFactory.hero_card(
  text="Hi 👋. How are you feeling today?",
  buttons=[
      CardFactory.action(ActionTypes.im_back, title="Good", value="Good"),
      CardFactory.action(ActionTypes.im_back, title="Bad", value="Bad"),
      CardFactory.action(ActionTypes.im_back, title="Sad", value="Sad"),
      CardFactory.action(ActionTypes.im_back, title="Mad", value="Mad"),
      CardFactory.action(ActionTypes.im_back, title="Glad", value="Glad"),
      CardFactory.action(ActionTypes.im_back, title="Upside", value="Upside")
  ]
)
prompt_msg = MessageFactory.attachment(hero_card)
PromptOptions(prompt=prompt_msg)

方案3：拆分多轮交互适配原生规则
如果不想使用卡片形式，可以将超过3个的选项拆分为多轮提问，每轮最多展示3个短文本选项，完全适配Teams原生Choice的按钮渲染规则。缺点是交互路径更长，仅适合选项数量少的场景。

注意事项

不要尝试通过修改原生Choice的样式参数强制渲染按钮，Teams的渲染逻辑在客户端本地执行，服务端传递的非公开参数无法覆盖这个规则。
按钮文案尽量控制长度，过长的文案即使在卡片中也会出现截断，影响使用体验。
Teams桌面端、网页端、移动端的渲染细节存在差异，功能上线前需要在实际使用的端侧做验证。

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