标准 · ARIA

状态 全局状态

aria-hidden

将元素及其所有后代从无障碍树中移除。视力正常的用户仍可看到该元素;辅助技术则完全无法访问。应仅用于装饰性内容,切勿将其应用于可聚焦的控件。

适用场景

适用于对屏幕阅读器用户毫无意义的装饰性内容——通常是已有文字标签的图标、分隔线、背景图形,或仅为布局而存在的重复文本。将这些元素标记为 aria-hidden="true" 可使无障碍树专注于有意义的内容。

与类似机制的对比:

  • aria-hidden="true" — 视力正常的用户可见,辅助技术不可见。元素仍占据布局空间。
  • CSS display: none 和 HTML hidden 属性 — 对所有人不可见(视力正常的用户和辅助技术均无法访问)。元素不参与渲染。
  • CSS visibility: hidden — 对所有人不可见,但元素仍占据布局空间。
  • inert 属性 — 元素及其后代无法聚焦,点击事件被抑制,但仍保留在无障碍树中(与 aria-hidden 不同)。适用于模态框背景遮罩和已路由出视图的屏幕。

需特别注意:切勿将 aria-hidden="true" 应用于可聚焦的控件,或包含可聚焦控件的元素。键盘用户仍可通过 Tab 键聚焦到该控件,但屏幕阅读器不会朗读它——用户会落在一个对其完全隐形的控件上。这是 axe-core 报告最频繁的错误之一。

保持同步

有效值为 "true""false""undefined"。实际有用的是 "true""false" 用于覆盖祖先元素的 aria-hidden,实践中几乎不需要。

该状态可以是静态的(始终为装饰性的图标),也可以是动态的。若需切换某区域的 aria-hidden——例如在模态框打开时隐藏主应用内容——应将其与实际视觉状态同步,并配合 inert 属性,确保该区域同时无法被键盘聚焦。

常见错误

  • 在可聚焦元素上使用 aria-hidden="true"——这是 axe-core 报告最多的问题。
  • 使用 aria-hidden 隐藏不希望屏幕阅读器读取的可见文字。应直接删除该文字,或将其移出 DOM。
  • 遗漏对带标签按钮旁纯装饰性图标的 aria-hidden="true" 标记——屏幕阅读器会在朗读按钮标签之外额外朗读图标的无障碍名称。
  • <body><main> 元素上设置 aria-hidden="true" 以锁定模态框后的背景内容,却未同时使用 inert——键盘焦点仍可逃离到背景区域。
  • 使用 aria-hidden="false" 来”显示”被 CSS 隐藏的内容。CSS 仍会将其隐藏。

示例

<button type="button">
  <svg aria-hidden="true" focusable="false" width="16" height="16">…</svg>
  保存
</button>