Combobox
输入并匹配建议值。中文惯用名：自动补全。设计文档原名：Autocomplete。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.combobox |
| 名称 | Combobox |
| 二级分类 | 数据录入（data-entry） |
| 用途 | 输入并匹配建议值 |
| 描述 | 中文惯用名：自动补全。设计文档原名：Autocomplete。 |
预览
静态结构：Combobox 为触发器（data-slot="combobox-trigger"，显示选中项 label；无选中时显示 placeholder 并弱化配色）+ 受控 Popover 弹层（data-slot="combobox-content"，内为 vendored Command：searchable 时顶部渲染 data-slot="command-input" 过滤输入、列表 data-slot="command-list"、无匹配时 data-slot="command-empty" 显示「无匹配结果」）。候选项为 data-slot="command-item"，以 value 作为 Command 值、label 作为 keywords 参与过滤；当前选中项带 data-checked 标记，点击即选中、写值并关闭弹层，禁用项不可选。Form 内声明非空 name 时外层为 data-slot="form-item" 容器（label + 触发器 + data-slot="form-error"）。
DSL 结构
{
"type": "Combobox",
"props": {
"name": "owner",
"label": "负责人",
"searchable": true,
"placeholder": "搜索并选择成员",
"options": [
{
"label": "张三",
"value": "zhangsan"
},
{
"label": "李四",
"value": "lisi"
},
{
"label": "王五",
"value": "wangwu"
},
{
"label": "赵六",
"value": "zhaoliu"
}
]
}
}何时用
何时使用
- 候选较多（数十项以上）时需要输入关键字快速定位的单选：成员、客户、标签、字典项。
- 候选项 label 可被关键字匹配（按 label 过滤、按 value 定位），用户记得「大概叫什么」但翻不动列表。
- 表单内声明 name 即自动注册为表单项，参与校验与提交。
何时不用
- 候选少且固定（10 项以内）、无需搜索：使用 Select，少一次输入成本。
- 层级候选数据：使用 Cascader / TreeSelect；其中 TreeSelect 支持 searchable，按树过滤。
- 需要用户输入任意文本（不在候选中也要保留）：Combobox 是「选值」控件，自由文本用 Input。
- 需要多选：当前实现为单选。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| searchable 可搜索（缺省） | 弹层顶部过滤输入，按 label 过滤候选 | 候选多，需关键字定位 |
| searchable=false 纯下拉 | 弹层无过滤输入，等同下拉选择 | 候选稍多但无需搜索（10-30 项） |
| 无匹配结果空态 | 弹层内「无匹配结果」提示 | 关键字未命中任何候选时的兜底反馈 |
| 选项级 disabled | 候选项灰化不可选 | 不可指派 / 已停用的候选对象 |
| Form 表单项 | form-item 容器：label + 触发器 + 校验错误行 | 表单内可搜索单选字段（声明 name 自动注册） |
| disabled 禁用 | 触发器半透明不可点开 | 联动未就绪或只读场景 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | string | — | 字段名；在 Form 内声明即自动成为表单项 |
label | string | — | 表单项标签（Form 内由 label 标签呈现） |
rules | FieldRule[] | — | 校验规则 |
options | ComboboxOption[] | [] | 选项列表（可含表达式解析后的数组）；项结构 { label, value: string |
value | `string | number` | — |
placeholder | string | — | 触发器空态文案，同时作为弹层过滤输入的占位文案 |
searchable | boolean | true | 弹层顶部显示过滤输入（按 label / value 匹配） |
disabled | boolean | false | 禁用触发器；选项级禁用用 options 项的 disabled |
onChange | `(value: string | number | undefined) => void` |
className / style | string / CSSProperties | — | 通用：根节点 class 合并 / 内联样式（Form 内为 form-item 容器，独立渲染时为触发器） |
使用规范
- 与 Select 的边界一句话：候选少且固定用 Select，候选多可搜索用 Combobox；两者都是单选值控件。
- 候选 label 是过滤的主依据，需可辨识（成员用「姓名（部门）」而非同名缩写）；value 保持稳定唯一。
- 候选集很大时确认数据已就绪再渲染，避免弹层打开却「无匹配结果」。
- 选中即关闭弹层并立即生效；下游如有关联刷新应放在 onChange 中处理。
- Combobox 无清除按钮（allowClear）；需要「回到未选」时提供一条「全部 / 不限」候选或改用 Select。
正例
- ✓ 指派负责人：options 为成员列表，searchable 输入姓名过滤，选中即回写 ownerId。
- ✓ Form 内「所属客户」：name + rules 必填，未选提交时提示「请选择客户」。
- ✓ 编辑回显：value 传已存 value，触发器显示对应 label 而非原始 id。
反例
- ✕ 十几个固定选项也用 Combobox（应使用 Select，不必让用户额外输入）。
- ✕ 用 Combobox 承载省市区等层级数据（应使用 Cascader / TreeSelect）。
- ✕ 期望 Combobox 支持多选或允许输入候选外的自由文本（当前实现为单选值控件）。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。