ARIA：列表框角色

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

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

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

当选项卡切换到列表时，如果尚未选择其他项目，则列表中的第一个项目将被选中。上/下箭头可导航列表，按 Shift + 上/下箭头将移动并扩展选择。键入一个或多个字母将导航列表项（相同的字母将转到以该字母开头的每个项目，不同的字母将转到以该整个字符串开头的第一个项目）。如果当前项目具有关联的上下文菜单，则 Shift+F10 将启动该菜单。如果列表项可选中，则可以使用空格键切换 复选框。对于可选列表项，空格键切换其选择，Shift+空格键可用于选择连续项，Ctrl+箭头键可用于移动而不选择，Ctrl+空格键可用于选择非连续项。建议使用复选框、链接或其他方法选择所有项目，并且可以使用 Ctrl+A 作为此快捷键。

当 listbox 角色添加到元素或此类元素变得可见时，屏幕阅读器会在其获得焦点时宣布列表框的标签和角色。如果列表中某个选项或项目获得焦点，则接下来会宣布该项目，然后是该项目在列表中的位置指示（如果屏幕阅读器支持此功能）。随着焦点在列表中移动，屏幕阅读器会宣布相关项目。

关联的角色

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 列表，这些 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 列表识别可见的元素，这些元素标识列表框。如果不存在可见的标签，则应使用aria-label来包含标签。（注意：根据辅助功能 API 约定，“labelled” 使用两个 L 是正确的拼写。）

aria-roledescription

一个可读的字符串值，可以更清晰地识别列表框的作用。屏幕阅读器通常会在读取标签（如果存在）后向用户读取此值，而不是说“列表框”。

• 当单选列表框获得焦点时
  • 如果在列表框获得焦点之前没有选中任何选项，则第一个选项获得焦点。可选地，第一个选项可能会自动选中。
  • 如果在列表框获得焦点之前已选中一个选项，则焦点将设置在选定的选项上。
• 当多选列表框获得焦点时
  • 如果在列表框获得焦点之前没有选中任何选项，则焦点将设置在第一个选项上，并且选择状态不会自动更改。
  • 如果在列表框获得焦点之前已选中一个或多个选项，则焦点将设置在列表中第一个选中的选项上。
• 向下箭头：将焦点移动到下一个选项。可选地，在单选列表框中，选择也可能随焦点一起移动。
• 向上箭头：将焦点移动到上一个选项。可选地，在单选列表框中，选择也可能随焦点一起移动。
• Home（可选）：将焦点移动到第一个选项。可选地，在单选列表框中，选择也可能随焦点一起移动。对于超过五个选项的列表，强烈建议支持此键。
• End（可选）：将焦点移动到最后一个选项。可选地，在单选列表框中，选择也可能随焦点一起移动。对于超过五个选项的列表，强烈建议支持此键。
• 建议所有列表框都使用类型提前输入，尤其是那些超过七个选项的列表框。
  • 键入一个字符：焦点移动到名称以键入的字符开头的下一个项目。
  • 快速连续键入多个字符：焦点移动到名称以键入的字符字符串开头的下一个项目。
• 多选：作者可以实现两种交互模型中的任何一种来支持多选：一种推荐的模型，不需要用户在导航列表时按住修饰键，例如Shift或Control，或者一种需要在导航时按住修饰键才能避免丢失选择状态的替代模型。
  • 推荐的选择模型 - 无需按住修饰键
    • 空格：更改焦点选项的选择状态。
    • Shift + 向下箭头（可选）：将焦点移动到下一个选项并切换其选中状态。
    • Shift + 向上箭头（可选）：将焦点移动到上一个选项并切换其选中状态。
    • Shift + 空格（可选）：从最近选中的项目到焦点项目选择连续的项目。
    • Control + Shift + Home（可选）：选择焦点选项和所有直到第一个选项的选项。可选地，将焦点移动到第一个选项。
    • Control + Shift + End（可选）：选择焦点选项和所有直到最后一个选项的选项。可选地，将焦点移动到最后一个选项。
    • Control + A（可选）：选择列表中的所有选项。可选地，如果所有选项都被选中，它也可能取消选中所有选项。

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

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

1. 取消选择先前选中的选项，将aria-selected设置为false，或完全删除该属性，更改新取消选择的选项的外观以使其看起来未被选中。
2. 选择新选中的选项，在该选项上设置aria-selected="true"并更改新选中的选项的外观以使其看起来已选中。
3. 更新列表框上的aria-activedescendant值，使其成为新选中的选项的 ID。
4. 以视觉方式处理选项的模糊、焦点和选中状态。

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

当用户单击一个选项、在聚焦于一个选项时按下空格或以其他方式切换选项的状态时，必须发生以下情况

1. 切换当前焦点选项的aria-selected状态，如果它是false则将其状态更改为true，如果它是true则将其状态更改为false。
2. 更改选项的外观以反映其选中状态。
3. 更新列表框上的aria-activedescendant值，使其成为用户刚刚交互的选项的 ID，即使他们切换了选项使其未被选中。

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

<p id="listbox1label" role="label">Select a color:</p>
<div
  role="listbox"
  tabindex="0"
  id="listbox1"
  aria-labelledby="listbox1label"
  onclick="return listItemClick(event);"
  onkeydown="return listItemKeyEvent(event);"
  onkeypress="return listItemKeyEvent(event);"
  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>

这本来可以用本机 HTML <select>和<label>元素更容易地处理。

<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>

• 可滚动列表框示例：单选列表框，滚动以显示更多选项，类似于 HTML <select>，其size属性大于 1。
• 带有分组选项的列表框示例：单选列表框，带有分组选项，类似于 HTML <select>，其size属性设置为大于"1"，并且选项使用optgroup元素进行分组。
• 带有可重新排列选项的示例列表框：单选和多选列表框的示例，以及允许添加、移动和删除选项的配套工具栏。

• 为了实现键盘可访问性，作者应管理此角色所有后代的焦点。
• 建议作者在列表未获得焦点时使用不同的样式来表示选中状态，例如，非活动选中状态通常以较浅的背景颜色显示。
• 如果列表框不是另一个部件的一部分，则应将其aria-labelledby属性设置为。
• 如果一个或多个条目不是列表框的 DOM 子元素，则需要设置其他aria-*属性（请参阅ARIA 最佳实践）。
• 如果存在展开列表框的有效理由，则combobox角色可能更合适。

• HTML <select>元素
• HTML <label>元素
• HTML <option>元素
• ARIA：combobox角色
• ARIA：option角色
• ARIA：list角色
• ARIA：listitem角色
• ARIA 最佳实践 - 列表框
• ARIA 角色模型 - 列表框