ARIA: spinbutton 角色

描述

spinbutton 角色表示該元素是一個輸入小部件，其值受限於一組或範圍內的離散值。該角色還附帶遞增和遞減功能。例如，在一個允許使用者在德州撲克遊戲中選擇下注金額的小部件中，spinbutton 角色可以允許使用者在最小和最大下注之間以遞增的方式選擇一個數字，具體取決於當前遊戲規則。

spinbutton 表示可能值的範圍。spinbutton 輸入的值表示當前值。

spinbutton 通常有三個元件，包括顯示當前值的文字欄位、一個遞增按鈕和一個遞減按鈕。文字欄位通常是唯一可聚焦的元件，因為遞增和遞減功能可以透過方向鍵進行鍵盤訪問。通常，文字欄位還允許使用者直接編輯值。

除了包含 tabindex 屬性以啟用 spinbutton 焦點外，還必須實現鍵盤和指標裝置支援。必須為鍵盤使用者提供方向鍵（例如箭頭鍵）支援。必須為指標裝置提供單擊遞增和遞減按鈕時更改值的支援。請參閱下面的鍵盤互動。

ARIA 範圍小部件選項

ARIA 為開發人員提供了六種不同的範圍小部件角色，包括 progressbar、meter、slider 和 spinbutton。

progressbar 角色，類似於 HTML 的 <progress> 元素，是一個只讀範圍。它表示任務完成的比例，在一個方向上進展，例如檔案上傳的載入進度條，在完全載入時最終達到 100%。

meter 角色，類似於 HTML 的 <meter> 元素，是一個只讀儀表。它表示已知範圍內某個事物的數量，例如電腦的電池指示器或汽車的油量表。

slider 角色，類似於 HTML 的 range 型別的 input，<input type="range">，是一個讀寫輸入範圍。滑塊允許使用者在預定義的最小值和最大值之間選擇一個值。使用者透過沿著水平或垂直滑塊移動滑塊拇指來選擇一個值。

儘管所有這三個範圍都具有相同的 ARIA 狀態和屬性，但 spinbutton 角色是唯一的讀寫範圍：它是唯一透過使用者互動更改其值的範圍。因此，它必須能夠接收焦點。此外，還必須支援鍵盤互動、滑鼠點選和觸控互動。

通用屬性

aria-valuemin 屬性設定最小值。如果省略或不是數字，則預設為 0 (零)。

aria-valuemax 屬性定義最大值。如果缺失或不是數字，則預設為 100。

aria-valuenow 屬性值必須在最小值和最大值之間（包括兩者）。此屬性對於 spinbutton 和 meter 是必需的，對於 progressbar 是可選的。

對於 spinbutton，除非使用像 <input type="number"> 這樣的語義 HTML 元素，否則如果值更新，aria-valuenow 值也必須以程式設計方式更新。

當 aria-valuenow 數字值不能反映 spinbutton 的預期值時，包含可選的 aria-valuetext 屬性。可選的最小值、最大值和當前值應為數字。當這些數字表示的值不是數字時，應包含 aria-valuetext 屬性，其字串值定義數字值。例如，如果使用 spinbutton 選擇 T 恤尺寸，aria-valuetext 屬性應隨著 aria-valuenow 的增加從 XX-Small 變為 XX-Large。

aria-valuetext 值必須隨著值或 aria-valuenow 的更新而更新。ARIA 屬性支援語義 HTML 元素。雖然 <input> 沒有等效的 HTML 屬性，但您可以在任何 <input> 型別上包含 aria-valuetext。當 aria-valuetext 對於 spinbutton 來說是一個重要特性時，請考慮改用帶有 <option> 元素的 <select>。

需要一個可訪問名稱。如果 spinbutton 角色應用於 HTML <input> 元素，則可訪問名稱可以來自關聯的 <label>。否則，如果存在可見標籤，請使用 aria-labelledby；如果不存在可見標籤，請使用 aria-label。

當不使用 HTML <input> 元素建立 spinbutton 時，請包含 tabindex 屬性以使 spinbutton 可聚焦。spinbutton 角色是使用者互動的，因此需要能夠接收焦點。焦點應放置在 spinbutton 輸入上，而不是放置在遞增和遞減 spinbutton 值的關聯按鈕上。

後代僅限於按鈕或文字

有些使用者介面元件在平臺輔助功能 API 中表示時，只能包含特定內容。spinbutton 的子元素或擁有的元素僅限於一個文字框和兩個按鈕。或者，spinbutton 角色可以應用於 text 輸入，並且可以使用兄弟按鈕來支援遞增和遞減功能。

關聯的 WAI-ARIA 角色、狀態和屬性

aria-valuenow (必需)

設定為介於 aria-valuemin 和 aria-valuemax 之間的十進位制值，表示 spinbutton 的當前值。如果不存在，則沒有預設值。

aria-valuetext

輔助技術通常將 aria-valuenow 的值呈現為數字。如果 aria-valuenow 不準確，請使用 aria-valuetext 為 spinbutton 提供一個更易於理解的值。

aria-valuemin

設定為表示最小值的十進位制值，且小於 aria-valuemax。如果不存在，則沒有預設值。

aria-valuemax

設定為表示最大值的十進位制值，且大於 aria-valuemin。如果不存在，則沒有預設值。

aria-labelledby

定義字串值或標識標記 spinbutton 元素提供可訪問名稱的元素（或多個元素）。可訪問名稱是必需的。

aria-label

定義一個字串值，用於標記 spinbutton 元素。當沒有可見標籤可透過 <label> 或 aria-labelledby 提供所需的可訪問名稱時，此屬性為元素提供一個可訪問名稱。

鍵盤互動

對於可選的 Page Up 和 Page Down 鍵，spinbutton 值的更改量最好大於向上和向下箭頭鍵所做的步進更改量。

示例

在下面的示例中，定義了一個 spinbutton 角色，允許使用者選擇月份中的某一天。

<p id="day">Enter the day of the month</p>
<button type="button" tabindex="-1" aria-label="previous day">˱</button>
<div
  role="spinbutton"
  tabindex="0"
  aria-valuenow="1"
  aria-valuetext="first"
  aria-valuemin="1"
  aria-valuemax="31"
  aria-labelledby="day">
  1
</div>
<button type="button" tabindex="-1" aria-label="next day">˲</button>

在此示例中，我們包含了一個負 tabindex 以從預設製表符順序中移除按鈕。我們還將 tabindex 新增到一個通常非互動式的 <div> 中，以便將 spinbutton 本身新增到製表符順序。此示例需要 JavaScript 來處理 spinbutton 獲得焦點時以及滑鼠使用者點選按鈕時的鍵盤操作。

使用語義化 HTML

這也可以使用語義化 HTML 編寫，從而無需任何 CSS 或 JavaScript，也無需包含併為額外的遞增和遞減按鈕提供功能。下面的程式碼片段顯示了不使用 spinbutton 角色並使用語義化 HTML 的上一個示例。

<label for="day">Enter the day of the month</label>
<input
  type="number"
  value="1"
  aria-valuetext="first"
  min="1"
  max="31"
  id="day" />

在這種情況下，唯一需要的 JavaScript 是在輸入值更改時更新 aria-valuetext，這在此情況下確實是一個可選功能。

最佳實踐

HTML 的 <input type="number"> 隱式具有 spinbutton 的 role。HTML 的 <input type="date"> 有 3 個巢狀的 spinbutton，分別用於月份、日期和年份。當語義 HTML 表單元素用於其預期目的時，不要使用 aria-valuemax 或 aria-valuemin 屬性；改用 min 和 max。否則，任何全域性 aria-* 屬性和任何其他 aria-* 屬性都適用於 spinbutton 角色。

首選語義化 HTML

建議使用原生 <input> 元素，型別為 number，即 <input type="number">，而不是 spinbutton 角色。

規範

另見

• <input type="number">
• <input type="date">
• <input type="time">
• 其他範圍小部件包括
  • meter
  • scrollbar
  • separator (如果可聚焦)
  • progressbar
  • slider
• 工作示例
  • 日期選擇器旋轉按鈕示例
  • 工具欄示例：字型大小選擇器