专业版

FaCombobox 组合框

输入搜索 + 下拉选择组件，支持分组、清空、空状态文案、自定义筛选和虚拟化列表。

使用场景

• 可搜索的表单下拉选择
• 城市/地区/人员选择
• 数据量较大的远端或本地选项选择
• 需要自定义关键词匹配规则的选择器
• 输入筛选 + 单选确认的配置项

Props

属性	类型	默认值	说明
disabled	boolean	false	是否禁用
clearable	boolean	false	是否显示清空按钮
position	'inline' | 'popper'	'popper'	下拉内容定位方式
options	(Option | GroupOption)[]	必需	选项数据
placeholder	string	-	输入框占位文本
emptyText	string	''	空状态文案
filter	(searchValue: string, option: Option) => boolean	-	自定义筛选函数
virtualList	boolean	false	是否启用虚拟化列表
class	HTMLAttributes['class']	-	自定义 CSS 类

Option 接口

interface Option {
  label: string
  value: AcceptableValue
  disabled?: boolean
}

GroupOption 接口（分组选项）

interface GroupOption {
  label: string
  options: Option[]
}

Slots

名称	说明
empty	自定义空状态内容

Events

事件名	说明	回调参数
change	选中值变化时触发	value: AcceptableValue | undefined
clear	点击清空按钮时触发	-

注意事项

1. v-model 绑定：使用 v-model 实现选中值的双向绑定
2. 单选组件：当前组件仅支持单选，不支持多选
3. 选项数据结构：options 支持普通选项和分组选项两种格式
4. 默认筛选：未传入 filter 时，组件使用不区分大小写的 label.includes(searchValue) 匹配
5. 自定义筛选：filter 会同时作用于普通列表和虚拟列表，返回 true 时保留该选项，返回 false 时隐藏该选项
6. 虚拟化列表：数据量较大时建议开启 virtual-list，减少渲染压力
7. 分组限制：开启 virtual-list 后会按扁平选项渲染，不显示分组标题
8. 清空按钮：clearable 模式下，仅当组件有选中值或输入内容且获得焦点或悬停时显示清空按钮
9. 空状态：可通过 emptyText 设置简单文案，也可以使用 empty 插槽自定义内容
10. z-index：下拉内容的 z-index 默认为 2000，确保在其他内容上方显示