本指南为在 Microsoft Teams 中构建 HTML 小组件的合作伙伴提供用户体验指南。 它介绍了创建专注于高质量的小组件体验的原则和建议,这些体验可以自然地集成到 Teams 聊天对话中。 目标不是强制使用单一的视觉样式,而是确保小组件在 Teams 上下文中感觉有意且正常工作。
用户体验原则
为 Teams 构建出色的小组件意味着提供集中的体验,在正确的时间显示正确的信息或操作。 HTML 小组件应该感觉像是 Teams 对话的自然组成部分,而不是嵌入其中的应用程序。
补充对话
- 在聊天会话中,小组件与代理生成的文本一起存在,并且应该始终让人感觉像是对话的自然组成部分。
- 小组件可以是仅显示的、支持交互或提示用户输入。
- 内容应支持对话,而不是感觉像是一种独立或脱节的体验。
- 针对对话上下文进行设计 — 小部件应该提供当下的原生价值,而不是简单地复制独立应用程序中已经存在的内容。
Surface 功能,但不是完整应用
避免将完整的应用程序体验嵌入到小组件中。 相反,确定用户此时此刻需要的最有价值的东西。
- 小组件应公开有针对性的高价值功能,而不是整个产品。
- 每个小组件都应代表一个集中的交互。
保持透明且可预测
- 小组件内容应清晰,任何交互都应明显。
- 用户应始终了解小组件显示的内容。
- 在用户采取行动之前,任何交互的预期结果都应该是显而易见的。
缩放到任务
将小组件的视觉足迹与用户当前的需求相匹配。
- 小组件始终内联显示在聊天中。
- Teams 提供了一个扩展的图面,即在聊天上方打开的较大视图。 如果您的小组件包含丰富的内容或更深层次的工作流程,并且受益于更多空间,请在小组件的操作区域添加展开图标以启用此体验。
保持人机控制
信任很重要,尤其是当小组件操作影响数据或触发外部工作流程时。
- 允许用户继续控制自己的体验。
- 清楚地显示小组件正在执行的操作以及原因。
- 在重要或敏感操作发生之前确认它们。
- 透明地传达结果 - 创建、更改或发送的内容。
了解聊天界面
HTML 小组件在 Teams 聊天消息中内联呈现。 在做出设计决策之前,了解这一背景至关重要。
在为 Teams 进行设计时,请遵循以下核心原则:
- 对话优先: 聊天仍然是主要交互模型。 构件支持它。
- 渐进式复杂性: 轻量级启动。 仅在需要时移动到展开的曲面。
- 上下文保留: 用户在与小组件交互时不应丢失对话上下文。
- Clarity over duplicates:小部件内容和代理正文文本应相互补充,而不是重复相同的信息。
请注意:
- 该小部件显示在聊天线程中,与座席的文本回复和其他消息一起显示
- 根据用户的消息布局,小组件可以 (舒适模式) 位于消息气泡内,也可以 (紧密模式和 Teams 移动) 直接放在聊天画布上。 确保它在两者中看起来都很好。
- 用户处于对话思维 — 他们期望轻量级、专注的交互
- 一个或多个小部件可能出现在同一消息中,并以任意顺序与可选的正文文本组合
- 虽然小组件也可能在其他主机平台中呈现,但请使用此指南来确保它在 Teams 中感觉是有意为之且本机的。
提示
如果小组件也在 智能 智能 Microsoft 365 Copilot 副驾驶® 副驾驶® 中呈现,请参阅声明式代理中 MCP 应用的用户体验指南,了解特定于 Copilot 的指南。
小组件剖析
许多小组件都遵循一种共同的模式,可帮助用户快速理解布局,但并非每个小组件都需要所有这些元素,并且某些小组件 ((例如地图、图表或表单)可能根本不遵循此结构) 。
常见元素
| 元素 | 说明 | 注释 |
|---|---|---|
| 标题 | 标识小组件或其代表的内容 | 让用户立即了解小部件是什么以及会发生什么,帮助它在对话中清晰地脱颖而出 |
| 正文内容 | 主要信息、媒体或交互式内容 | 大多数小部件的核心 — 可能是唯一存在的元素 |
| 操作 | 按钮、链接或其他交互式元素,允许用户执行下一步 | 可选。 交互式元素可能出现在整个小部件中,不仅出现在底部,而且当小部件包含专用操作区域时,它通常会放置在底部 |
当小组件遵循这种常见模式时,内容通常从上到动:
- 游戏 ((如果适用))
- 主要内容 — 关键信息、数据或媒体
- 操作区域 ((如果存在)) - 放置在底部
小组件要求
以下要求适用于提交到 Teams 的所有 HTML 小组件。 不满足这些要求的小组件可能会被拒绝或需要在发布前进行修正。
主题支持 (浅色和深色模式)
小组件必须在 Teams 浅色模式和深色模式下正确呈现。
- 提交前,请在这两个主题中测试小组件。
- 使用 CSS 变量或 Fluent 2 颜色标记而不是硬编码的十六进制值,以便小组件自动适应主题更改。
注意
对于颜色有意义且不应更改的内容,例如设计文档、品牌演示文稿、数据可视化或颜色具有特定含义的媒体,不需要主题调整。 在这些情况下,请按原样呈现内容。
响应式缩放
小组件必须适应聊天容器的宽度。 Teams 聊天容器的宽度因上下文而异,例如移动屏幕、会议聊天窗格或与主聊天一起打开的线程视图。 与支持合作伙伴可以独立自定义的离散大小变体的自适应卡不同,HTML 小组件使用跨宽度连续缩放的单个流畅布局。 您的设计应在任何宽度下都能优雅地保持,而不是针对特定尺寸。
- 使用灵活流畅的布局,而不是固定像素宽度
- 避免使用固定像素高度 — 允许小组件根据内容需要垂直增长
- 跨一系列宽度进行测试,以确保布局在常见的 Teams 上下文中能够保持良好效果
首先针对较窄的移动集装箱进行设计,然后针对较宽的集装箱调整布局。 保持主要内容可读,不会剪裁或意外水平滚动。 使每个操作都可通过触摸使用,而无需依赖悬停。 在 iOS 和 Android 版 Teams 中以纵向和横向测试,并确认布局也适用于桌面宽度。
下面显示的宽度表示要测试的最常见方案:宽、标准桌面、移动和会议聊天或并排视图。 这些不是断点或大小槽 - 它们是评估单个流体布局如何在控件可能出现的上下文范围内缩放的参考点。
水平滚动
避免水平滚动主要小组件内容。 布局应适应聊天容器典型的窄宽度。
提示
水平滚动可以有意用于特定的内容类型,例如宽数据表、媒体轮播或时间线,其中水平导航是体验的有意义的一部分。 这些情况应该是有意为之,而不是固定宽度布局的结果。
反馈和确认
小组件必须清楚地传达用户操作的结果。
- 在小组件内使用可见的成功状态确认成功的操作
- 操作失败时显示带有恢复选项的清除错误状态
- 当小组件在内部提取或处理数据时显示加载指示器
- 不要仅依赖代理的正文文本来传达小组件状态
注意
Teams 处理小组件级别的加载和错误状态。 上述要求适用于小组件内容中的状态处理。
提交的最低用户体验栏
小组件必须满足以下所有要求才能被 Teams 应用商店接受。
| 要求 |
|---|
| ✅ 在 Teams 浅色模式和深色模式下都能正确呈现 (但颜色有意义的内容除外) |
| ✅ 根据聊天容器宽度响应缩放,而不会出现水平滚动 (有意水平滚动模式也有例外) |
| ✅ 提供有关小组件中加载、成功和错误状态的可见反馈 |
| ✅ 提供专注的单一用途体验 |
| ✅ 将主要操作限制为两个按钮 — 附加操作放置在溢出中 |
| ✅ 内容和正文相辅相成,没有重复 |
| ✅ 看不到占位符、测试或损坏的内容 |
警告
不满足这些要求的小组件可能会被拒绝或需要修正才能发布。
强烈建议
强烈建议使用以下指南,以帮助小组件在 Teams 中感到宾至如归。 合作伙伴可能会出于合法的品牌或设计原因偏离,但应故意这样做。
提示
从 小组件边框和填充开始。 它包含本节中的其他所有内容。
小组件边框和填充
Teams 提供小组件呈现的 iframe,但不向其添加边框、角半径或背景。 添加您自己的边框和填充,以便您的小部件作为消息中的包含单元阅读。
这很重要,因为消息气泡的背景通常框住消息及其中的所有内容。 在 Cozy 模式下,气泡位于小部件后面并完成该工作。 在紧密模式和 Teams 移动版上,没有气泡,因此小组件直接位于聊天画布上。 如果没有自己的边框和填充,它可能看起来像是浮动的。
- 在小组件内容周围添加边框和填充
- 选择适合设计的边框颜色、角半径和背景。 如果希望小组件给 Teams 原生的感觉,Fluent 2 形状和颜色标记是一个很好的起点
- 使用“ 间距”中所述的建议的 16 像素填充。
| 舒适 (消息气泡) | 紧凑、移动 (无气泡) | |
|---|---|---|
| 带边框和填充 |
|
|
视觉设计
颜色和主题
对背景、边框和文本使用 Fluent 2 颜色标记。 这可确保小组件正确响应 Teams 主题,而无需进行其他工作。
- 谨慎使用品牌颜色 — 作为主要动作和关键元素的亮点,而不是作为主背景色
- 切勿仅依靠颜色来传达含义 - 始终将颜色与标签、图标或其他指示器配对
容器颜色
使用容器颜色令牌在小组件中建立层次结构并传达状态。 如果希望外部卡表面与 Teams 匹配,请从默认开始,然后在其中嵌套容器以对相关内容或表面状态含义进行分组。
| 样式 | 令牌 | 用于 | |
|---|---|---|---|
| 默认值 |
|
colorNeutralCardBackgroundcolorNeutralStroke2 |
外部卡表面 - 如果希望小组件的基本容器与 Teams 本机卡背景匹配,请使用此令牌 |
| 强调 |
|
colorNeutralBackground3colorNeutralStroke1 |
分组或次要内容区域 - 最常见的内部容器 |
| 突出 |
|
colorBrandBackground2colorBrandStroke2 |
品牌强调的亮点和标注 |
| Good |
|
colorPaletteLightGreenBackground1colorStatusSuccessBorder1 |
确认和成功结果 |
| 警告 |
|
colorPaletteMarigoldBackground1colorPaletteMarigoldBorder1 |
注意事项和时效性警报 |
| 注意 |
|
colorStatusDangerBackground1colorStatusDangerBorder1 |
错误、故障和严重警报 |
与自适应卡片不同,HTML 小组件不会自动继承卡背景。 如果要匹配 Teams 本机卡表面,请应用于colorNeutralCardBackground外部容器。 在其中,使用 Emphasis 容器对内容进行分组或分隔,并在特定内容区域具有状态含义时使用 Good、Warning 或 Attention 容器。
文本颜色
使用文本颜色令牌创建层次结构并传达小组件内容中的含义。 将状态文本颜色与匹配的容器或图标配对 - 切勿只依赖颜色。
| 样式 | 令牌 | 用于 | |
|---|---|---|---|
| 默认值 |
|
colorNeutralForeground1 |
主要文本 — 标题、键值 |
| 细微 |
|
colorNeutralForeground3 |
辅助文本 — 支持详细信息、元数据 |
| 突出 |
|
colorBrandForeground2 |
Teams 品牌强调文本和内联链接 |
| Good |
|
colorStatusSuccessForeground1 |
成功标签和状态指示器 |
| 警告 |
|
colorPaletteMarigoldForeground2 |
警告标签和状态指示器 |
| 注意 |
|
colorStatusDangerForeground3 |
错误标签和状态指示器 |
注意
叠加文本 标记是在图像或背景媒体上呈现的文本的静态颜色。 与其他文本令牌不同,它们不适应主题变化 - 根据基础图像的亮度选择深色或浅色。
| 样式 | 令牌 | 用于 | |
|---|---|---|---|
| 深色叠加层 |
|
colorNeutralForeground1Static |
浅色或中间色调图像上的文本 |
| 叠加光 |
|
colorNeutralForegroundStaticInverted |
深色图像上的文本 |
版式
使用以下基本文本样式在小部件中创建清晰的视觉层次结构。 这些样式与 Teams 设计系统一致,并涵盖小组件中最常见的文本角色。
| 样式 | Fluent 令牌 | 尺寸/重量 | 用于 |
|---|---|---|---|
| Header | — * | 18 像素/600 | 小组件或卡标题 |
| Label | Body1Strong |
14 像素/600 | 节标题、状态标签 |
| 正文 | Body1 |
14 像素/400 | 主要内容、说明 |
| 标题标签 | Caption1Strong |
12 像素/600 | 小标签,字段值 |
| Caption | Caption1 |
12 像素/400 | 支持详细信息、时间戳 |
| 字幕细微标签 | Caption1Strong + ColorNeutralForeground3 |
12 像素/600 | 细微的分区标签、元数据键 |
| 字幕细微 | Caption1 + ColorNeutralForeground3 |
12 像素/400 | 去强调文本,辅助元数据 |
* 标头是 Fluent UI 中未包含的自定义大小 React v9 类型渐变。直接使用 18 像素/600。
- 在单个小组件中最多使用三种不同的文本大小来维护视觉层次结构
- 默认情况下允许文本块换行 - 除非空间受到真正限制,否则避免截断正文内容
提示
如果使用 React 构建,请使用 Fluent UI React v9 版式令牌,而不是硬编码的像素值。 令牌会自动适应主题更改,并与 Fluent 设计系统保持同步。
容器和边框
有关整个小组件周围的边框和填充,请参阅 小组件边框和填充。
在小组件的框架内,使用容器对相关内容进行分组并创建可视层次结构。
- 应用与 Fluent 2 形状 一致的边框半径值,使容器感觉是 Teams 的本机容器
- 当内容区域之间需要额外的分隔或强调时,添加边框 - 使用与容器颜色配对的边框标记
- 应谨慎使用全角 (边到边的) 背景 — 它们非常适合主图或强势分区
- 避免深度嵌套 — 将容器嵌套限制为最多两个级别
Spacing
小组件边框内的建议填充为 16 像素 (spacingHorizontalL / spacingVerticalL 四边) 。
以下是小组件布局的常用间距值。 这些映射到 Fluent UI React v9 间距标记 — 交换Vertical为Horizontal水平间距等效项。
| 名称 | 令牌 | Size | 常见用途 |
|---|---|---|---|
| 特小号 | spacingVerticalXS |
4 像素 | 图标与其标签之间,徽章内 |
| 小 | spacingVerticalS |
8 px | 在按钮或紧密分组的元素之间 |
| 中 | spacingVerticalM |
12 像素 | 文本块和输入之间的垂直节奏 |
| 大 | spacingVerticalL |
16 像素 | 用于卡片和容器的 Standard 内部填充物 |
| 特大 | spacingVerticalXL |
20 像素 | 不同内容部分之间的分离 |
| 特大号 | spacingVerticalXXL |
24 像素 | 宽敞的呼吸空间 |
以下示例演示了间距标记如何在实际小组件布局中应用。
有关完整间距比例,请参阅
Fluent 2 > 间距。
图标
尽可能使用 Fluent 2 图标 ,而不是自定义或第三方图标集。 Teams 用户可识别 Fluent 图标,并能以标准大小正确缩放。
操作
操作允许用户在不离开对话的情况下执行下一步。
- 限制为两个主要操作 - 将一个主要按钮用于最重要的操作,将一个辅助按钮用于备用操作
-
将溢出用于其他操作 - 将其他操作放置在溢出菜单中, (
•••) ,而不是添加更多按钮 - 明确标记行动 — 使用以结果为导向的标签,例如“立即保留”或“批准”,而不是像“确定”这样模糊的标签
- 禁用,不隐藏 - 如果操作在当前状态下不可用,请禁用该控件,而不是隐藏它
提示
如果使用 React 进行构建,则 Fluent 2 按钮组件可直接实现正确的 Teams 对齐按钮样式和状态。
内容和布局
- 简明扼要: 小组件应一目了然。 用户无需在小组件内滚动即可了解关键信息
- 显示摘要,而非系统: 显示与当前上下文最相关的数据,而不是完整的数据表、仪表板或导航树
- 避免内部滚动: 如果内容需要滚动,请考虑它是否属于展开的图面
- 避免深层导航: 选项卡、向下钻取菜单和多级导航不适合内联小部件
- 请勿重复内容: 小组件内容和代理正文文本应相辅相成 - 不要在两者中重复相同的信息
渐进式披露
并非所有信息都需要同时可见。 使用渐进式披露来保持小组件简洁,同时允许用户在需要时访问更多详细信息。
- 使用显示/隐藏切换开关内联显示辅助信息或辅助信息 — 例如展开摘要行以显示完整详细信息,或按需显示其他字段
- 对于更长的内容列表,在定义的容器内使用滚动 - 确保容器具有清晰的标签,并且可通过键盘访问
- 对于需要大量垂直空间或多步骤交互的内容,过渡到扩展的图面
输入收集
如果小组件包含表单或输入字段:
- 清楚地标记所有字段 - 使用可见标签,而不仅仅是占位符文本
- 指示必填字段
- 验证输入内联,并在相关字段旁边显示错误消息
- 保持窗体简短 - 如果窗体需要四到五个以上的字段,请考虑将其移动到展开的图面
展开的曲面
当用户选择展开按钮时,展开的图面将作为聊天上方的模式打开。 将其用于需要比内联小部件合理提供的更多空间的内容或工作流。
何时使用展开图面
- 多步骤窗体或配置流
- 受益于更大画布的富媒体
- 详细数据表或比较视图
- 具有持久状态的迭代工作流
交互准则
- 有意使用扩展 — 并非每个小组件都需要扩展的视图。 为真正受益于更多空间的内容保留它
- 不要复制完整的应用程序 — 扩展的 Surface 是用于特定任务的重点工作区,而不是产品外壳。 避免使用全局导航、设置面板或不相关的功能
- 范围限定为一项任务 — 扩展的图面应支持单个一致的工作流
- 保留上下文 - 当展开的图面打开时,聊天仍然可见。 设计扩展的内容以与对话协同工作
最佳做法
✅ 应做
- 添加边框和填充,使小组件在有或没有消息气泡的情况下保持在一起
- 保持小组件轻量化且面向操作
- 支持最多两个主要操作
- 使用展开的图面进行深度导航或多步骤工作流
- 使用 Fluent 2 组件、间距、版式和标记
- 显示加载指示器、成功确认和错误状态以及恢复选项
- 默认情况下允许文字换行
- 使用以结果为导向的操作标签,例如“立即保留”或“批准请求”
❌ 禁止事项
- 不要依赖消息气泡将小组件与聊天分开
- 不要在小组件中嵌入完整的应用程序体验
- 请勿重新创建 Teams 聊天功能,如提示输入或重试控件
- 不要对颜色进行硬编码 - 使用 Fluent 2 令牌或 CSS 变量
- 不要使小组件高于视区
- 不要在小组件和代理的正文文本中重复相同的信息
- 避免使用模糊的操作标签,如“确定”或“单击此处”——尽可能使用以结果为导向的标签
很高兴有
以下项是可选的,但有助于提供更高质量的小组件体验。
- 使用 Fluent 2 组件: Fluent 2 组件可实现 Teams 对齐的视觉模式和交互,开箱即用。 如果使用 React 进行构建,则建议使用 Fluent UI React v9 实现。
- 支持布局模式:考虑既定的布局模式 — 顶部的主图 (图像、) 下方的内容、文章 (文本繁重、分层) 、以输入为中心的) 表单 (或) (重复项目列表 — 并选择适合你的内容类型的模式。
- 图表和数据可视化:确保轴标签和数据点在小部件宽度下清晰可读。 对于复杂图表,请考虑过渡到展开图面。
- 媒体元素:对于内联视频或富媒体,请提供清晰的播放控件和静态缩略图。 不建议自动播放。
- 插图:谨慎而有目的地使用插图。 避免增加高度而不增加价值的装饰插图。