# 无障碍

{% hint style="info" %}
对应的[官方页面地址](https://contributing.bitwarden.com/contributing/accessibility/)
{% endhint %}

Bitwarden 严格遵守 [WCAG AA 要求](https://www.w3.org/WAI/WCAG2AA-Conformance)。以下介绍了在实现功能和内容时应考虑的无障碍的常见方面。此列表并不全面，但它提供了一个起点，让您了解可能会限制无障碍新功能的常见「陷阱」。有关无障碍的全面指南，请访问 [WCAG 官方网站](https://www.w3.org/WAI/WCAG21/Understanding/)。

{% hint style="info" %}
有关 Bitwarden 无障碍的其他资源可以在 [Confluence](https://bitwarden.atlassian.net/wiki/spaces/EN/pages/193953973) 上找到。
{% endhint %}

## 视觉呈现 <a href="#visual-presentation" id="visual-presentation"></a>

| WCAG 成功规范                                                                                                                                                                                                                      | 描述                                                                                                                                                                                                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p><a href="https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html">1.4.3 Contrast minimum</a><br><br><a href="https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html">1.4.11 Non-text contrast</a></p> | <p>内容的对比度应达到或超过 WCAG AA 准则：<br>  - 对于普通文本：4.5:1<br>  - 大型文本和图形：3:1<br>  - 使用  <a href="https://webaim.org/resources/contrastchecker/">WebAIM contrast checker</a> 了解更多信息<br>  - 使用组件库中的变量时， <code>text-main</code> 变量会在 <code>background</code> 和 <code>background-alt</code> 变量上进行测试。所有其他背景一般使用 <code>text-contrast</code></p> |
| [1.4.13 Content on Hover of focus](https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html)                                                                                                                 | **Bitwarden 设计最佳实践**：交互式元素应始终可见，用户无需悬停或聚焦该元素。这样可以使内容更容易被发现，从而便于用户访问，同时也消除了为满足 WCAG 标准而实施这种模式所需的复杂性。                                                                                                                                                                                                                             |
| [2.4.7 Focus visible](https://www.w3.org/WAI/WCAG21/Understanding/focus-visible.html)                                                                                                                                          | **Bitwarden 设计最佳实践**：所有交互式元素都应具有可见焦点、悬停状态和正确的光标样式。                                                                                                                                                                                                                                                                              |
|                                                                                                                                                                                                                                | **Bitwarden 设计最佳实践**：缩短的图标和文本应始终带有 `title` 属性，以提供额外的上下文。                                                                                                                                                                                                                                                                        |

## 键盘导航 <a href="#keyboard-navigation" id="keyboard-navigation"></a>

| WCAG 成功规范                                                                                                                                                                                              | 描述                                                  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- |
| [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html)                                                                                                                            | 页面上的所有鼠标交互元素都应可通过键盘导航访问。                            |
| <p><a href="https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html">2.1.1 Keyboard</a><br><br><a href="https://www.w3.org/WAI/WCAG21/Understanding/no-keyboard-trap">2.1.2 No keyboard trap</a></p> | 如果打开了弹出窗口（尤其是多个对话框），请务必测试焦点是否能正确进出每个对话框，以及是否存在键盘陷阱。 |
| [2.4.7 Focus visible](https://www.w3.org/WAI/WCAG21/Understanding/focus-visible.html)                                                                                                                  | 每个交互式元素都应有一个可见的焦点指示器，以帮助用户通过键盘导航页面。                 |

## 屏幕阅读器 <a href="#screen-reader" id="screen-reader"></a>

弱视或失明用户通常会使用键盘导航和屏幕阅读器来浏览产品。这将导致页面内容的语音朗读，通常还会根据关注的语义元素提供额外的指导。

要进一步了解屏幕阅读器和键盘导航，请在 macOS 上打开 [VoiceOver](https://support.apple.com/en-ca/guide/voiceover/vo2682/mac) 或在 Windows 上下载 [NVDA](https://www.nvaccess.org/download/)，并尝试使用键盘和屏幕阅读器导航设备。

| WCAG 成功规范                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | 描述                                                                                                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [1.1 Text alternatives](https://www.w3.org/WAI/WCAG21/Understanding/text-alternatives)                                                                                                                                                                                                                                                                                                                                                                                    | 对于传递其他地方未提供的信息的任何非文本元素，请使用 `alt-text` 或 aria-labels 标记。如果元素不具有信息性，则可标记为 `decorative`。                                                                                                                                            |
| <p><a href="https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships">1.3.1 Info and relationships</a><br><br><a href="https://www.w3.org/WAI/WCAG21/Understanding/meaningful-sequence">1.3.2 Meaningful sequence</a><br><br><a href="https://www.w3.org/WAI/WCAG21/Understanding/error-identification">3.3.1 Error identification</a><br><br><a href="https://www.w3.org/WAI/WCAG21/Understanding/labels-or-instructions">3.3.2 Labels or instructions</a></p> | <p>确保相关内容一起呈现，并可通过编程确定。<br><br>使用 <code>aria-describedby</code> 将一个元素中的内容与另一个元素关联起来。这通常用于表单错误或辅助文本。</p>                                                                                                                          |
| [4.1.2 Name, role, value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)                                                                                                                                                                                                                                                                                                                                                                                    | 在触发菜单或对话框等其他元素的元素上使用 `aria-haspopup`。这将告诉屏幕阅读器（以及用户），另一个元素正在打开，并将有额外的操作。更多信息，请参阅 [aria-haspopup - Accessibility MDN](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-haspopup)。                  |
| [4.1.2 Name, role, value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)                                                                                                                                                                                                                                                                                                                                                                                    | 在展开或折叠的元素上使用 `aria-expanded` 可显示或隐藏更多信息。注意：`aria-haspopup` 和 `aria-expanded` 不应同时用于同一元素。菜单默认使用 `aria-haspopup`，手风琴或其他显示/隐藏切换器等交互方式则使用 `aria-expanded` 。                                                                          |
| [4.1.2 Name, role, value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)                                                                                                                                                                                                                                                                                                                                                                                    | 当标签页、表格行或网格单元格等多个元素可被选中或取消选中时，请使用 `aria-selected`。更多信息，请参阅 [WAI-ARIA Roles - Accessibility MDN](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles)。                                                          |
| [4.1.2 Name, role, value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)                                                                                                                                                                                                                                                                                                                                                                                    | 大多数 HTML 元素都已分配了角色。但在某些情况下，您可能需要指定元素的角色。有关角色的更多信息，请参阅 [WAI-ARIA Roles - Accessibility MDN](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles)。大多数 Bitwarden 组件库组件都已应用了适用的角色。但在某些情况下，如果您需要创建一个新的组件，则应考虑元素的角色。 |
| [4.1.3 Status messages](https://www.w3.org/WAI/WCAG21/Understanding/status-messages)                                                                                                                                                                                                                                                                                                                                                                                      | 有时，页面上的交互会触发附加内容的添加或更改。例如：点击 「发送验证码」按钮会触发一条确认信息。通过屏幕阅读器公布这些内容非常重要。这可以通过 `aria-live` 区域或使用 `role=alert` 属性来实现。                                                                                                                    |

## 语义结构 <a href="#semantic-structure" id="semantic-structure"></a>

确保在每个页面上使用适当的语义结构。用于创建页面的元素可为屏幕阅读器提供更多上下文信息，使其了解该元素包含的内容类型。正确使用地标和标题，还能让用户仅通过地标或标题级别来浏览页面，而不必总是以标签方式浏览整个页面的内容。

| WCAG 成功规范                                                                                          | 描述                                                                                  |
| -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [3.1.1 Language of page](https://www.w3.org/WAI/WCAG21/Understanding/language-of-page)             | 在每个页面的 `html` 元素中加入 `lang` 属性。                                                      |
| [2.4.2 Page titled](https://www.w3.org/WAI/WCAG21/Understanding/page-titled)                       | 使用一个 `title` 元素和一个 `h1` 在每个页面上显示标题。                                                 |
| [1.3.1 Info and relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships) | 用与内容目的相匹配的、具有语义意义的元素来包装内容。注意：`div` 和 `span` 没有语义意义，因此最好避免使用它们来包转文本。取而代之的是使用 `p` 元素。 |
| [1.3.1 Info and relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships) | 标题层次使用逻辑顺序。`h4` 不应出现在第一个 `h3` 元素之前。此外，不要跳过标题层，应使用下一个降序标题来创建结构。                      |
| [1.3.1 Info and relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships) | 使用地标区域传达预期内容；确保在页面导航周围包含 `nav` 元素，在页面内容周围包含 `main` 元素。                              |
| [1.3.1 Info and relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships) | 使用 `a` 元素和 `hrefs` 作为链接；当用户导航到新页面时使用链接。                                             |
| [1.3.1 Info and relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships) | 使用 `button` 元素提交数据或执行不移动键盘焦点的屏幕操作。                                                  |
| [3.3.2 Labels or instructions](https://www.w3.org/WAI/WCAG21/Understanding/labels-or-instructions) | 使用适当的表单语义，每个输入都有相应的 `label` 元素，并在适用时使用 `fieldset` 元素。                               |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dev.ppgg.in/contributing/accessibility.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.