keyboard-accessibility

键盘无障碍

将这些规则应用于每个交互元素和功能。示例优先使用 React。只有在纯 JavaScript 与 React 的做法有显著差异时，才会展示纯 JavaScript 示例。详细规则和代码示例收录在 ./reference/ 下。应用或引用规则前，请先阅读相关文件。

核心要求

所有交互功能都必须能仅用键盘完整操作，无需鼠标或触摸；但真正依赖路径移动的功能（例如徒手绘图）除外。键盘可访问不等于“能用 Tab 键聚焦到它”：原生控件和复合控件使用不同的按键约定，用户必须能够到达、操作并离开每个组件。

确认

如果你只是在审查，请直接报告发现的问题，不必暂停。修改现有文件前，请先确认预期的修改范围；如需更多上下文才能准确判断，请先询问，不要猜测。

严重程度等级

等级	含义
严重	完全阻碍键盘和辅助技术（AT）用户完成任务
高	严重影响键盘访问，且没有合理的替代方法
中	造成不便，但存在替代方法
低	最佳实践方面的不足，影响较小

根据对任务的实际影响判断严重程度，而非仅依据规则本身：用户能否到达、操作并离开该组件；是否有关键任务受阻；焦点是否丢失或被放置在误导性的位置。

参考索引

规则和代码示例收录在 ./reference/ 下。应用或引用规则前，请先阅读相关文件。违反规则时的严重程度取决于其影响。

• 严重规则：
  • reference/native-elements.md — 使用原生且可通过键盘访问的元素
  • reference/keyboard-traps.md — 不得形成键盘陷阱
  • reference/widget-keys.md — 预期的按键行为
  • reference/dialogs.md — 对话框焦点管理
• 高严重程度规则：
  • reference/focus-visibility.md — 焦点可见性
  • reference/focus-not-obscured.md — 焦点不可被遮挡
  • reference/focus-order.md — 焦点顺序
  • reference/composite-widgets.md — 复合控件（roving tabindex）
  • reference/visibility-mechanisms.md — aria-hidden 与 hidden、inert 的区别
• 中等严重程度规则：
  • reference/skip-links.md — 跳过链接和地标
  • reference/navigation-and-notifications.md — 导航和通知焦点
  • reference/input-alternatives.md — 字符键快捷键、触摸和指针
• 测试：
  • reference/checklist.md — 测试清单和自动化工具的局限

WCAG 2.2 关键准则

• 2.1.1 键盘（A），违反时为严重
• 2.1.2 无键盘陷阱（A），违反时为严重
• 2.1.4 字符键快捷键（A）
• 2.4.1 绕过区块（A）
• 2.4.3 焦点顺序（A）
• 2.4.7 焦点可见（AA）
• 2.4.11 焦点未被遮挡（最低要求）（AA）
• 2.4.13 焦点外观（AAA）
• 2.5.1 指针手势（A）
• 2.5.3 标签名称（A）
• 2.5.8 目标尺寸（最低要求）（AA）

参考资料

• WAI-ARIA 编写实践指南（APG）
• APG：开发键盘界面
• APG：对话框（模态框）模式
• APG：组合框模式
• MDN：<dialog> 元素
• MDN：inert 属性
• MDN：:focus-visible
• focus-trap-react

标准展望： 这些规则以 WCAG 2.2 AA 为目标。WCAG 3.0 仍在 制定中。键盘和焦点要求预计将保持广泛兼容。请关注 https://www.w3.org/TR/wcag-3.0/.

反模式

• 使用正数 tabindex 值强制调整顺序；应改为调整 DOM 顺序。
• 在应使用 button 或 a 的地方使用可点击的 div 或 span。
• 不加区分地调用 preventDefault()，吞掉预期按键。
• 移除焦点轮廓，却不提供可见的替代样式。
• 在可聚焦元素上设置 aria-hidden="true"，导致焦点无处可去。

---

由 @planetabhi 撰写