aria-label

适用场景

当控件没有可见文本时使用 — 仅有图标的按钮、仅有放大镜图形的搜索框、关闭（×）按钮、社交媒体链接图标。aria-label 中的字符串将成为元素的无障碍名称，屏幕阅读器会用它替代内部文本进行播报。

原生 HTML 的对应方式是为表单输入使用 <label> 元素，或使用可见的按钮文字。只有在两者都不可行时，才应使用 aria-label。

行为说明

接受单个字符串。aria-label 中的内容会覆盖元素内部的任何可见文本 — 无障碍名称是辅助技术用户所听到的内容，但对视力正常的用户不可见。这种不对称性是该属性最常见错误的根源。

字符串不会自动翻译。若网站支持多种语言，aria-label 的值必须像其他界面字符串一样进行本地化。屏幕阅读器将该值视为纯文本 — 不支持 HTML、换行符或任何标记。

若元素具有可见文本，应优先使用指向该文本的 aria-labelledby，以确保可见标签与无障碍名称保持同步。

常见错误

• 在已包含”提交订单”等文字的按钮上添加 aria-label="Click here" — 可见文本被辅助技术隐藏，用户听到的是错误内容。
• 违反 WCAG 2.5.3 名称包含标签：在可见文本为”Send order”的按钮上设置 aria-label="Submit"，导致语音控制用户无法通过说”click Send order”来操作该按钮。
• 在 <div> 或 <span> 等非交互元素上添加 aria-label — 大多数浏览器会忽略它，因为该元素没有支持名称的角色。
• 在页面其余部分已使用其他语言时，忘记翻译该值。
• 在表单字段上用 aria-label 代替真正的 <label>，从而破坏”点击标签以聚焦字段”的交互效果。
• 将操作说明填入 aria-label 而非 aria-describedby。名称应简短；辅助性文字应放入描述中。

示例

<!-- 仅有图标的按钮：无可见文字，必须使用 aria-label -->
<button type="button" aria-label="Close dialog">
  <svg aria-hidden="true" focusable="false">…</svg>
</button>

<!-- 可见文字 + 图标：此处不应使用 aria-label -->
<button type="button">
  <svg aria-hidden="true" focusable="false">…</svg>
  Close dialog
</button>