ARIA：列表框 (listbox) 角色 - ARIA

描述

listbox 角色用于标识一个元素，该元素创建一个列表，用户可以从该列表中选择一个或多个静态项目，类似于 HTML <select> 元素。与 <select> 不同，列表框可以包含图像。列表框包含子元素，这些子元素的角色是 option，或其角色是 group 的元素，这些元素又包含角色是 option 的子元素。

强烈建议使用 HTML select 元素，如果只能选择一个项目，则使用一组单选按钮，如果可以选择多个项目，则使用一组复选框，因为需要管理所有后代的焦点，这涉及到大量的键盘交互，而原生 HTML 元素免费提供了此功能。

角色为 listbox 的元素具有隐式 aria-orientation 值 vertical。

当列表通过 Tab 键获取焦点时，如果未选择任何其他项目，则列表中的第一个项目将被选中。上下箭头键用于导航列表，按 Shift + 上/下箭头键将移动并扩展选择。键入一个或多个字母将导航列表项目（相同的字母将导航到以该字母开头的每个项目，不同的字母将导航到以整个字符串开头的第一个项目）。如果当前项目具有关联的上下文菜单，按 Shift+F10 将启动该菜单。如果列表项目是可勾选的，Space 键可用于切换复选框。对于可选择的列表项目，Space 键用于切换其选择状态，Shift+Space 键可用于选择连续项目，Ctrl+箭头键可在不选择的情况下移动，Ctrl+Space 键可用于选择非连续项目。建议使用复选框、链接或其他方法来选择所有项目，Ctrl+A 可用作此操作的快捷键。

当列表框角色添加到元素或此类元素变为可见时，屏幕阅读器在列表框获得焦点时宣布其标签和角色。如果列表中的某个选项或项目获得焦点，它将在之后宣布，如果屏幕阅读器支持，还会指示该项目在列表中的位置。随着焦点在列表中移动，屏幕阅读器会宣布相关项目。

关联的 ARIA 角色、状态和属性

关联角色

option 角色: 需要一个或多个嵌套选项。所有选定的选项都将 aria-selected 设置为 true。所有未选定的选项都将 aria-selected 设置为 false。如果选项不可选择，则省略 aria-selected。
list 角色: 包含 listitem 元素的段落

状态和属性

aria-activedescendant: 保存列表框中当前活动元素的 id 字符串。如果它是选项元素，那么它将是最近交互的选项的 id，无论该选项的 aria-selected 值是 true 还是不是。即使在多选列表框中，也只取一个 id 的值。如果 id 不引用列表框的 DOM 后代，那么该 id 必须包含在 aria-owns 属性的 ID 中。
aria-owns: 这是一个以空格分隔的元素 ID 列表，这些元素不是列表框的 DOM 子元素。此处列出的 ID 不能同时列在任何其他元素的 aria-owns 属性中。
aria-multiselectable: 如果用户可以同时选择多个选项，则包含并设置为 true。如果设置为 true，则每个可选择的选项都应包含 aria-selected 属性并设置为 true 或 false。不可选择的选项不应具有 aria-selected 属性。如果为 false 或省略，则只有当前选定的选项（如果选择了任何选项）才需要 aria-selected 属性，并且必须将其设置为 true。
aria-required: 一个布尔属性，指示必须选择具有非空字符串值的选项。
aria-readonly: 用户无法更改哪些选项被选中或未选中，但列表框在其他方面可操作。
aria-label: 一个人类可读的字符串值，用于标识列表框。如果存在可见标签，则应使用 aria-labelledby 来引用该标签。
aria-labelledby: 标识以空格分隔的元素 ID 列表中的可见元素，这些元素 ID 标识列表框。如果不存在可见标签，则应使用 aria-label 来包含标签。（注意：“labelled”是基于辅助功能 API 约定的正确拼写。）
aria-roledescription: 一个人类可读的字符串值，更清晰地标识列表框的角色。屏幕阅读器通常会在读取标签（如果有）之后，而不是说“列表框”时向用户读取此值。

键盘交互

当单选列表框获得焦点时
- 如果在列表框获得焦点之前没有选中任何选项，则第一个选项获得焦点。可选地，第一个选项可以自动选中。
- 如果在列表框获得焦点之前已选中某个选项，则焦点将设置在该选定选项上。
当多选列表框获得焦点时
- 如果在列表框获得焦点之前没有选中任何选项，则焦点将设置在第一个选项上，并且选择状态没有自动改变。
- 如果在列表框获得焦点之前已选中一个或多个选项，则焦点将设置在列表中第一个选中的选项上。
向下箭头

：将焦点移动到下一个选项。可选地，在单选列表框中，选择也可以随焦点移动。
向上箭头

：将焦点移动到上一个选项。可选地，在单选列表框中，选择也可以随焦点移动。
Home

（可选）：将焦点移动到第一个选项。可选地，在单选列表框中，选择也可以随焦点移动。强烈建议包含超过五个选项的列表支持此键。
End

（可选）：将焦点移动到最后一个选项。可选地，在单选列表框中，选择也可以随焦点移动。强烈建议包含超过五个选项的列表支持此键。
所有列表框都建议使用预输入（Type-ahead），特别是包含超过七个选项的列表框。
- 键入一个字符：焦点移动到下一个以键入字符开头的项目。
- 快速键入多个字符：焦点移动到下一个以键入字符字符串开头的项目。
多选：作者可以实现两种交互模型中的任何一种来支持多选：一种推荐模型，不需要用户在导航列表时按住修饰键（如 Shift 或 Control），另一种替代模型，在导航时需要按住修饰键以避免丢失选择状态。
- 推荐选择模型 — 无需按住修饰键
  - 空格键：更改焦点选项的选中状态。
  - Shift + 向下箭头（可选）：将焦点移动到下一个选项并切换其选中状态。
  - Shift + 向上箭头（可选）：将焦点移动到上一个选项并切换其选中状态。
  - Shift + 空格键（可选）：选择从最近选择的项目到焦点项目的连续项目。
  - Control + Shift + Home（可选）：选择当前聚焦的选项以及直到第一个选项的所有选项。可选地，将焦点移动到第一个选项。
  - Control + Shift + End（可选）：选择当前聚焦的选项以及直到最后一个选项的所有选项。可选地，将焦点移动到最后一个选项。
  - Control + A（可选）：选择列表中的所有选项。可选地，如果所有选项都已选中，它也可以取消选择所有选项。

所需的 JavaScript 功能

在单选列表框中选择一个选项

当用户选择一个选项时，必须发生以下情况：

取消选择之前选中的选项，将 aria-selected 设置为 false，或者完全删除该属性，从而改变新取消选中的选项的外观使其看起来未选中。
选择新选中的选项，将选项上的 aria-selected="true"，并改变新选中的选项的外观使其看起来被选中。
将列表框上的 aria-activedescendant 值更新为新选中选项的 ID。
视觉上处理选项的失焦、聚焦和选中状态

在多选列表框中切换选项的状态

当用户点击某个选项，当焦点在该选项上时按下 Space 键，或以其他方式切换选项的状态时，必须发生以下情况：

切换当前聚焦选项的 aria-selected 状态，如果其状态为 false，则将其更改为 true；如果其状态为 true，则将其更改为 false。
改变选项的外观以反映其选中状态
更新列表框上的 aria-activedescendant 值，将其设置为用户刚刚交互的选项的 ID，即使他们将该选项切换为未选中状态。

注意：ARIA 使用的首要原则是，如果有一个具有你所需语义和行为的本地功能，那么就使用它，而不是重新利用一个元素并添加 ARIA 角色、状态或属性来使其可访问。带有后代 <option> 元素的 <select> 元素原生处理所有必要的交互。

示例

示例 1：使用 `aria-activedescendant` 的单选列表框

下面的代码片段使用 aria-activedescendant，展示了如何将列表框角色直接添加到 HTML 源代码中。

html

<p id="listbox1label" role="label">Select a color:</p>
<div
  role="listbox"
  tabindex="0"
  id="listbox1"
  aria-labelledby="listbox1label"
  aria-activedescendant="listbox1-1">
  <div role="option" id="listbox1-1" class="selected" aria-selected="true">
    Green
  </div>
  <div role="option" id="listbox1-2">Orange</div>
  <div role="option" id="listbox1-3">Red</div>
  <div role="option" id="listbox1-4">Blue</div>
  <div role="option" id="listbox1-5">Violet</div>
  <div role="option" id="listbox1-6">Periwinkle</div>
</div>

const listbox = document.getElementById("listbox1");
listbox.addEventListener("click", listItemClick);
listbox.addEventListener("keydown", listItemKeyEvent);
listbox.addEventListener("keypress", listItemKeyEvent);

这本可以通过原生 HTML <select> 和 <label> 元素更轻松地处理。

html

<label for="listbox1">Select a color:</label>
<select id="listbox1">
  <option selected>Green</option>
  <option>Orange</option>
  <option>Red</option>
  <option>Blue</option>
  <option>Violet</option>
  <option>Periwinkle</option>
</select>