aria-level

使用场景

在 role="heading" 上声明标题的层级深度——相当于用 ARIA 选择 <h1>–<h6>。原生标题元素应是首选；只有在需要超过 6 的层级，或受框架限制无法直接使用标题元素时，才使用 role="heading" + aria-level。

同样适用于 role="treeitem"（树中的深度，顶层项从 1 开始）和嵌套 role="list" 中的 role="listitem"（当 DOM 结构本身未体现嵌套关系时）。

行为说明

值为正整数。对于标题，1–6 对应 <h1>–<h6>；超过 6 的值在 ARIA 中合法，但只有少数屏幕阅读器会将其播报出来，因此不应依赖”第 7 级”被正常播报。

对于树节点，层级表示深度：树的根节点为第 1 级，其直接子节点为第 2 级，以此类推。层级数值让屏幕阅读器用户无需查看缩进即可了解自己在层级结构中的位置。

该属性不影响视觉样式。若”ARIA 标题第 4 级”需要呈现为 h4 的外观，须自行编写样式。

常见错误

• 使用 role="heading" 加 aria-level="3"，而非直接使用 <h3>。原生元素可免费提供角色、层级、默认键盘导航和文档大纲集成。
• 在不含 role="heading"、role="treeitem" 或 role="listitem" 的元素上设置 aria-level。该属性对 <button> 或无角色的 <div> 等元素无任何效果。
• 跳级——第 2 级之后紧接第 4 级会破坏文档大纲，并导致 SC 1.3.1 审计不通过。
• 树节点层级错误：第 2 级节点的所有子节点必须为第 3 级。差一位的错误会使”上移一级”/“下移一级”的播报出现混乱。
• 非整数或零值。只有正整数有效；aria-level="0" 会被忽略。
• 在可拖拽树中对节点进行重新排列后，忘记更新 aria-level。

示例

<!-- 超过 h6 的标题（罕见；用于复杂大纲） -->
<div role="heading" aria-level="7">子子子章节</div>

<!-- 树节点通过 aria-level 表达深度 -->
<ul role="tree">
  <li role="treeitem" aria-level="1" aria-expanded="true">
    文档
    <ul>
      <li role="treeitem" aria-level="2">发票</li>
      <li role="treeitem" aria-level="2">合同</li>
    </ul>
  </li>
</ul>