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 示例
  • 工具栏示例：字体大小选择器