如何创建无障碍文档

遵循 WCAG 指南创建无障碍文档，包括语义化 HTML、键盘导航、替代文本和包容性内容实践。

当你编写无障碍文档时，你会优先考虑内容设计，使尽可能多的用户都能使用你的文档，而不受其访问和交互方式的限制。

无障碍文档能改善所有人的使用体验。无论用户是通过屏幕阅读器、键盘导航、移动设备，还是慢速网络访问，你的内容都将更清晰、结构更合理、导航更便捷。

本指南介绍创建无障碍文档的最佳实践。无障碍是一项持续的工作。技术和标准会不断演进，始终存在改进的机会。请从影响最大的改动入手，并将无障碍融入你的工作流程。

​

什么是无障碍？

无障碍（有时缩写为 a11y，意指”accessibility”首尾字母之间的 11 个字母）是指有意识地设计和构建尽可能多的人都能使用的网站和工具。无论是临时还是永久性的残障人士，都应当享有与他人同等水平的数字技术可达性。而为无障碍而设计也能惠及所有人，包括那些通过移动设备或在慢速网络上访问你网站的用户。

无障碍的文档应遵循网页无障碍标准，主要是 网页内容无障碍指南（WCAG）。这些指南有助于确保你的内容具有可感知、可操作、可理解和健壮性等特征。

​

开始使用无障碍

让你的文档具备可访问性是一个过程。你不必一次性修复所有问题，也不能一次完成就了事。

如果你刚开始为文档落实无障碍实践，可以考虑采取分阶段的方法：先从影响最大的改动入手，再循序推进。

​

入门

以下是你现在就可以采取的三项措施，来提升文档的可访问性：

1. 运行 mint a11y，识别 content 中的可访问性问题。
2. 为所有图片添加替代文本（alt text）。
3. 检查标题层级，确保每页只有一个 H1，且各级标题按顺序递进。

​

规划你的无障碍工作

最好的工作流程是最适合你团队的那个。下面是开展无障碍工作的一个可行方法：

阶段 1：图像与结构

• 检查所有图像是否包含具有描述性的 alt 文本。
• 审核链接文本，替换”点击这里”等泛泛表述。
• 修复整份文档中的标题层级问题。

阶段 2：导航与媒体

• 在文档中测试键盘导航。
• 测试屏幕阅读器兼容性。
• 为嵌入视频添加字幕和文字稿。
• 检查颜色对比度。

阶段 3：融入你的工作流程

• 在发布新内容前运行 mint a11y。
• 将无障碍检查纳入内容评审流程。
• 添加交互功能时测试键盘导航。
• 确认新的外部链接和嵌入包含合适的标题和说明。

从小处着手，并将无障碍纳入日常工作流程，才能长期坚持。每一次改进都能帮助更多用户顺利使用你的文档。

​

结构化你的内容

结构清晰的内容更便于浏览和理解，尤其有助于依靠标题在页面间移动的屏幕阅读器用户，以及使用键盘进行导航的用户。

​

使用正确的标题层级

每个页面应只有一个 H1 标题，该标题由页面 frontmatter 中的 title: 属性定义。按顺序使用后续标题，避免跳级。例如，不要从 H2 直接跳到 H4。

<!-- 正确 -->
# 页面标题 (H1)

## 主要章节 (H2)

### 子章节 (H3)

### 另一个子章节 (H3)

## 另一个主要章节 (H2)

<!-- 错误 -->
# 页面标题 (H1)

## 主要章节 (H2)

#### 子章节 (H4)

### 另一个子章节 (H3)

同一层级的标题应具有唯一名称。

<!-- 好的示例 -->
## 无障碍功能提示 (H2)

### 编写有效的替代文本 (H3)

### 使用适当的颜色对比度 (H3)

<!-- 不好的示例 -->
## 无障碍功能提示 (H2)

### 提示 (H3)

### 提示 (H3)

​

编写具有描述性的链接文本

链接文本应当有意义，并清楚表明其指向的内容。避免使用诸如”点击这里”或”了解更多”这类含糊的表述。

<!-- 好的示例 -->
了解如何 [配置导航](/organize/navigation)。

<!-- 链接文本与目标之间的关系不明确 -->
[了解更多](/organize/navigation)。

​

让内容便于快速浏览

• 拆分长段落。
• 使用列表呈现步骤和选项。
• 通过提示框突出关键信息。

​

使用正确的表格结构

尽量少用表格，仅在需要呈现由行列标题传达含义的表格数据时使用。

使用表格时，请包含表头，以便屏幕阅读器能将数据与正确的列关联：

良好的表格结构

| 功能 | 状态 | 最近更新 |
| ------- | ------ | ------------ |
| 搜索  | 启用 | 2024-03-15   |
| Analytics | 启用 | 2024-03-10 |
| 导出 | Beta | 2024-03-20 |

较差的示例缺少表头，屏幕阅读器无法说明每一列代表的含义。

​

撰写具描述性的替代文字

替代文字有助于屏幕阅读器用户理解图像，并会在图像加载失败时显示。文档中的图像应包含能够描述图像并清楚说明其用途或包含原因的替代文字。即使提供了替代文字，也不应仅依赖图像来传达信息。请确保你的内容能够表达图像所传达的要点。

进一步了解如何处理图像，请参阅 媒体指南。

​

编写有效的替代文本（alt text）

• 具体明确：描述图像所展示的内容，而不是只说明这是一张图片。
• 简洁凝练：控制在一到两句话。
• 避免冗余：不要以”Image of”开头，因为屏幕阅读器已经知道替代文本与图像相关。但如果这些信息对图像的 context 很重要，可以包含诸如”Screenshot of”或”Diagram of”之类的描述。

<!-- 好的示例 -->
![控制台截图，显示三个活跃项目和两个待处理邀请](/images/dashboard.png)

<!-- 不够有用的示例 -->
![控制台截图](/images/dashboard.png)

​

为图像添加替代文本（alt text）

对于 Markdown 图像，请在方括号中填写替代文本：

![图片说明](/path/to/image.png)

对于 HTML 图片，请使用 alt 属性：

<img
  src="/images/screenshot.png"
  alt="设置面板，已启用无障碍功能选项。选项以橙色矩形框突出显示。"
/>

​

为嵌入内容添加标题

iframe 和视频嵌入需要提供描述性标题：

<iframe
  src="https://www.youtube.com/embed/example"
  title="教程：设置您的第一个文档站点"
></iframe>

​

为可读性而设计

视觉设计的取舍会影响低视力、色盲或其他视觉障碍用户获取你文档信息的可访问性。

​

确保足够的色彩对比度

如果你自定义了主题颜色，请确认对比度符合 WCAG 要求：

• 正文：最低 4.5:1 对比度
• 大号文本：最低 3:1 对比度
• 交互元素：最低 3:1 对比度

请同时测试 light 与深色模式。mint a11y 命令会检查色彩对比度。

良好对比度示例

{
  "colors": {
    "primary": "#0066CC",
    "background": {
      "light": "#FFFFFF",
      "dark": "#1A1A1A"
    }
  }
}

在较差示例中，黄色 (#FFCC00) 与白色背景对比度不足。深色模式下的背景 (#333333) 偏亮，不利于最佳可读性。

​

不要仅依赖颜色

如果你用颜色来传达信息，请同时加入文本标签或 icon。例如，不要仅用红色文字标记错误；请加入错误 icon 或”错误”一词。

​

使用清晰、简洁的语言

• 使用通俗易懂的语言撰写内容。
• 在技术术语首次出现时给出定义。
• 避免冗长拖沓的长句。
• 使用主动语态。

更多写作最佳实践请参阅 风格与语调指南。

​

让代码示例更具可访问性

代码块是技术文档的重要组成部分，但为确保屏幕阅读器用户能理解，它们需要特定的无障碍设计考量。一般而言，请遵循以下指南：

• 将较长的代码示例拆分为更小且逻辑清晰的片段。
• 在代码中为复杂逻辑添加注释。
• 考虑为复杂算法提供文字说明。
• 展示文件结构时，使用带语言标签的实际代码块，而非 ASCII 艺术。

​

指定编程语言

务必为语法高亮声明所用语言。这有助于屏幕阅读器向用户说明代码的 context：

```javascript
function getUserData(id) {
  return fetch(`/api/users/${id}`);
}
```

​

为代码提供上下文

为代码块提供清晰的上下文：

以下函数从 API 获取用户数据：

```javascript
function getUserData(id) {
  return fetch(`/api/users/${id}`);
}
```

这将返回一个解析为用户对象的 Promise。

​

视频与多媒体的可访问性

视频、动画及其他多媒体内容需要提供文本替代，确保所有用户都能获取其中的信息。

​

为视频添加字幕

字幕可让聋人或听力障碍用户更便捷地获取视频内容，也能帮助处于对声音敏感环境的用户以及非母语使用者：

• 为视频中的所有口语内容提供字幕。
• 在字幕中包含相关的音效描述。
• 确保字幕与音频同步。
• 当多人发言时，使用正确的标点并标注说话者。

大多数视频托管平台都支持添加字幕。可上传字幕文件，或先使用自动生成的字幕作为基础，再进行准确性校对。

​

提供文字稿

文字稿为获取视频内容提供了一种替代方式。它可被搜索、更便于引用，并且对屏幕阅读器更加友好：

<iframe
  src="https://www.youtube.com/embed/example"
  title="教程：设置认证"
></iframe>

<Accordion title="视频文稿">
在本教程中，我们将逐步介绍如何设置认证...
</Accordion>

将文字稿放在视频附近，或提供明确的访问链接。

​

考虑提供视频内容以外的替代方案

如果关键信息只出现在视频中：

• 提供等效的文本版本。
• 附上关键截图，并配有描述性替代文本（alt 文本）。
• 编写涵盖同样内容的图文教程。

这样可确保无法访问视频内容的用户仍然能够完成其任务。

​

测试你的文档

定期测试可在用户遇到问题之前发现无障碍问题。

​

使用 mint a11y 检查无障碍问题

使用 mint a11y 命令行界面（CLI）命令自动扫描文档，检测常见的无障碍问题：

mint a11y

该命令会检查：

• 图像和视频缺少替代文本（alt）。
• 颜色对比度不足。

​

解读输出

扫描完成后，你会看到类似如下的报告：

Accessibility Issues Found:

❌ Missing alt text (3 issues)
  - /guides/quickstart.mdx:45 - Image missing alt text
  - /api-reference/users.mdx:12 - Image missing alt text
  - /guides/setup.mdx:89 - Video missing title attribute

⚠️  Color contrast (2 issues)
  - Primary color (#FFCC00) on light background fails WCAG AA (2.1:1)
  - Link color (#FF6B6B) on dark background fails WCAG AA (3.2:1)

✅ 0 issues found in 15 other pages

​

修复常见问题

缺少替代文本：为图像或视频添加描述性替代文本：

<!-- 修改前 -->
![](/images/dashboard.png)

<!-- 修改后 -->
![仪表盘显示三个活跃项目和两个待处理邀请](/images/dashboard.png)

颜色对比度不达标：在 docs.json 中更新主题颜色：

{
  "colors": {
    "primary": "#0066CC",  // 由 #FFCC00 修改而来
    "light": "#3399FF",
    "dark": "#004C99"
  }
}

再次运行 mint a11y 以验证修复结果。

​

使用 flag 进行定向检查

使用 flag 检查特定的无障碍问题：

# 仅检查缺少替代文本的问题
mint a11y --skip-contrast

# 仅检查颜色对比度问题
mint a11y --skip-alt-text

# 发现问题时使 CI/CD 流水线失败
mint a11y --fail-on-error

​

基本键盘导航测试

仅使用键盘浏览文档：

1. 按 Tab 在交互元素间向前移动。
2. 按 Shift + Tab 向后移动。
3. 按 Enter 激活链接和按钮。
4. 确认所有交互元素均可到达，并具有可见的焦点指示。

​

深入开展无障碍测试

如需进行更全面的测试：

• 屏幕阅读器：使用 NVDA（Windows） 或 VoiceOver（Mac） 进行测试。
• 浏览器扩展：安装 axe DevTools 或 WAVE，对页面进行问题扫描。
• WCAG 指南：查阅 Web Content Accessibility Guidelines，了解详细标准。

​

常见问题

我的文档需要符合 WCAG AA 还是 AAA 等级？

大多数组织以 WCAG 2.1 AA 等级为目标，这是众多法律要求采用的标准，并在无障碍性与可行性之间取得了较好的平衡。AAA 等级更为严格，并不适用于所有类型的内容。

请将 AA 等级作为基准。mint a11y 命令会检查 AA 等级常见的要求，例如颜色对比度和替代文本。

如何使用屏幕阅读器测试我的文档？

在 Mac 上，使用内置的 VoiceOver（按 Cmd + F5 启用）。在 Windows 上，下载 NVDA（免费且开源）。仅使用屏幕阅读器浏览你的文档，听一听标题是否被正确播报、链接文本是否具有描述性、图像是否带有替代文本、阅读顺序是否合理。无需成为专家也能发现主要问题。

替代文本与图片说明文字（caption）有何区别？

替代文本 由屏幕阅读器朗读，并会在图像加载失败时显示。它用于描述图像所展示的内容及其相关性。替代文本是无障碍的必要项。

图片说明文字 会显示在图像下方，所有用户均可见。它用于补充背景、署名或解释。图片说明文字是可选的，作为替代文本的补充。

当一张图像既需要描述（替代文本）又需要补充上下文（说明文字）时，二者并用。

可以在无障碍文档中使用表情符号吗？

可以，但要节制使用。屏幕阅读器会朗读表情符号的名称，因此连续多个表情符号会造成干扰。例如，🎉 会被读作 “party popper”，🚀 会被读作 “rocket”，因此 🎉 🚀 会被读作 “party popper rocket”。请避免使用表情符号传达关键信息。即便去掉表情符号，含义也应保持清晰。如有疑问，请改用文字。

如何处理代码示例的无障碍？

为每个代码块指定语言以启用语法高亮。在代码块前后提供上下文，让屏幕阅读器用户理解代码的作用——屏幕阅读器通常会跳过代码本身。将冗长的示例拆分为较小的片段，并使用朗读后仍易于理解的描述性变量名。

如果无法立刻修复所有无障碍问题，该怎么办？

按影响优先级处理。先修复缺失的替代文本、键盘导航失效以及颜色对比度不足——这些问题影响最广。其次是标题层级不当和模糊的链接文本。记录已知问题及其处理计划。逐步推进胜过追求完美。

​

其他资源

通过以下权威资源继续学习无障碍：

• WebAIM：关于网页无障碍的实用文章与教程
• The A11y Project：社区驱动的无障碍资源与检查清单
• W3C Web Accessibility Initiative (WAI)：官方无障碍标准与指南