aria-describedby

使用场景

用于控件旁边的补充信息：日期字段下方的格式提示（“MM/DD/YYYY”）、密码强度规则列表、内联错误信息、复杂控件上方的使用说明。标签回答的是这是什么？；描述回答的是还有哪些需要了解的信息？。

适用于表单输入框、按钮、对话框，以及任何需要在名称之后提供额外上下文的自定义控件。

行为说明

该属性的值是以空格分隔的元素 ID 列表，形式与 aria-labelledby 相同。屏幕阅读器在朗读无障碍名称和角色之后，通常短暂停顿后再朗读描述——例如*“电子邮件，编辑，我们仅会就本订单与您联系。“*多个 ID 按列出的顺序拼接。

描述不是名称。它不会出现在无障碍树的名称字段中，因此 axe-core 不会将其计为控件的标签。若控件没有名称，aria-describedby 无法弥补这一缺失。

若描述内容发生变化（例如出现错误信息），应更新被引用元素的文本内容，而非替换 aria-describedby 的属性值——许多辅助技术在属性本身变化时不会重新朗读，但当引用的文本属于实时区域、或焦点重新进入该字段时，则会重新朗读。

常见错误

• 将本应作为名称的内容用于 aria-describedby，导致控件仍缺少标签——用户听到的是描述，却始终听不到名称。
• 引用了不存在或已被渲染从 DOM 中移除的 ID。
• 将 aria-describedby 添加到不可聚焦的元素上；大多数浏览器仅在元素获得焦点或被直接查询时才暴露其描述。
• 将冗长的营销文案用作描述——冗余的朗读内容会促使用户全局关闭描述功能。
• 忘记关联内联表单错误。aria-describedby="email-error" 配合 aria-invalid="true" 是规范做法；若缺少该引用，错误信息虽可见却无声。
• 对多个字段重复使用同一描述 ID（如 aria-describedby="hint"）——虽然可行，但需确认该文本确实适用于每个字段。

示例

<label for="password">Password</label>
<input
  id="password"
  type="password"
  aria-describedby="pw-rules pw-error"
  aria-invalid="true"
>
<p id="pw-rules">At least 12 characters, including a number.</p>
<p id="pw-error">Password is too short.</p>