Combobox (Autocomplete / Typeahead) 组合框 Combobox（自动补全 / 输入联想） web
A text input paired with a filtered list of selectable suggestions
一个文本输入框，配一个按输入过滤、可供选择的建议列表
标本可交互 —— 点点看。Specimen is live — try it.
Anatomy — every part, named解剖 —— 每个部件的名字
-
1 Combobox input组合框输入框
role="combobox"“The searchable dropdown field I type into” is the combobox input.
「我往里打字、能搜索的那个下拉框」就是组合框输入框。
Prompt fragmentPrompt 片段the role="combobox" text input controlling the suggestions popup and retaining DOM focus
role="combobox" 的文本输入框，控制建议弹层并持有 DOM 焦点
-
2 Listbox popup列表弹层（Listbox）
role="listbox"“The matching results underneath the field” are the listbox popup.
「输入框下面那排匹配结果」就是列表弹层。
Prompt fragmentPrompt 片段the role="listbox" suggestions popup anchored directly beneath the combobox input
role="listbox" 的建议弹层，锚定在组合框输入框正下方
-
3 Active option活动选项
aria-activedescendant“The result highlighted as I press the arrow keys” is the active option.
「我按方向键时高亮的那条结果」就是活动选项。
Prompt fragmentPrompt 片段the aria-activedescendant active option, visibly highlighted while DOM focus remains in the combobox input
由 aria-activedescendant 指示的活动选项，视觉上明显高亮，DOM 焦点始终留在组合框输入框里
-
4 Selected-option checkmark已选项对勾
aria-selected“The checkmark next to the choice I already picked” is the selected-option indicator.
「我已经选中的那项旁边的对勾」就是已选项指示。
Prompt fragmentPrompt 片段the checkmark beside a role="option" with aria-selected="true" in the combobox listbox
组合框列表中 aria-selected="true" 的 role="option" 旁边的对勾
Prompt — paste into your agentPrompt —— 直接粘贴给你的代理
Build a labelled Combobox with role="combobox" and a controlled role="listbox" popup. Keep aria-expanded and aria-controls in sync, give each result role="option", retain DOM focus in the input with aria-activedescendant, and support Arrow keys, Enter, and Escape without autofocusing on mount.
构建一个带标签的组合框（Combobox）：输入框用 role="combobox"，受控的建议弹层用 role="listbox"。保持 aria-expanded 和 aria-controls 同步，给每个结果 role="option"；DOM 焦点留在输入框里，用 aria-activedescendant 指示高亮项；支持方向键、Enter、Escape，挂载时不要自动聚焦。
Debug prompt — when it misbehaves调试 Prompt —— 当它不听话时
Debug my combobox (role=combobox, aria-activedescendant, cmdk/Radix). Rule out: the listbox closing on blur before the option click lands — handle selection on pointerdown or check relatedTarget; the highlighted index not resetting when the filter changes; aria-activedescendant pointing at a filtered-out option id; the mobile keyboard covering the list because nothing scrolls the field into view. The symptom:
调试我的组合框（role=combobox、aria-activedescendant、cmdk/Radix）。排查：blur 时列表先关闭，选项的点击还没落上——在 pointerdown 里处理选中，或检查 relatedTarget；过滤条件变化后高亮索引没有重置；aria-activedescendant 指向已被过滤掉的 option id；移动端键盘盖住列表，因为没有东西把输入框滚进可视区。症状：
In code代码里叫什么
| Framework框架 | Symbol符号 | Note说明 |
|---|---|---|
| ARIA | role="combobox" | |
| ARIA | role="listbox" | |
| ARIA | aria-expanded | |
| ARIA | aria-controls | |
| ARIA | aria-activedescendant | |
| HTML | <datalist> | a native limited alternative原生但功能有限的替代方案 |