ARIA：spinbutton 角色

spinbutton 角色表示元素是一個輸入小部件，它將值限制為一組或一系列離散值。該角色還附帶增量和減量功能。例如，在一個允許使用者選擇德州撲克遊戲押注金額的小部件中，spinbutton 角色可以允許使用者根據當前遊戲規則，以允許的增量選擇最小和最大押注之間的數字。

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

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

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

ARIA 為開發人員提供了六種不同的範圍 小部件角色，包括進度條、儀表、滑塊和 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，除非使用語義 HTML 元素（例如 <input type="number">），如果值更新，則 aria-valuenow 值也必須以程式設計方式更新。

可選的 aria-valuetext 屬性在 aria-valuenow 數值無法反映 spinbutton 的預期值時使用。可選的最小值、最大值和當前值應為數值。當這些數字代表的值不是數值時，應包含 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 的重要功能時，請考慮使用 <select> 和 <option> 元素代替。

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

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

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

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 提供必需的可訪問名稱時，這為元素提供了可訪問名稱。

在下面的示例中，已定義 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 來編寫此程式碼，從而無需任何 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，這在這種情況實際上是可選功能。

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

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

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

• <input type="number">
• <input type="date">
• <input type="time">
• 其他範圍小部件包括
  • meter
  • scrollbar
  • separator（如果可獲得焦點）
  • progressbar
  • slider
• 工作示例
  • 日期選擇器 spinbutton 示例
  • 工具欄示例：字型大小選擇器