ARIA: progressbar 角色

描述

progressbar 范围控件表明已收到请求，并且应用程序正在朝着完成所请求的操作取得进展。

作者可以设置 aria-valuemin 和 aria-valuemax 来指示进度指示器的最小值和最大值。否则，它们的隐式值遵循 HTML <input type="range"> 的相同规则

• 如果 aria-valuemin 缺失或不是数字，则默认为 0（零）。
• 如果 aria-valuemax 缺失或不是数字，则默认为 100。
• 只有当进度条的最小值不是 0 或最大值不是 100 时，才需要为 progressbar 角色设置 aria-valuemin 和 aria-valuemax 属性。
• 应提供并更新只读的 aria-valuenow，除非值为 indeterminate（不确定），在这种情况下，请不要包含该属性。如果设置了该属性，请确保 aria-valuenow 的值介于最小值和最大值之间。

如果 progressbar 角色应用于 HTML <progress> 元素，则可访问名称可以来自关联的 <label>。否则，如果存在可见标签，请使用 aria-labelledby；如果不存在可见标签，请使用 aria-label。

所有后代都是展示性的

某些用户界面组件，当在平台辅助功能 API 中表示时，只能包含文本。辅助功能 API 无法表示 progressbar 中包含的语义元素。为了解决此限制，浏览器会自动将 presentation 角色应用于任何 progressbar 元素的子元素，因为它是一个不支持语义子元素的角色。

例如，考虑以下包含标题的 progressbar 元素。

<div role="progressbar"><h3>Title of my progressbar</h3></div>

由于 progressbar 的子元素是表示性的，因此以下代码是等效的

<div role="progressbar">
  <h3 role="presentation">Title of my progressbar</h3>
</div>

从辅助技术用户的角度来看，标题不存在，因为前面的代码片段在辅助功能树中等同于以下内容：

<div role="progressbar">Title of my progressbar</div>

关联的 WAI-ARIA 角色、状态和属性

aria-valuenow

仅当值不是不确定时才存在且必需。设置为介于 0（或 aria-valuemin，如果存在）和 aria-valuemax 之间的十进制值，表示进度条的当前值。

aria-valuetext

辅助技术通常将 aria-valuenow 的值显示为百分比。如果这不准确，请使用此属性使进度条值易于理解。

aria-valuemin

设置为表示最小值并小于 aria-valuemax 的十进制值。如果不存在，则默认值为 0。

aria-valuemax

设置为表示最大值并大于 aria-valuemin 的十进制值。如果不存在，则默认值为 100。

aria-label 或 aria-labelledby

定义字符串值或标识用于标记 progressbar 元素（提供可访问名称）的元素。需要可访问名称。

建议使用原生的 <progress> 或 <input type="range"> 元素，而不是 progressbar 角色。用户代理会为 <progress> 元素提供一个可样式化的控件，该控件基于当前 value 相对于 0（最小值）和 max 值。

示例

在下面的示例中，进度条使用了 aria-valuemin 和 aria-valuemax 的默认值 0 和 100

<div>
  <span id="loadinglabel">Loading:</span>
  <span role="progressbar" aria-labelledby="loadinglabel" aria-valuenow="23">
    <svg width="100" height="10">
      <rect height="10" width="100" stroke="black" fill="black" />
      <rect height="10" width="23" fill="white" />
    </svg>
  </span>
</div>

使用语义化 HTML，这可以写成

<label for="loadinglabel">Loading:</label>
<progress id="loadinglabel" max="100" value="23"></progress>

最佳实践

如果进度条描述的是页面特定区域的加载进度，请包含 aria-describedby 属性来引用进度条的状态，并在该区域加载完成之前将其 aria-busy 属性设置为 true。

优先使用 HTML

建议使用原生的 <progress> 或 <input type="range"> 元素，而不是 progressbar 角色。

规范

另见

• HTML <progress> 元素
• 其他范围小部件包括
  • meter
  • scrollbar
  • separator (如果可聚焦)
  • slider
  • spinbutton