1. aria-describedby 的基本概念
1.1 什么是 aria-describedby
在 HTML 和无障碍网络中，aria-describedby 是一个用于把一个或多个描述文本与控件相关联的属性。当一个元素拥有 aria-describedby="desc1 desc2" 时，屏幕阅读器会把 id 为 desc1、desc2 的文本作为该控件的描述内容进行朗读。该描述文本应与控件的用途紧密相关，避免冗余信息。
与 aria-label 不同，aria-describedby 提供的是额外的描述信息，而不是直接替代控件的名称。它的作用是补充控件的语义，帮助用户理解复杂的状态或格式要求。描述文本通常放在文档中的独立区域，便于维护与本地化管理。
1.2 aria-describedby 的工作原理
实现时，控件需要一个 aria-describedby 属性，值是一个或多个描述元素的 ID，用空格分隔。屏幕阅读器在聚焦控件时，会把这些描述文本联合起来朗读，提升可访问性。
当描述文本需要随状态变化时，应确保相应的文本节点能被更新，并且描述文本所在的元素应保持可读性，避免被隐藏或从文档中移除，以免丢失朗读信息。
<label for="city">城市</label>
<input id="city" type="text" aria-describedby="city-desc">
<span id="city-desc">请输入所在城市，可包含大小写字母和空格。</span>
2. 在可访问性中的实际应用场景
2.1 表单控件的描述信息
对表单控件而言，描述信息可以告知用户格式要求、长度限制、以及辅助信息。通过 aria-describedby 将这些信息与控件分离，使页面的结构更清晰，维护也更简单。
例如，密码输入框常需要一个长度要求的描述文本；将该描述放在一个独立的元素中，并通过 aria-describedby 引用，屏幕阅读器就能在聚焦时朗读该描述文本，帮助用户判断是否符合要求。描述文本应避免与控件名称重复，以提升信息层级。
2.2 动态状态与可访问性
当控件的状态发生变化时，描述文本也应随之更新。通过 动态修改描述文本的内容，并确保其元素处于可读状态，可以让屏幕阅读器读出更新后的信息。
为了确保更新生效，可以将描述文本设置为一个可读的区域，并在文本变更时触发屏幕阅读器注意到变化。使用 aria-live 或适当的文本更新策略有助于即时朗读。
<label for="age">年龄</label>
<input id="age" type="number" aria-describedby="age-desc">
<span id="age-desc">请输入您的年龄，且不可包含字母。</span><script>const ageInput = document.getElementById('age');const ageDesc = document.getElementById('age-desc');ageInput.addEventListener('input', () => {const v = ageInput.value;if (v <= 0) {ageDesc.textContent = '年龄需要大于0岁。';} else {ageDesc.textContent = '当前输入：' + v;}});
</script>
3. 结合开发流程的最佳实践
3.1 如何在组件库中统一使用
在一个 UI 组件库中，应该规定统一的描述文本命名约定和使用方式。例如，每个带有说明的输入都应有一个对应的描述文本，使用 aria-describedby 进行绑定，描述文本的 ID 命名应保持全局唯一性。制定规范有助于保持一致性与可维护性。
对于自定义控件，应该确保屏幕阅读器能正确读取描述，避免仅通过隐藏文本实现描述而不被朗读。遵循可访问性优先的设计哲学，有助于减少后续修改成本。
3.2 常见错误与排查方法
常见错误包括：描述文本缺失、aria-describedby 引用的 ID 不存在、描述文本内容与控件状态不一致等。排查时可结合浏览器辅助功能调试工具与屏幕阅读器的实际朗读反馈，确保描述链路是闭环的。
在排查时，也要避免使用 display:none 隐藏描述文本，因为屏幕阅读器可能不会朗读被隐藏的文本。优选视觉可见或视觉隐藏但仍对屏幕阅读器可见的实现方式。
<!-- 常见问题：描述文本丢失 -->
<input id="phone" type="tel" aria-describedby="phone-desc">
<small id="phone-desc" class="hidden">用于联系的电话号码，请确保在工作时间内可联系。</small>
4. 代码实战：示例与逐步讲解
4.1 基本用法示例
下面的示例展示最简单的用法：一个输入框通过 aria-describedby 绑定一个描述文本元素。当聚焦输入框时，朗读文本会同时包含控件的名称与描述信息，提升用户理解。确保描述文本与控件的语义关系清晰。
这种做法的好处在于可重复使用：相同的描述文本结构可以应用到多种控件上，避免重复编码。统一的描述文本结构便于维护和本地化。
<label for="search">搜索</label>
<input id="search" type="text" aria-describedby="search-desc">
<span id="search-desc">请输入关键词进行商品搜索。</span>
4.2 结合 aria-live 与动态描述
在需要提示即时变化状态的场景中，可以配合 aria-live 与动态文本更新实现即时朗读。描述文本的更新应保持简练，避免干扰用户的当前操作。动静态描述结合使用，有助于提升实际无障碍体验。
以下示例演示了一个文本输入的描述在用户输入时动态更新，并通过 aria-live 声明方式提示变化。
<label for="email">电子邮件</label>
<input id="email" type="email" aria-describedby="email-desc">
<span id="email-desc" aria-live="polite">请确保使用有效的电子邮件格式。</span><script>const emailInput = document.getElementById('email');const emailDesc = document.getElementById('email-desc');emailInput.addEventListener('input', () => {if (emailInput.value.includes('@')) {emailDesc.textContent = '格式看起来正确。';} else {emailDesc.textContent = '请包含 @ 符号以形成有效的邮箱地址。';}});
</script>
4.3 复杂控件描述（如自定义下拉）
对于自定义控件（如仿造下拉菜单的组件），同样可以通过 aria-describedby 提供额外描述，帮助用户理解当前状态与可用选项。描述文本应与控件的交互文本保持一致，且描述文本区域应在控件可访问的前提下保持可读。避免仅用视觉提示传达信息，要确保屏幕阅读器也能读取到。
下面是一个自定义下拉的描述示例，结合了 aria-describedby 的关联与下拉状态的描述。
<div class="custom-select" aria-describedby="ddl-desc" tabindex="0" role="combobox" aria-expanded="false" aria-controls="ddl-list">请选择一个选项</div>
<ul id="ddl-list" hidden><li>选项A</li><li>选项B</li>
</ul>
<span id="ddl-desc">当前显示的文本是“请选择一个选项”，按下 Enter 键展开列表。</span>
