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>