ARIA combobox 怎么用 aria-activedescendant 管理列表选项焦点

我在把普通的搜索输入框改成可键盘操作的建议列表时，最容易写错的不是上下箭头，而是“焦点到底在哪里”。如果每次移动选项都把 DOM 焦点移到 option，输入框的编辑体验会变得不稳定；如果焦点始终留在输入框，又必须让辅助技术知道当前选中了哪一项。这个场景正适合 aria-activedescendant。

参考文档：https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/combobox_role

核心做法是：让带 role="combobox" 的输入框继续拥有真实 DOM 焦点，把当前 option 的唯一 id 写入 aria-activedescendant，同时用 aria-controls 指向弹出的 listbox。这样，浏览器的真实焦点和辅助技术感知的活动项各司其职。

先分清 DOM 焦点和虚拟焦点

aria-activedescendant 不会真的调用 focus()，它只是告诉浏览器和辅助技术：当前组合控件里哪一个后代元素相当于“正在被关注”。因此，键盘输入时 document.activeElement 仍然应该是输入框，而不是列表项。

这里有三个容易混淆的点：

• aria-activedescendant 的值是当前活动元素的 id，不是文本、索引或 CSS 选择器。
• 被引用的 option 必须是控件能逻辑拥有的元素，且在视觉上可见；列表滚动时要同步把它带入可视区域。
• 这个属性表达的是辅助技术的焦点感知，不会自动添加高亮样式、滚动行为或上下键逻辑。

把 combobox、listbox 和活动 option 连接起来

一个可编辑的建议列表至少要维护四种关系：输入框是否展开、输入框控制哪个弹层、弹层里的项使用什么语义，以及当前项是哪一个。aria-expanded 应随弹层的显示状态同步；aria-controls 指向 listbox 的 id；每个项使用 role="option" 和稳定唯一的 id。

最小 HTML 可以先把语义关系搭好，业务搜索和异步请求留在外层：

城市

如果弹层不是 listbox，而是 grid、tree 或 dialog，对应的 aria-haspopup 也要写成真实角色。不要把 aria-haspopup="true" 当成通用写法；在 ARIA 语义里，布尔值 true 对应的是 menu。

用键盘事件只更新一个活动项

我更愿意把活动项保存成一个索引或 DOM 引用，再由一个函数统一更新 aria-activedescendant、高亮类和滚动位置。这样不会出现“视觉高亮在第二项、属性却还指向第一项”的分裂状态。

const input = document.querySelector('#city-input');
const list = document.querySelector('#city-list');
const options = [...list.querySelectorAll('[role="option"]')];
let activeIndex = -1;

function setActive(index) {
  // 只允许活动索引落在现有 option 范围内，避免生成无效 ID 引用。
  activeIndex = Math.max(-1, Math.min(index, options.length - 1));
  options.forEach((option, current) => {
    // aria-selected 与视觉类同时更新，避免读屏状态和画面高亮不一致。
    const active = current === activeIndex;
    option.toggleAttribute('aria-selected', active);
    option.classList.toggle('is-active', active);
  });
  const active = options[activeIndex];
  input.setAttribute('aria-activedescendant', active ? active.id : '');
  // 活动项可能在滚动容器外，切换后把它带回可视区域。
  active?.scrollIntoView({ block: 'nearest' });
}

input.addEventListener('keydown', (event) => {
  // 先处理控件导航，普通字符仍交给 input 的原生编辑行为。
  if (event.key === 'ArrowDown') {
    event.preventDefault();
    list.hidden = false;
    input.setAttribute('aria-expanded', 'true');
    setActive(activeIndex + 1);
  } else if (event.key === 'ArrowUp') {
    event.preventDefault();
    setActive(activeIndex 

示例只覆盖焦点与状态关系，没有假定搜索接口如何返回数据。实际项目还要定义 Enter 选中项、Tab 接受当前值、结果为空时如何关闭，以及异步刷新列表后如何重新计算活动索引。

哪些情况不适合 aria-activedescendant

它适合“输入框控制 listbox，DOM 焦点留在输入框”的组合控件，不是所有弹层都应套用。若打开的是 dialog，真实焦点应该移动到对话框内部，因为 dialog 不属于可以用 aria-activedescendant 引用的角色范围。

另外，下面几种实现比属性缺失更容易造成问题：

• 列表项重新渲染后换了 id，但输入框仍引用旧值。
• 弹层关闭时没有清空 aria-activedescendant，读屏用户会得到已经不可见的活动项。
• 用鼠标点击项时只改了输入值，没有让键盘状态、高亮和 aria-selected 一起更新。
• 为了自定义导航拦截所有按键，破坏输入框原本的光标移动、选择和编辑行为。

最后可以按一张小表复查：

相关问题

aria-activedescendant 能代替 option.focus() 吗？在 combobox 控制 listbox 且焦点留在输入框的模式下可以表达活动项，但它不会替你完成键盘逻辑、样式高亮和滚动。

aria-controls 和 aria-owns 要选哪个？新实现优先使用 aria-controls 描述输入框控制的弹层；不要为了兼容旧代码继续把二者混用。