treeitem

使用时机

在 role="tree" 内部，为每个可见节点使用。若节点有子节点，需设置 aria-expanded="true" 或 "false"，并在其内部包含或拥有一个持有子 treeitem 的 role="group"。若节点没有子节点，则完全省略 aria-expanded（叶节点上不要将其设为 "false"——那样会宣告”已折叠”却无可展开的内容）。

当视觉嵌套无法从 DOM 层级推断时，需在每个 treeitem 上设置 aria-level（从 1 开始的深度）、aria-posinset（在同级中的位置，从 1 开始）和 aria-setsize（同级总数）。

若导航本质上只是”带有嵌套子链接的链接列表”，则优先选择带有嵌套 <ul> 和 <a> 的 <nav>。仅当体验是单制表位层级浏览器时才使用树形视图。

键盘与焦点规范

依据 APG 树形视图模式：

• Tab 键将焦点移入树形结构，定位到当前 treeitem；再次按 Tab 则移出。
• 上/下箭头在可见节点之间移动焦点（跳过已折叠的子节点）。
• 右箭头：若节点已折叠，展开它；若已展开，移至第一个子节点。
• 左箭头：若节点已展开，折叠它；若已折叠，移至父节点。
• Home / End 移至第一个/最后一个可见节点。
• Enter 或 Space 激活（选中）当前项。
• 预读：输入字母将焦点移至下一个匹配的可见节点。

常见错误

• 在叶节点上设置 aria-expanded="false"——宣告了虚假的可折叠状态。
• 每个 treeitem 都有 tabindex="0"。该模式为单制表位；只有聚焦项才携带 tabindex="0"。
• 用右/左箭头表示”下一个同级/上一个同级”而非展开/折叠。
• 将子 treeitem 直接放在父 <li> 内，未使用包裹的 role="group"。屏幕阅读器无法将该组作为一个整体宣告。
• 当 DOM 结构扁平时（例如用绝对定位渲染树形结构），缺少 aria-level。

示例

<ul role="tree" aria-label="Files">
  <li role="treeitem" aria-expanded="true" tabindex="0">
    Documents
    <ul role="group">
      <li role="treeitem" tabindex="-1">Resume.pdf</li>
      <li role="treeitem" aria-expanded="false" tabindex="-1">
        Photos
        <ul role="group">
          <li role="treeitem" tabindex="-1">2025-summer.jpg</li>
        </ul>
      </li>
    </ul>
  </li>
  <li role="treeitem" tabindex="-1">Downloads</li>
</ul>