aria-valuetext为数值控件提供可读状态文本

在无障碍开发中，我们经常需要为数值型控件提供更友好的状态描述。比如，一个进度条显示“65%”，对普通用户来说很直观，但对于依赖读屏软件的用户，如果能听到“上传进度：已完成65%”，体验会好得多。这就是 aria-valuetext 属性的用武之地——它能覆盖默认的数值播报，提供人类可读的文本。

不过，这个属性可不是随便哪个元素都能用的。用错了，不仅没效果，还可能破坏原有的无障碍语义。

哪些HTML元素能直接用 aria-valuetext

简单来说，只有那些语义上明确属于“范围控件”的原生元素才原生支持 aria-valuetext。目前，这个名单很短，主要就是两个： 和 。主流读屏器（如NVDA、VoiceOver、JAWS）对它们的支持也最到位。

这里有个常见的“坑”：很多人会尝试给 元素也加上 aria-valuetext，结果发现浏览器直接把它忽略了。为什么呢？因为 的ARIA角色是 meter，它被设计为只读的静态展示元素，而不是一个用户可以交互调整的“控件”。根据WAI-ARIA规范，aria-valuetext 是专门用于“范围控件”的，用在 上属于无效操作。

• 有效，读屏会播报自定义文本。
• 有效（但注意，需要同时用 aria-valuenow 等属性管理好当前值）。
• 无效，属性会被浏览器静默丢弃。

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

道理其实很清晰。 的定位就是展示一个静态的、不可交互的标量值，比如磁盘使用率、考试分数区间。它不表示一个“正在变化的过程”，用户也不能去拖动它。而 aria-valuetext 在规范里，是绑定在那些“用户可影响其值”的交互控件上的。所以，浏览器和辅助技术（AT）根本不会去处理 上的这个属性。

那如果真想给类似 这样的静态数值展示元素提供更丰富的描述，该怎么办呢？别急，有两条可靠的路径可以走：

• 路径一：角色替换。 放弃原生 ，使用一个通用的
  或 ，然后通过 role="progressbar" 明确声明它是一个进度条角色。接着，手动设置好 aria-valuenow、aria-valuemin、aria-valuemax，这时你就可以自由地使用 aria-valuetext 了。记得加上 aria-busy="false" 来表明这个值不会自动更新，以区别于动态进度条。
• 路径二：标签关联。 保留原生的 ，利用 aria-labelledby 属性将它关联到一个可见的文本元素上。比如，你可以写一个 电量：充足（87%），然后在 上设置 aria-labelledby="meter-label"。读屏器会朗读这个关联标签的内容。这种方式兼容性极佳，而且不会破坏 的默认样式和语义。

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

如果你的控件数值是动态变化的（比如一个实时更新的文件上传进度条），这里有个关键细节：仅仅通过Ja vaScript更新元素的 value 属性是不够的。读屏器可不会智能地根据新数值推断出新的 aria-valuetext 含义。你必须手动、同步地去更新 aria-valuetext 属性的值，否则用户听到的将一直是旧的描述文本。

举个例子，上传进度从30%变到72%：

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

这里有几个实操要点：

• 不要只依赖CSS动画或 value 属性的变更来触发读屏播报，它们“喊不动”读屏器。
• 避免使用写死的静态文本（比如永远都是“加载中”），aria-valuetext 的内容应该真实反映当前的状态和上下文。
• 如果数值变化非常频繁（比如每100毫秒更新一次），建议对 aria-valuetext 的更新做节流处理，否则读屏器可能会不停地“刷屏”播报，反而影响体验。

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

最后分享一个最佳实践：当界面上已经存在清晰、用户可见的状态描述文本时（比如旁边就写着“剩余时间：2分钟”或“健康度：良好”），优先考虑使用 aria-labelledby 将控件指向这个可见文本，而不是额外再写一份 aria-valuetext。

这么做有几个很实际的好处：

• 维护性更好： 可见文本天然需要满足WCAG对颜色对比度、字体大小等视觉要求。而 aria-valuetext 是隐藏内容，容易写得模糊或过长。统一维护一处文本，更不容易出错。
• 本地化更简单： 做多语言翻译时，你只需要翻译那一处可见的DOM文本，不需要额外去处理ARIA属性里的字符串。
• 兼容性更佳： 虽然主流读屏器对 aria-valuetext 的支持已经不错，但 aria-labelledby 的兼容性历史更久、更稳定，尤其是在一些旧版本或特定环境中。

当然，关键点在于：确保你引用的那个元素（比如一个 ）拥有唯一的 id，并且确实存在于DOM中。记住，读屏器最终朗读的，就是那个目标元素里的文字内容，所以务必保证其语义准确、清晰。