progressbar

使用场景

优先使用 <progress value="42" max="100">。原生元素在跨浏览器样式定制方面存在局限，这是在自定义 <div> 上改用 role="progressbar" 的主要原因。

进度条分为两种类型：

• 确定型 — 总量已知。设置 aria-valuemin、aria-valuemax，并在任务推进时更新 aria-valuenow。
• 不确定型 — 总量未知。省略 aria-valuenow（或不设置）。屏幕阅读器将播报”忙碌”或”加载中”，而不显示百分比。

当纯数字缺乏语义时，应设置 aria-valuetext——例如，aria-valuetext="正在上传第 3 张，共 8 张" 比”37%“更易于理解。

进度条并非实时区域——屏幕阅读器不会播报每次 aria-valuenow 的变化。如需将变化播报给用户，可在一个配套元素上同时使用 role="status"，并在其中显示人类可读的进度文本。

常见错误

• 在没有 aria-label 的旋转加载图标上使用 role="progressbar"。角色已播报，但任务名称缺失。
• 对不确定型旋转图标使用 role="progressbar" 的同时设置 aria-valuenow="0"，导致始终播报”完成 0%”。
• 任务完成后忘记移除进度条（或其 aria-busy）。部分屏幕阅读器会持续轮询。
• 上传停滞时，进度条搭配的视觉隐藏百分比文本未同步更新，用户长时间停留在无响应状态且毫无提示。
• 在外层容器和内层填充条上都添加 role="progressbar"，造成角色重复——二者选其一即可。

示例

<!-- 推荐用法 -->
<label for="upload">正在上传</label>
<progress id="upload" value="42" max="100">42%</progress>

<!-- 自定义确定型进度条 -->
<div id="uploadLabel">正在上传第 3 张照片，共 8 张</div>
<div
  role="progressbar"
  aria-labelledby="uploadLabel"
  aria-valuemin="0"
  aria-valuemax="100"
  aria-valuenow="37"
></div>