aria-labelledby

适用场景

当页面上已有可见文本描述该元素时使用 — 对话框上方的标题、单元格上方的列标题、区域前的引导段落。aria-labelledby 指向该文本，使屏幕阅读器将其作为元素的无障碍名称播报。用户听到的内容与视力正常的用户所读到的完全一致。

原生 HTML 的对应方式是为表单输入使用 <label for="…">。aria-labelledby 将同样的机制扩展至任何支持名称的角色。

行为说明

值为以空格分隔的元素 ID 列表。辅助技术会按顺序收集每个引用元素的文本内容，以空格拼接后作为无障碍名称。对隐藏元素（display: none、hidden）的引用仍会贡献其文本 — 元素只需存在于 DOM 中即可。

aria-labelledby 的优先级高于 aria-label，aria-label 的优先级高于可见内部文本。因此，若已指向可见标题，无需再额外设置 aria-label。

为保持关联有效：被引用的 ID 必须存在于页面中，必须唯一，且其中的文本必须保持有意义。若重新渲染选项卡面板并复用 ID，需确认新内容仍能准确描述被标注的元素。

常见错误

• 指向不存在的 ID（拼写错误、元素已移除、组件已卸载）。关联会静默失败，导致元素最终没有名称。
• 在页面中重复使用同一 ID — 只有第一个匹配项有效。
• 引用文本为空或仅含空白字符的元素。
• 拼接顺序错误：aria-labelledby="surname firstname" 会产生”Smith John”，而预期是”John Smith”。
• 指向包含长段落的通用 <div> — 整个段落会成为名称。名称应简短；长篇上下文应放入 aria-describedby。
• 本地化时忘记更新被引用的文本 — 名称与可见界面失去同步。

示例

<h2 id="billing-heading">Billing address</h2>
<div role="group" aria-labelledby="billing-heading">
  <label>
    Street
    <input type="text" autocomplete="street-address">
  </label>
  <!-- … -->
</div>

<!-- 拼接两个 ID，实现"名字 + 姓氏"模式 -->
<span id="first">First name</span>
<span id="last">(required)</span>
<input type="text" aria-labelledby="first last">