ARIA: spinbutton 角色
spinbutton 角色定义了一种范围类型，它要求用户从离散选项中选择一个值。
描述
spinbutton 角色表示该元素是一个输入小部件，其值受限于一组或范围内的离散值。该角色还附带递增和递减功能。例如，在一个允许用户在德州扑克游戏中选择下注金额的小部件中，spinbutton 角色可以允许用户在最小和最大下注之间以递增的方式选择一个数字，具体取决于当前游戏规则。
spinbutton 表示可能值的范围。spinbutton 输入的值表示当前值。
spinbutton 通常有三个组件，包括显示当前值的文本字段、一个递增按钮和一个递减按钮。文本字段通常是唯一可聚焦的组件，因为递增和递减功能可以通过方向键进行键盘访问。通常，文本字段还允许用户直接编辑值。
除了包含 tabindex 属性以启用 spinbutton 焦点外，还必须实现键盘和指针设备支持。必须为键盘用户提供方向键（例如箭头键）支持。必须为指针设备提供单击递增和递减按钮时更改值的支持。请参阅下面的键盘交互。
注意：建议使用 <input type="number"> 元素，或用于日期和时间的其他输入类型，它们也隐式具有 role="spinbutton" 语义，而不是 spinbutton 角色。用户代理为这些输入元素提供样式化小部件，它们提供默认的递增、递减和原生范围限制功能。当使用非语义元素时，所有原生语义元素的特性都需要通过 ARIA 属性、JavaScript 和 CSS 进行重新创建。
ARIA 范围小部件选项
ARIA 为开发人员提供了六种不同的范围小部件角色，包括 progressbar、meter、slider 和 spinbutton。
progressbar 角色，类似于 HTML 的 <progress> 元素，是一个只读范围。它表示任务完成的比例，在一个方向上进展，例如文件上传的加载进度条，在完全加载时最终达到 100%。
meter 角色，类似于 HTML 的 <meter> 元素，是一个只读仪表。它表示已知范围内某个事物的数量，例如电脑的电池指示器或汽车的油量表。
slider 角色，类似于 HTML 的 range 类型的 input，<input type="range">，是一个读写输入范围。滑块允许用户在预定义的最小值和最大值之间选择一个值。用户通过沿着水平或垂直滑块移动滑块拇指来选择一个值。
尽管所有这三个范围都具有相同的 ARIA 状态和属性，但 spinbutton 角色是唯一的读写范围：它是唯一通过用户交互更改其值的范围。因此，它必须能够接收焦点。此外，还必须支持键盘交互、鼠标点击和触摸交互。
警告：要更改 spinbutton 值，基于触摸的辅助技术需要通过合成按键事件来响应用户增加和减少值的手势。在使用 spinbutton 角色（以及所有范围小部件）之前，请在以触摸为主要输入机制的设备上使用辅助技术充分测试 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 | （可选）将值减少一个大于或等于一步的设定量 |
| Home | 将 spinbutton 设置为最小值 |
| End | 将 spinbutton 设置为最大值 |
对于可选的 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 角色。
规范
| 规范 |
|---|
| 无障碍富互联网应用程序 (WAI-ARIA) # spinbutton |
另见
<input type="number"><input type="date"><input type="time">- 其他范围小部件包括
meterscrollbarseparator(如果可聚焦)progressbarslider
- 工作示例