nex_design_system/docs/14-accessibility-platform-m...

76 lines
5.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 14. Cross-platform Assistive Technology Test Matrix
## 1. 目的
本文件定义 NEX 项目如何选择真实辅助技术(AT)验证环境。**VoiceOver 不是跨平台唯一方案,也不是日常开发的默认工具。** Agent 必须根据产品声明支持的操作系统、浏览器和用户群选择匹配的测试组合。
## 2. 平台建议矩阵
| 目标平台 | 优先考虑的屏幕阅读器 | 建议浏览器组合 | 适用说明 |
|---|---|---|---|
| macOS | VoiceOver(系统内置) | Safari;如产品主要支持 Chrome,也增加 Chrome 组合 | 验证 macOS 原生辅助技术与 Web 内容的实际交互 |
| Windows | NVDA(免费) | Firefox 或 Chrome/Edge,按产品支持范围选择 | 可按企业客户/用户群补充 JAWS;可用 Narrator 做系统内置辅助抽查 |
| Linux | Orca(GNOME 常见读屏器) | 优先 Firefox;若产品明确支持 Chromium,再补充该组合 | 需记录发行版、桌面环境、AT-SPI 支持和浏览器版本;不同桌面/浏览器组合能力可能不同 |
这些是建议起点,不是宣称所有版本和组合都等价或完全兼容。测试报告必须记录真实 OS、发行版/桌面环境、浏览器、屏幕阅读器及版本。不得把 macOS VoiceOver 结果外推为 Windows NVDA 或 Linux Orca 结果。
## 3. 如何选择需要测试的平台
1. 先读取产品支持平台、部署环境、用户群和客户合同/无障碍要求。
2. 只对产品实际支持或明确承诺的平台建立 AT 测试矩阵;不因 NEX 本身而强制测试所有桌面操作系统。
3. 普通页面、静态内容和常规原生控件优先通过 E0–E2 日常验证;不要求每个提交都执行 E3。
4. 自定义复合控件、拖拽/排序、复杂 Tabs/菜单/导航、动态 Live Region、复杂数据表格、关键流程或已有 AT 缺陷,按风险触发 E3。
5. 对高风险功能,选择实际用户占比最高或合同明确要求的代表性平台/AT;若产品承诺跨平台且交互实现存在平台差异,应增加对应组合。
6. 若受法规、招标、客户验收或无障碍声明约束,按明确要求增加测试矩阵,不以本文件的建议组合替代合同要求。
## 4. 平台不可用时的处理
- Agent 不得在 Windows/Linux 上尝试启动 macOS VoiceOver;不得在 macOS 上假定已安装 NVDA 或 Orca。
- 若当前工作环境没有目标操作系统、浏览器或屏幕阅读器,先完成可执行的 E0–E2,不得伪造 E3 结果。
- E3 被风险判断为必要但环境不可用时,状态标记为 `MANUAL_QA_REQUIRED`,同时记录所需组合、未验证行为、风险和建议测试责任人/设备。
- 若经风险评估 E3 不适用,应记录 `E3_NOT_REQUIRED` 及理由,不需要为了形式完整而开启屏幕阅读器。
- 可在专用测试机、用户提供的设备、人工 QA 或经授权的远程环境完成 E3;不得默认将不同 OS 的读屏器行为视为一致。
## 5. 屏幕阅读器启停与用户环境保护
启动屏幕阅读器可能产生语音输出、改变键盘交互并影响用户当前工作环境,因此:
1. 日常开发、页面巡检和普通浏览器自动化不得自动启动屏幕阅读器。
2. 启动、关闭或切换系统屏幕阅读器前,必须有用户对本次 E3 测试的明确授权;一般开发授权不自动包含这项授权。
3. 测试前记录屏幕阅读器初始状态。若它在测试开始前已由用户开启,Agent 不得擅自关闭。
4. 只有 Agent 在本次已获授权测试中亲自启动的实例,才可在用户授权范围内按约定恢复;不得更改用户的全局辅助功能偏好、语音、快捷键或自动启动设置。
5. 无法安全确认启停状态时,停止自动启停操作,改为由用户/测试人员手动控制并记录。
## 6. 各层测试职责
| 级别 | 默认工具/方式 | 验证范围 | 是否常规 |
|---|---|---|---|
| E0 | 源码、HTML/ARIA、组件 API 审阅 | 语义、名称、状态、结构和实现意图 | 是 |
| E1 | Playwright、axe-core、测试框架 | 自动可检测规则、可访问名称/角色断言、键盘脚本、Live Region DOM 更新等 | 是,按项目支持 |
| E2 | 浏览器 + 键盘/指针/触屏实际操作 | 真实焦点顺序、可操作性、可见焦点、交互结果与反馈 | 是,按影响面 |
| E3 | VoiceOver / NVDA / Orca 等实际 AT | 真实朗读、AT 导航模式、快捷键冲突、Live Region 播报时序和实际用户体验 | 否,按风险触发 |
浏览器自动化可以验证可访问树、DOM 状态和部分交互,但不能完整模拟或证明屏幕阅读器实际播报、阅读模式、快捷键分发和用户听到的内容。反过来,E3 也不取代 E0–E2 的高频回归。
## 7. E3 记录的最低要求
真实 AT 测试记录必须包含:
- 风险理由及被测用户任务;
- OS/发行版/桌面环境、浏览器和 AT 的名称及版本;
- 输入方式、键盘布局、视口和缩放;
- 预期 role/name/state 与预期播报;
- 实际焦点路径和实际听到的播报(关键内容尽量逐字记录);
- 快捷键是否冲突、Live Region 是否播报及播报时序;
- 失败步骤、复现方法、证据和未覆盖的其他组合。
一次 E3 通过只对记录的 OS + 浏览器 + AT 组合和测试范围有效,不自动代表其他平台通过。
## 8. 参考资料
- W3C — WCAG 2.2: https://www.w3.org/TR/WCAG22/
- W3C — WCAG Overview: https://www.w3.org/WAI/standards-guidelines/wcag/
- Playwright — Accessibility testing: https://playwright.dev/docs/accessibility-testing
- Apple — VoiceOver User Guide: https://support.apple.com/guide/voiceover/welcome/mac
- NV Access — NVDA download and supported Windows versions: https://www.nvaccess.org/download/
- GNOME — Orca Screen Reader: https://gnome.pages.gitlab.gnome.org/orca/help/introduction.html