> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.another-horizon.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# 无障碍

> 遵循 WCAG 标准，打造尽可能多用户都能使用的文档。

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

无障碍文档能改善所有人的使用体验。你的内容将更清晰、结构更合理、导航更便捷。

本指南提供了创建无障碍文档的一些最佳实践，但并不完整。你应将无障碍视为一项持续的工作。技术和标准会随时间演变，也将带来改进文档的新机会。

<div id="what-is-accessibility">
  ## 什么是无障碍？
</div>

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

无障碍的文档应遵循网页无障碍标准，主要是 [网页内容无障碍指南（WCAG）](https://www.w3.org/WAI/WCAG22/quickref/)。这些指南有助于确保你的内容具有可感知、可操作、可理解和健壮性等特征。

<div id="getting-started-with-accessibility">
  ## 无障碍入门
</div>

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

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

<div id="first-steps">
  ### 入门
</div>

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

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

<div id="plan-your-accessibility-work">
  ### 规划你的无障碍工作
</div>

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

**阶段 1：图像与结构**

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

**阶段 2：导航与媒体**

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

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

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

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

<div id="structure-your-content">
  ## 结构化你的内容
</div>

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

<div id="use-proper-heading-hierarchy">
  ### 使用正确的标题层级
</div>

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

```mdx theme={null}
<!-- 正确 -->
# 页面标题 (H1)

## 主要章节 (H2)

### 子章节 (H3)

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

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

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

## 主要章节 (H2)

#### 子章节 (H4)

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

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

```mdx theme={null}
<!-- 好的示例 -->
## 无障碍功能提示 (H2)

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

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

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

### 提示 (H3)

### 提示 (H3)
```

<div id="write-descriptive-link-text">
  ### 编写具有描述性的链接文本
</div>

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

```mdx theme={null}
<!-- Good -->
了解如何[配置您的导航](/organize/navigation)。

<!-- Unclear relation between  -->
[了解更多](/organize/navigation)。
```

<div id="keep-content-scannable">
  ### 让内容便于快速浏览
</div>

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

<div id="use-proper-table-structure">
  ### 使用正确的表格结构
</div>

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

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

```mdx theme={null}
| 功能 | 状态 |
| ------- | ------ |
| 搜索  | 启用 |
| Analytics | 启用 |
```

<div id="write-descriptive-alt-text">
  ## 撰写具描述性的替代文字
</div>

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

<div id="write-effective-alt-text">
  ### 编写有效的替代文本（alt text）
</div>

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

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

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

<div id="add-alt-text-to-images">
  ### 为图像添加替代文本（alt text）
</div>

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

```mdx theme={null}
![图片说明](/path/to/image.png)
```

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

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

<div id="add-titles-to-embedded-content">
  ### 为嵌入内容添加标题
</div>

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

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

<div id="design-for-readability">
  ## 为可读性而设计
</div>

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

<div id="ensure-sufficient-color-contrast">
  ### 确保足够的色彩对比度
</div>

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

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

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

<div id="dont-rely-on-color-alone">
  ### 不要仅依赖颜色
</div>

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

<div id="use-clear-concise-language">
  ### 使用清晰、简洁的语言
</div>

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

<div id="make-code-examples-accessible">
  ## 让代码示例更具可访问性
</div>

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

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

<div id="specify-the-programming-language">
  ### 指定编程语言
</div>

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

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

<div id="provide-context-around-code">
  ### 为代码提供上下文
</div>

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

````mdx theme={null}
以下函数从 API 获取用户数据：

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

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

<div id="video-and-multimedia-accessibility">
  ## 视频与多媒体的可访问性
</div>

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

<div id="add-captions-to-videos">
  ### 为视频添加字幕
</div>

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

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

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

<div id="provide-transcripts">
  ### 提供文字稿
</div>

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

```mdx theme={null}
<iframe
  src="https://www.youtube.com/embed/example"
  title="教程：设置认证"
></iframe>

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

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

<div id="consider-alternatives-to-video-only-content">
  ### 考虑提供视频内容以外的替代方案
</div>

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

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

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

<div id="test-your-documentation">
  ## 测试你的文档
</div>

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

<div id="check-for-accessibility-issues-with-mint-a11y">
  ### 使用 `mint a11y` 检查无障碍问题
</div>

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

```bash theme={null}
mint a11y
```

该命令会检查：

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

扫描完成后，查看报告的问题并在你的内容中修复它们。再次运行该命令以验证修复结果。

使用标志（flag）参数来检查特定的无障碍问题。

```bash theme={null}
# Check only for missing alt text
mint a11y --skip-contrast

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

<div id="basic-keyboard-navigation-test">
  ### 基本键盘导航测试
</div>

仅使用键盘浏览文档：

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

<div id="go-deeper-with-accessibility-testing">
  ### 深入开展无障碍测试
</div>

如需进行更全面的测试：

* **屏幕阅读器**：使用 [NVDA（Windows）](https://www.nvaccess.org/) 或 [VoiceOver（Mac）](https://www.apple.com/accessibility/voiceover/) 进行测试。
* **浏览器扩展**：安装 [axe DevTools](https://www.deque.com/axe/browser-extensions/) 或 [WAVE](https://wave.webaim.org/extension/)，对页面进行问题扫描。
* **WCAG 指南**：查阅 [Web Content Accessibility Guidelines](https://www.w3.org/WAI/WCAG22/quickref/)，了解详细标准。

<div id="additional-resources">
  ## 其他资源
</div>

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

* **[WebAIM](https://webaim.org/)**：关于网页无障碍的实用文章与教程
* **[The A11y Project](https://www.a11yproject.com/)**：社区驱动的无障碍资源与检查清单
* **[W3C Web Accessibility Initiative (WAI)](https://www.w3.org/WAI/)**：官方无障碍标准与指南