web-accessibility

开发期间的 Web 无障碍

构建或审查 UI 时使用此技能。通用规则如下。 特定功能的模式位于 references/ 文件中 — 遇到相应功能时， 请阅读匹配的文件。

每个组件都适用

这些规则适用于你构建的所有内容，无一例外。

优先使用语义化 HTML（SC 1.3.1、4.1.2）

使用与行为匹配的原生元素。操作使用 <button>，导航使用 <a href>，数据输入使用 <input>，选择操作使用 <select>，覆盖层使用 <dialog>。绝不要给 <div> 或 <span> 添加点击处理程序并称其为交互元素。如果没有合适的原生元素，请添加 role、 tabindex="0" 和键盘处理程序（根据需要处理 Enter、Space、方向键）。

键盘可操作性（SC 2.1.1、2.1.2、2.4.3）

每个交互元素都必须可通过 Tab 访问，并可通过键盘操作。 标准按键映射：Enter/Space 用于激活按钮和链接，方向键用于复合控件（单选按钮组、标签面板、菜单、列表框），Escape 用于关闭覆盖层。除有意设置的模态框外，不得设置键盘陷阱。

Tab 顺序必须符合视觉和阅读顺序。绝不要使用大于 0 的 tabindex 值；仅使用 tabindex="0"（加入 Tab 顺序）或 tabindex="-1" （可通过程序聚焦，不在自然 Tab 顺序中）。

焦点可见性（SC 2.4.7、2.4.11、1.4.11）

每个交互元素都需要可见的 :focus-visible 指示器。绝不要在未提供替代方案的情况下编写 outline: none。焦点指示器本身与相邻颜色之间的非文本对比度必须达到 3:1（SC 1.4.11）。

颜色对比度（SC 1.4.1、1.4.3、1.4.11）

文本对比度：普通文本必须 ≥ 4.5:1，大号文本必须 ≥ 3:1（≥ 18pt / ≥ 14pt 粗体）。非文本 UI 元素（边框、图标、焦点环、表单字段边界）必须达到 3:1。

不要对比率进行四舍五入。 计算得出的比率为 4.4999 时，未达到 4.5:1 阈值。请使用 contrast-check.md 中的计算和检查指南进行验证。

颜色绝不能成为传达信息的唯一方式。应搭配文本、图标或图案。

文本替代（SC 1.1.1）

• 信息性图像：提供描述性 alt，传达图像在上下文中的含义。
• 装饰性图像：使用 alt=""。
• 仅含图标的控件：在控件上添加 aria-label，在图标/SVG 上添加 aria-hidden="true"。
• 复杂图像（图表、示意图）：通过 aria-describedby 或相邻文本提供较长的描述。

无障碍名称（SC 4.1.2、2.5.3）

每个交互元素都必须具有可被发现的无障碍名称。对于带有可见文本的控件，无障碍名称必须包含该可见文本 （SC 2.5.3 名称中的标签）。

视觉隐藏内容（sr-only）

sr-only 会在视觉上隐藏元素，同时将其保留在无障碍树中。 如果项目已有此工具类，请使用它。如果没有：

.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip-path: inset(50%);
  white-space: nowrap;
  border: 0;
}

不要使用 display: none、visibility: hidden 或 width: 0; height: 0 — 这三种方式都会从无障碍树或文档流中移除元素。

在以下情况下使用 sr-only：

• 原生输入在视觉上被自定义元素替代时（原生输入使用 sr-only；自定义元素使用 aria-hidden="true"）。
• 输入项之前有对不明显交互方式的文字说明时。
• 视觉呈现（例如，用颜色区分的差异）需要提供适合屏幕阅读器用户的文字等效内容时。

页面级结构

地标和标题（SC 1.3.1、2.4.6）

• 每个页面使用一个 <main>。
• 使用 <nav>、<header>、<footer> 表示相应的地标角色。如果某种地标类型重复出现（例如两个 <nav> 元素），请为每个元素设置唯一的 aria-label。
• 每个页面使用一个 <h1>。标题应构成逻辑清晰的大纲，不得跳过级别。

页面标题（SC 2.4.2）

每个页面（或 SPA 中的每个路由）都应有描述性的 <title>。在 SPA 中，标题应在导航时更新。用途不同的路由应使用不同的标题。

语言（SC 3.1.1、3.1.2）

<html> 使用 lang 声明页面语言。其他语言的行内文本应带有自己的 lang 属性。

跳过链接（SC 2.4.1）

“跳转到主要内容”链接是页面上第一个可聚焦元素。聚焦时，该链接会显示，并将焦点移至 <main> 地标。

实时区域和动态内容（SC 4.1.3）

内容发生变化但焦点未移动时，必须通过 aria-live 区域向屏幕阅读器播报。

这包括：验证结果、成功／错误消息、加载状态、保存确认、筛选结果计数、分数更新、提示消息、异步操作结果。

**实时区域容器必须在注入内容前就存在于 DOM 中。**在同一操作中创建容器并填入内容，不会触发播报。先渲染空容器，再向其中注入内容。

两种语义角色涵盖了大多数情况：

<div role="status"></div>



<div role="alert"></div>

不要在 role="status" 或 role="alert" 元素上显式添加 aria-live 或 aria-atomic——这些角色已经设置了相应属性。

确实需要使用不带角色的 aria-live 区域时（例如自定义日志小组件），请遵循以下规则：

• aria-live="polite" — 等用户完成当前交互后再播报。
• aria-live="assertive" — 立即打断并播报。仅用于真正紧急的错误；过度使用会让用户养成忽略播报的习惯。
• aria-atomic="true" — 发生任何变化时重新播报整个区域。适用于内容完整的消息（如提示消息、状态行），因为只重新播报部分内容没有意义。
• aria-atomic="false"（默认值）— 只播报发生变化的节点。适用于追加内容（如聊天记录、错误列表），此时只需朗读新条目。

加载、空内容和错误状态都需要提供文本，不能只有加载指示器或空白屏幕。加载指示器应使用 role="status"。

动画和运动（SC 2.2.2、2.3.1、2.3.3）

遵循 prefers-reduced-motion。推荐采用由用户选择启用运动效果的模式：

/* No motion by default */
.element {
  opacity: 1;
}

/* Motion only when the user hasn't opted out */
@media (prefers-reduced-motion: no-preference) {
  .element {
    transition: opacity 200ms ease-in-out;
  }
}

任何内容每秒闪烁次数不得超过三次。任何自动播放或循环播放且时长超过 5 秒的动画，都必须可以暂停或停止。

禁用的控件（SC 4.1.2、1.4.3）

优先让控件保持启用状态，在用户触发操作时进行验证，并显示可恢复的错误消息。

如果控件必须显示为不可用，请使用 aria-disabled="true"，而不是 HTML 的 disabled 属性。

使用 aria-disabled 时：

• 在 JS 中同时阻止指针和键盘事件触发操作。
• 在 CSS 中通过 [aria-disabled="true"] 设置不可用状态的样式。
• 该元素仍必须满足对比度要求。

目标尺寸和触控（SC 2.5.1、2.5.8）

交互目标至少应为 24×24 CSS 像素（SC 2.5.8，AA）。如果目标更小，则只有当以其为中心、直径为 24px 的圆形区域与任何相邻目标的圆形区域都不重叠时，才符合要求。

为便于触控操作，目标尺寸应达到 44×44 CSS px，尤其是作为主要交互点的控件。

任何基于路径或多点触控的手势（滑动、拖动、捏合）也必须支持使用单个指针操作（轻触／单击）。仅提供键盘替代操作并不足以满足此项标准；鼠标／触控用户还需要一种基于鼠标／触控、无需拖动的操作方式。

响应式布局和重排（SC 1.4.4、1.4.10、1.4.12）

在 320 CSS px 的视口宽度下，内容必须能够重排且无需水平滚动（SC 1.4.10）。文本放大至 200% 时，不得被裁切或重叠（SC 1.4.4）。避免使用固定高度的容器，以免用户调整文本间距后文本被裁切（SC 1.4.12）。

键盘快捷键（SC 2.1.4）

如果应用将单个可打印字符（不带 Ctrl／Alt／Cmd 的字母、数字或标点符号）绑定为快捷键，则必须允许禁用该快捷键、将其改为包含修饰键的组合，或仅在相关组件获得焦点时启用该快捷键。至少要在焦点位于 <input>、<textarea> 或 contenteditable 元素中时，禁止触发单字符快捷键。

特定功能模式

上述章节适用于所有情况。遇到特定功能时，请阅读此技能的 references/ 目录中对应的参考文件：

功能类型	阅读
表单、输入、验证、字段集	forms.md
对话框、模态框、抽屉、侧边栏	overlays.md
下拉菜单、披露控件、菜单按钮	menus.md
音频、视频、媒体控件	media.md
标签页、树视图、数据网格、组合框、拖放、手风琴、轮播、工具栏、列表框	complex-patterns.md

如果组件与上述任何参考文件都不匹配，请查看 WAI-ARIA Authoring Practices Guide pattern index。 如果没有已记录的模式，请说明你的处理方式，并在实施前请用户确认。