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 角色模型 - 列表框