如何利用HTML的aria-valuetext属性为数值型控件添加易读状态描述？

本文共计983个文字，预计阅读时间需要4分钟。

只有明确属于范围控件（range widget）语义的原生元素才原生支持 `aria-valuetext`。目前仅包括：

常见误解是给 <meter> 加 aria-valuetext —— 它会被浏览器忽略，因为 <meter> 的角色是 meter，不是 widget，WAI-ARIA 规范禁止在非交互/非范围类元素上使用该属性。

• <progress value="65" max="100" aria-valuetext="上传进度：已完成 65%"> ✅ 有效
• <input type="range" aria-valuetext="音量：中等"> ✅ 有效（需同步管理 aria-valuenow）
• <meter value="82" min="0" max="100" aria-valuetext="高水位"> ❌ 无效，属性被静默丢弃

为什么 <meter> 不能加 aria-valuetext，但可以换种方式实现

<meter> 是只读语义标签，设计初衷就是展示静态标量值（如磁盘使用率、电池电量），不表示“正在变化”或“可操作”。而 aria-valuetext 的规范定义绑定在“用户可影响其值”的控件上，所以浏览器和AT不会处理它。

要达成类似效果，有两个可靠路径：

立即学习“前端免费学习笔记（深入）”；

• 用 <div role="progressbar"> 替代 <meter>，显式声明 aria-valuenow、aria-valuemin、aria-valuemax 和 aria-valuetext；注意加上 aria-busy="false" 表明值不自动更新
• 保留原生 <meter>，用 aria-labelledby 关联一个可见的 <span id="meter-label">，比如 <span id="meter-label">电量：充足（87%）</span> —— 这种方式兼容性更好，且不破坏默认样式和语义

动态更新时，aria-valuetext 必须同步修改

如果数值会随 JS 改变（例如上传进度实时刷新），仅改 value 属性是不够的。读屏器不会自动推断新含义，必须手动更新 aria-valuetext 的值，否则会持续播报旧文本。

示例场景：上传进度从 30% 到 72%

const progress = document.getElementById('upload-progress'); progress.value = 72; progress.setAttribute('aria-valuetext', '上传进度：已完成 72%，约剩余 18 秒');

• 不要只依赖 CSS 动画或 value 变更触发读屏播报
• 避免写死静态文本（如始终用“加载中”），应反映真实状态和上下文
• 若值变化频繁（如每 100ms 更新），建议节流播报，防止读屏器刷屏

有可见标签时，优先用 aria-labelledby 而非 aria-valuetext

当界面上已有清晰、用户可见的状态文本（如“剩余时间：2 分钟”“健康度：良好”），直接用 aria-labelledby 指向它，比重复写 aria-valuetext 更可靠、更易维护。

原因很实际：

• 可见文本天然满足 WCAG 对颜色对比度、字体大小等要求，而 aria-valuetext 内容不可见，容易写得模糊或过长
• 翻译、本地化时只需改一处 DOM 文本，不用额外维护 ARIA 属性
• 部分旧版读屏器对 aria-valuetext 支持不稳定，但 aria-labelledby 兼容性极好

关键点：确保 id 唯一、目标元素存在、且内容本身语义准确——读屏器朗读的是那个 <span> 里的文字，不是你脑补的。