MCP 应用 (HTML 小组件) 允许合作伙伴在 Teams 聊天中的沙盒 <iframe> 内呈现自定义 HTML 和 JavaScript 体验。 由于这些小部件与对话内容内联显示,因此它们必须满足一致的辅助功能栏,以便所有用户(包括使用辅助技术的用户)都可以感知、理解和操作它们。
本文介绍 HTML 小组件的最低辅助功能要求,并提供建议的最佳做法和测试指南。
范围
这些准则适用于在 Teams 聊天中 <iframe> 呈现的所有合作伙伴构建的 HTML 小组件 (MCP 应用) 。 这些要求是对一般 Web 辅助功能标准(如 WCAG 2.2 和 WAI-ARIA 创作实践)的补充。
提示
如果要使用 React 构建小组件,建议使用 Fluent UI React v9 组件和令牌。 它们现成实现可访问的、与 Teams 兼容的模式,并减少了所需的自定义辅助功能工作量。 不需要 Fluent UI React v9 - 只要满足本文中的辅助功能要求,合作伙伴就可以使用任何框架或库。
建议的最佳做法
以下做法不是必需的,但强烈建议用于改善整体体验。
- 跳过链接: 在小组件顶部提供“跳到主要内容”链接,以便键盘和屏幕阅读器用户绕过重复导航
-
标题: 使用标题 (
<h1>-<h3>) 来构建内容结构,使屏幕阅读器用户能够更轻松地进行导航 - 简单的交互模型: 与高度自定义或新颖的控件相比,更喜欢简单、可预测的交互模式
- 滚动: 避免使用复杂的嵌套滚动区域。 如果需要可滚动区域,请确保它具有清晰的标签并且可通过键盘访问
-
工具提示: 使用可访问的工具提示,
aria-describedby确保它们在焦点和悬停时可用 - 可访问的组件:尽可能使用 Fluent UI React v9 组件 — 它们实现开箱即用的可访问模式,并减少了所需的自定义辅助功能工作量
责任模型
团队和合作伙伴共同负责辅助功能。 下表阐明了各方拥有的内容。
| 要求 | Teams | 合作伙伴 |
|---|---|---|
| 小组件容器标签 (例如,“Scout 小组件”) | ✅ | |
| 小组件容器的制表位 | ✅ | |
| 消息元素的 Tab 键顺序 | ✅ | |
| 焦点进出构件容器 | ✅ | |
| 小组件级别加载和错误状态 | ✅ | |
| 小组件内的键盘导航 | ✅ | |
| 交互式元素的 ARIA 标签 | ✅ | |
| 对小组件内容的屏幕阅读器支持 | ✅ | |
| 小组件内的颜色对比度 | ✅ | |
| 小组件内的高对比度支持 | ✅ | |
| 小组件内内容的错误处理 | ✅ |
提交的最小辅助功能栏
小组件必须满足以下所有要求才能被接受。 不满足此标准的小组件可能会被拒绝或需要在发布前进行修正。
| 要求 |
|---|
| ✅ 完全可通过键盘操作,小部件内没有焦点陷阱 |
| ✅ 可与屏幕阅读器一起使用,在所有交互元素上具有有意义的角色、名称和状态 |
| ✅ 满足文本和基本 UI 元素的 WCAG 2.2 AA 对比度 |
| ✅ 为小组件内的内容提供可访问的错误处理和加载状态 |
| ✅ 文本和交互式控件在 200% 浏览器缩放率下仍可阅读和可操作, (特殊情况适用于图表、地图和媒体) 等固定方面内容 |
✅ 尊重 prefers-reduced-motion 并避免有害闪烁 |
| ✅ 避免主要内容水平滚动 - 可以接受有意水平滚动模式,例如宽表或轮播 |
警告
小组件必须满足以下所有要求才能被 Teams 应用商店接受。 在 发布到 Teams 应用商店之前,不满足此标准的小组件可能会被拒绝或需要修正。
键盘辅助功能
注意
Teams 管理进出构件容器的焦点。 以下要求仅适用于小组件内容内的键盘导航。
键盘可操作性:所有交互式元素必须可使用标准键盘输入(如 Tab、Shift+Tab、箭头键、Enter 和空格键)访问和操作,具体取决于控件类型。
无焦点陷阱:小组件不得捕获焦点。 用户必须能够按逻辑顺序浏览所有交互式元素,并在不会卡住的情况下退出小部件。
可见焦点:所有交互元素必须具有清晰可见的焦点指示器,符合对比度要求,并且在没有可访问的替换项的情况下不能通过 CSS 删除。
自定义控件:自定义小组件和控件必须遵循 ARIA 创作实践中为其各自角色定义的键盘交互模式, (button例如 、 menudialoglistbox 、、) 。
对话框和模式:在小组件中可以使用模式对话框和覆盖,但不建议这样做。 由于小组件在一个小的 iframe 中呈现,模态将受到该空间的约束,并且可能会让用户感到迷失方向。 如果您的用例需要模态,请考虑扩展的图面是否更适合该交互。 如果您确实在小部件中实现了模态,如果您使用的是 Fluent UI React v9,请使用 Dialog 或 Popover 组件而不是自定义实现,因为它们可以正确处理焦点捕获、焦点恢复和 ARIA 属性。 对于自定义模式行为, useModalAttributes 可用。
焦点恢复:当用户操作 (后从 DOM 中删除元素时,例如,在提交表单或关闭面板) 后,焦点必须恢复到逻辑元素,而不是拖放到文档正文。 使用 Fluent V9 的 useRestoreFocusSource 和 useRestoreFocusTarget 挂钩自动处理此问题。
| ✅ 应做 | ❌ 禁止事项 |
|---|---|
|
|
屏幕阅读器语义
小组件必须公开有意义的结构和语义,以便屏幕阅读器和其他辅助技术可以正确解释和播报内容。
语义 HTML
尽可能使用本机 HTML 元素,例如 <button>、<input>、<label>、 <nav><ul><li><form>和 。
角色、名称、状态
所有互动元素必须具有:
- 一个有意义的角色 (本机或 ARIA)
- 可访问的名称 (可见文本、
aria-labelaria-labelledby或) - 准确的状态和属性信息 (例如
aria-expanded、 、aria-selectedaria-checkedaria-disabled)
动态更新
使用实时区域宣布屏幕阅读器的重要更改:
-
aria-live="polite"对于非关键更新,例如加载结果 -
aria-live="assertive"对于错误等关键更新
如果你使用的是 Fluent V9 和 React,请将 AriaLiveAnnouncer 与 useAnnounce 钩子一起使用,而不是实现原始aria-live区域。 如果您的小部件包含文本输入,并且需要在用户键入时宣布更新,请改用 useTypingAnnounce 。
Images
传达含义的图像必须包含描述性 alt 文本。 装饰图像应标为空白 alt="" 或隐藏辅助技术。
| ✅ 应做 | ❌ 禁止事项 |
|---|---|
|
|
焦点管理
由于小组件嵌入在对话体验中,因此小组件中的焦点行为必须是可预测的,并且不得中断用户在聊天中的工作流。
没有焦点窃取
加载小组件时不得在 iframe 内自动移动焦点。 焦点应保留在 Teams 放置的位置,直到用户与构件明确交互。
初始焦点
当用户将焦点移到小组件中时,焦点应落在第一个有意义的交互式元素上,而不是隐藏或非交互式元素上。
对话框和覆盖
如果小组件打开模式对话框:
- 在对话框打开时将焦点移动到对话框中
- 在对话框打开时将焦点捕获在对话框内
- 对话框关闭时,将焦点返回到触发元素
颜色、对比度和高对比度模式
小组件必须在不同的对比度设置(包括 Windows 高对比度模式)下保持可感知。
文本对比度
文本和基本图标必须满足 WCAG 2.2 AA 对比度:
- 对于普通文本,至少为 4.5:1
- 对于 18pt 或 14pt 粗体及以上 (大文本,至少为 3:1)
高对比度模式
在 Windows 高对比度模式下测试小组件,并确保交互式元素、焦点指示器和关键图标保持可见且易于理解。 虽然提交时不是必需的,但强烈建议使用高对比度支持,以确保依赖此辅助功能设置的人员可以使用小组件。
颜色独立性
不要仅仅依靠颜色来传达意义。 除颜色外,还可使用文本、图标、图案或其他指示器。
| ✅ 应做 | ❌ 禁止事项 |
|---|---|
|
|
响应式布局和缩放
小组件必须适应聊天容器,并在不同的缩放级别和视区大小下保持可用。
- 缩放支持: 文本和交互式控件必须在 200% 浏览器缩放分辨率下保持可读性和可操作性。 固定方面的内容(如数据可视化、嵌入式媒体、地图或基于画布的渲染)在缩放本质上会扭曲体验的情况下是豁免的。 在这些情况下,请确保内容仍可通过其他方式(例如描述性替换文字、数据表或标题)访问。
- 灵活的布局: 避免使用固定像素高度 — 允许小组件根据需要垂直增长,这样内容就不会被剪裁。
- 水平滚动: 避免水平滚动主要小组件内容。 布局应适应聊天容器典型的窄宽度。 特定内容类型(例如宽数据表或轮播)的有意水平滚动是可接受的。
动作、动画和计时
动作和动画不得引起不适或干扰可用性。
-
减少运动: 通过减少或禁用非必要动画来尊重用户的
prefers-reduced-motion设置 - 安全运动: 避免可能引发光敏反应的闪烁内容或快速动画
- 自动推进内容: 请勿在没有用户输入的情况下自动推进轮播或内容。 如果需要自动前进,请提供用于暂停、停止和手动导航的控件
小组件内的错误处理
注意
Teams 处理呈现器级别的加载和错误状态 — 小组件本身无法加载或呈现时显示的外部状态。 合作伙伴负责在其自己的小组件内容中进行可访问的错误处理。
通知
使用 或适当的实时区域向 aria-live="assertive" 屏幕阅读器报出严重错误。 如果使用 Fluent UI React v9,请使用 useAnnounce with polite: false 来发布错误公告。
清晰的消息传递
错误消息必须:
- 用清晰简洁的语言描述出现的问题
- 说明用户如何修复问题或重试
输入错误
对于无效字段:
- 在输入上设置
aria-invalid="true" - 使用或类似机制将错误消息与输入
aria-describedby相关联
在小组件内加载状态
注意
Teams 处理小组件级别的加载状态。 以下要求适用于初始渲染后控件内容中发生的任何加载状态。
- 可见指示器: 当控件在初始渲染后获取或处理数据时显示清晰的加载指示器。
-
公告: 用于
aria-live="polite"向屏幕阅读器通知加载和完成状态。 如果使用 Fluent UI React v9,请将 useAnnounce 与polite: true. - 对准行为: 在加载过程中不要捕获焦点 — 用户仍必须能够在小组件内移动焦点。
-
骨架 UI: 如果使用骨架屏幕,请使用
aria-hidden="true"将其隐藏在辅助技术之外,或者提供描述加载状态的有意义的标签。
测试指南
合作伙伴应在提交之前使用以下三步工作流验证辅助功能。 由于小组件在沙盒 iframe 中运行,因此在运行任何自动化工具之前,请直接在浏览器选项卡中打开小组件内容 - 默认情况下,大多数工具无法扫描 iframe 内容。
步骤 1 - 运行自动扫描
从自动扫描开始,快速发现最常见的问题。 自动化工具通常可识别 30-40% 的辅助功能问题,因此还需要手动测试。
| 工具 | 类型 | 注释 |
|---|---|---|
| Lighthouse | 浏览器 (Chrome DevTools) | 内置于 Chrome 中 — 这是捕获丢失标签、对比度故障和结构问题的良好起点。 无需安装。 首先运行。 |
| 斧头开发工具 | 浏览器扩展 | 比灯塔更详细。 免费版本涵盖了更广泛的 WCAG 违规行为,并提供了更清晰的补救指南。 |
| 挥手 | 浏览器扩展 | 直接在页面上突出显示问题的视觉覆盖。 用于快速发现缺少的替换文字、窗体标签和标题结构。 |
第 2 步 - 手动验证对比度
自动化工具并不总是能可靠地发现对比度故障。 自动扫描后,使用以下任一工具手动验证颜色对比度:
| 工具 | 类型 | 注释 |
|---|---|---|
| 颜色对比度分析仪 | 桌面工具 | 直接在屏幕上对任意两种颜色进行采样,并根据 WCAG AA 比率检查。 |
| WebAIM 对比度检查器 | 基于 Web 的 | 输入十六进制值以验证文本和背景组合。 无需安装。 |
第 3 步 - 手动测试
需要手动测试来验证键盘行为、屏幕阅读器输出和视觉适应性。 按顺序完成每个测试:
| 测试类型 | 要验证的内容 |
|---|---|
| 仅使用键盘 | 仅使用 Tab、Shift+Tab、箭头键、Enter 和空格键导航整个小组件。 验证始终没有焦点陷阱和逻辑标签页顺序。 |
| 屏幕阅读器 | 至少使用一个屏幕阅读器进行测试 - Windows 上的“讲述人”或 NVDA,Mac 上的 VoiceOver。 验证所有元素均已有意义地宣布。 |
| 缩放 | 将浏览器缩放比例增加到 200%,并确保文本和交互式控件保持完全可用。 |
| 减少运动 | 在 OS 设置中启用减少运动,并验证动画是否已最小化或禁用。 |
| 快速响应 | 在代表 Teams 聊天容器宽度的窄视区宽度下进行测试。 在 iOS 和 Android 版 Teams 中,测试纵向和横向。 验证主要内容是否未被剪裁,并且操作是否可通过触摸使用,而无需依赖悬停。 请参阅 响应式缩放。 |
| 高对比度 | 启用 Windows 高对比度模式,并验证内容、控件和焦点指示器仍然可见。 |