Microsoft Teams 中 HTML 小组件的辅助功能指南

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 挂钩自动处理此问题。

✅ 应做 ❌ 禁止事项
  • 使用 Fluent UI、React v9 对话框或弹出框实现模式体验
  • 在对话框或面板关闭后将焦点恢复到触发元素
  • 请勿在未提供可访问的替代方案的情况下删除焦点轮廓
  • 在没有明确用户操作的情况下,请勿在控件之间自动推进焦点

屏幕阅读器语义

小组件必须公开有意义的结构和语义,以便屏幕阅读器和其他辅助技术可以正确解释和播报内容。

语义 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="" 或隐藏辅助技术。

✅ 应做 ❌ 禁止事项
  • 使用标题 (<h1>-<h3>) 来构建内容并帮助屏幕阅读器用户导航
  • 将构件视为一个独立的 Web 应用程序 - 不要依赖 Teams 为 iframe 内的内容提供角色或标签
  • 不要在没有角色和标签的情况下使用泛型 <div> OR <span> 元素作为控件
  • 当本机元素已提供所需的行为时,不要使用 ARIA 替代正确的本机语义

焦点管理

由于小组件嵌入在对话体验中,因此小组件中的焦点行为必须是可预测的,并且不得中断用户在聊天中的工作流。

没有焦点窃取

加载小组件时不得在 iframe 内自动移动焦点。 焦点应保留在 Teams 放置的位置,直到用户与构件明确交互。

初始焦点

当用户将焦点移到小组件中时,焦点应落在第一个有意义的交互式元素上,而不是隐藏或非交互式元素上。

对话框和覆盖

如果小组件打开模式对话框:

  • 在对话框打开时将焦点移动到对话框中
  • 在对话框打开时将焦点捕获在对话框内
  • 对话框关闭时,将焦点返回到触发元素

颜色、对比度和高对比度模式

小组件必须在不同的对比度设置(包括 Windows 高对比度模式)下保持可感知。

文本对比度

文本和基本图标必须满足 WCAG 2.2 AA 对比度:

  • 对于普通文本,至少为 4.5:1
  • 对于 18pt 或 14pt 粗体及以上 (大文本,至少为 3:1)

高对比度模式

在 Windows 高对比度模式下测试小组件,并确保交互式元素、焦点指示器和关键图标保持可见且易于理解。 虽然提交时不是必需的,但强烈建议使用高对比度支持,以确保依赖此辅助功能设置的人员可以使用小组件。

颜色独立性

不要仅仅依靠颜色来传达意义。 除颜色外,还可使用文本、图标、图案或其他指示器。

✅ 应做 ❌ 禁止事项
  • 提交前在 Windows 高对比度模式下测试
  • 将颜色与标签或图标配对以传达状态
  • 将 Fluent UI React v9 颜色令牌用于背景、边框和文本
  • 请勿将低对比度文本或图标用于关键信息
  • 不要将占位符文本用作输入的唯一标签
  • 不要对颜色值进行硬编码 - 使用 Fluent UI、React v9 颜色令牌或 CSS 变量,以便小组件适应 Teams 主题

响应式布局和缩放

小组件必须适应聊天容器,并在不同的缩放级别和视区大小下保持可用。

  • 缩放支持: 文本和交互式控件必须在 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 高对比度模式,并验证内容、控件和焦点指示器仍然可见。