Combobox 组合框
输入框即控件的可过滤单选组合框:常显可编辑的输入框显示选中项 label,输入实时过滤选项,选中后 value 取 option.value。
与 Select、AutoComplete 的定位差异
- Select:按钮触发下拉,值限定在选项内,输入框不常显;
- AutoComplete:自由文本联想,值可以是任意输入内容(无需来自选项);
- Combobox:输入框即控件,输入仅用于过滤,值必须来自选项(
option.value)。
基础用法
基础用法
点击/聚焦展开下拉;输入关键字实时过滤(filterable 默认开启,子串匹配 label);↑/↓ 移动高亮、Enter 选中、Esc 关闭。
预设值(受控)
预设值(受控 value)
value 为受控属性:选中后回写;外部修改属性同样即时反映到输入框 label。
外部受控设值
外部受控设值
受控模式下宿主可随时通过 value 属性驱动组件显示:
过滤与关闭边界
输入过滤 + 失焦回退
输入未选中直接失焦/按 Esc 时,输入框回退为当前选中项 label(默认非破坏,不丢失已选值)。
不可过滤
关闭过滤(filterable="false")
filterable="false" 时输入不再过滤选项,仅通过键盘 ↑/↓ + Enter 或鼠标选择。
可清空
可清空(clearable)
有选中值时显示清空按钮,点击清空 value 并派发 oas-clear 与 oas-change。
加载中
加载中(loading)
loading 时下拉显示「加载中…」占位(远程数据场景由宿主在请求期间置位)。
空态
无选项(empty)
选项为空时下拉显示「暂无选项」;输入过滤无匹配时显示「无匹配选项」。
禁用
禁用
事件
事件输出
监听 oas-input(过滤词)、oas-change(选中)、oas-clear(清空):
API
属性
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
clearable | 可清空(有值时显示清空按钮,清空派发 oas-clear) | boolean | — |
disabled | 禁用(不可输入、不展开) | boolean | — |
filterable | 输入实时过滤 label(filterable="false" 关闭本地过滤) | string | true |
loading | 加载占位(下拉显示「加载中…」) | boolean | — |
options | 选项,JSON 数组 [{ label, value, disabled? }] | Option[] | string | [] |
placeholder | 占位提示 | — | — |
value | 当前值(受控,选中项 option.value) | string | — |
事件
| 事件 | 说明 |
|---|---|
oas-change | 选中/清空变化,detail: { value } |
oas-clear | 点击清空按钮,detail: { value }(清空前的值) |
oas-input | 输入过滤词,detail: { value } |
键盘:Enter / 聚焦展开,↑/↓ 移动高亮,Enter 选中,Esc 关闭并回退。