自动完成控件的无障碍支持

WAI-ARIA 组合框模式为自动完成控件定义了一组特定的角色和属性。组合框是一个与列表框弹出层配对的输入元素。该模式可确保屏幕阅读器向无法看到可视界面的用户正确播报交互行为、可用选项和当前选择。

将输入框放在带有 role="combobox" 的 div 中。这样会向辅助技术说明该输入框关联了一个弹出列表。在此包装器上设置 aria-expanded={isOpen}，告诉屏幕阅读器建议列表当前是可见还是隐藏。

输入元素本身应具有：aria-autocomplete="list"（弹出层包含建议列表）、aria-haspopup="listbox"（点击或输入内容会打开列表框）、aria-expanded={isOpen}，以及 aria-controls="suggestion-list-id"，指向下拉列表元素的 id。

输入框上的 aria-activedescendant 指向当前高亮选项的 id。当 selectedIndex 为 0 时，设置 aria-activedescendant="option-0"。屏幕阅读器会利用它播报当前处于活动状态的项目，同时不将实际焦点从输入框移开。没有选中任何项目时，请移除该属性，或将其设置为空字符串。

下拉列表容器元素应具有 role="listbox"，以及与输入框的 aria-controls 匹配的唯一 id。此角色会告诉无障碍树，该元素是一个可选择选项的列表。列表框通过输入框上的 aria-activedescendant 间接获得焦点。

每个建议项都应具有 role="option" 和唯一的 id，例如 option-0、option-1 等。添加 aria-selected={index === selectedIndex}，以指示当前高亮的项目。用户使用方向键导航时，屏幕阅读器会播报选项内容以及它是否已被选中。

当用户按下 ArrowDown 且 aria-activedescendant 更新为 option-1 时，VoiceOver 会播报类似“React 钩子，5 个中的第 2 个”的内容。屏幕阅读器会根据 ARIA 标记自动读取选项文本及其在列表中的位置。键盘导航不需要额外的实时区域。

在 macOS 上使用 VoiceOver（按 Cmd+F5 切换），在 Windows 上使用 NVDA（可免费下载）进行测试。定位到输入框并开始输入。确认屏幕阅读器会播报组合框角色、找到的结果数量，以及您使用方向键逐项浏览时的每个选项。将行为与 WAI-ARIA 编写实践指南中的示例进行比较。

建议异步加载时，添加一个视觉上隐藏的 div，并设置 aria-live="polite" 和 aria-atomic="true"。加载完成后更新其文本内容：“找到 5 个结果”或“未找到结果”。屏幕阅读器会在当前播报结束后播报此消息，在不中断用户的情况下让他们了解最新状态。

位于 w3.org/WAI/ARIA/apg 的 WAI-ARIA 编写实践指南（APG）包含专门的组合框模式页面，其中有可运行的代码示例和详细的键盘交互规范。实现自动完成、对话框或选项卡等交互控件时，请始终参考 APG，以确保完全符合无障碍要求。

如果不存在可见的标签元素，请为输入框提供 aria-label：aria-label="Search suggestions"。不要仅依赖 placeholder 作为标签——用户输入内容后占位符会消失，而且并非所有屏幕阅读器都会一致地播报它。带有 htmlFor 的可见 label 元素始终是最佳选择。

自动完成输入框上的 aria-activedescendant 属性有什么作用？

在包装器上使用 role="combobox"，在输入框上使用 aria-autocomplete="list"、aria-expanded、aria-controls 和 aria-activedescendant，将输入框与建议列表关联起来。每个选项都需要 role="option"、唯一的 id 和 aria-selected。为异步结果数量添加 aria-live 区域。