Combobox 组合框
结合文本搜索与单项选择，从较长候选列表中快速定位值。
使用概览
适合使用
- 选项较多且用户能通过关键词缩小候选范围时。
不建议使用
- 选项只有少数几个，或允许提交列表之外的自由文本时。
真实示例
工作区搜索选择
从工作区列表中搜索并选择一个值。
正在加载示例…
安装
本地候选警告Registry 地址仅指向当前本地文档站；npm 包也只用于本地候选验证，尚未公开发布。
pnpm dlx shadcn@4.16.0 add http://127.0.0.1:3000/r/combobox.json基础用法
导入
import { Combobox } from "@richardqiu/quartz/combobox";JSX
<Combobox aria-label="工作区" placeholder="搜索工作区" emptyText="没有匹配结果" options={[{ label: "北极星", value: "northstar" }, { label: "Quartz", value: "quartz" }]} />状态与控制摘要
默认
键盘焦点可见
已打开
已选择
空状态
已禁用
label · textactive · booleanAPI 参考
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
options | readonly ComboboxOption[] | 必填 | 提供候选项的标签、值、关键词与禁用状态。 |
组合结构
- 01
Combobox
键盘约定
- 方向键移动活动选项，Enter 选择，Escape 关闭列表框。
可访问性契约
- 文本字段必须暴露 combobox 与 listbox 的关系。
- 禁用选项保持可见，但不能被选中。