项目正在快速迭代中，API 与视觉细节可能随版本调整，请勿用于生产环境。
仅桌面端保证样式

Select 选择器 ​

移动端：下拉 popper 改为底部选择面板，参见 移动端 · 数据录入。

下拉选择控件：Option 挂载时向 Select 注册，支持单选 / 多选、可搜索与自定义过滤、远程搜索、允许创建、折叠标签、选项分组与键盘导航（上下键高亮、Enter 选中、Esc 关闭、Backspace 删除多选末项）。

基础用法 ​

单选时绑定值为选中项的 value；clearable 默认关闭，开启后有选中值时展示清空按钮，单选点击清空为空串、多选清空为空数组，并触发 clear 事件。

多选与折叠标签 ​

multiple 时绑定值为数组，选中项以可关闭的 tag 呈现，选择后下拉保持打开；collapse-tags 只展示前 max-collapse-tags 个 tag（默认 1），其余折叠为 + N 计数，避免撑高筛选区。

选中数上限 ​

max-count 限定多选最多可选中数量：达到上限后其余选项呈置灰态、点击被拦截，已选标签可照常移除，移除后立即恢复可选；0 表示不限。

可搜索 ​

filterable 开启后可在输入框中按 label 关键字过滤选项；需要按拼音、编码等自定义规则过滤时传 filter-method（(query, option) => boolean 返回是否保留）。

允许创建 ​

allow-create 配合 filterable：搜索无匹配项时把当前输入作为临时选项出现在下拉首位，回车选中后写入绑定值，适合标签、备注类自由输入。

远程搜索 ​

remote 声明远程模式：键入时调用 remote-method(query) 拉取选项（示例做了 400ms 防抖），loading 期间下拉展示加载文案，常用于大数据量字典搜索。

数据模式与虚拟滚动 ​

传 options 数组即进入数据模式：无需手写 eb-option，下拉由组件直接渲染；再叠加 virtual 开启虚拟滚动——万级选项只渲染可视窗口，滚动、键盘、过滤全程流畅。

选项分组 ​

eb-option-group 以 label 作为分组标题，把选项按业务维度归组，长列表更易扫读。

对象值形态 ​

label-in-value 开启后绑定值形如 { value, label }（multiple 时为对象数组），业务侧免于二次反查文案；回显同时兼容基础值与对象两种形态，清空仍回落为空串 / 空数组。

当前值：null

下拉面板自定义区块 ​

popup-render 插槽在选项列表之后、下拉面板底部追加自定义区块（对齐 antd 的 dropdownRender 语义），常用于「+ 新增」一类入口；点击区块内元素默认不会关闭下拉。

尺寸与禁用 ​

size 支持 large / small；disabled 禁用整个选择器，单个 option 设置 disabled 则该项不可选（呈置灰态）。

API ​

Select Props

参数说明类型默认值
v-model绑定值，多选时为选中 value 数组；label-in-value 下形如 { value, label }string | number | boolean | array | object
multiple多选，绑定值为数组且选择后下拉保持打开booleanfalse
disabled禁用（同时响应表单禁用态）booleanfalse
size尺寸，支持 large / smallstring
clearable可清空，单选有值或多选非空数组时展示清空按钮booleanfalse
placeholder占位文本（缺省取语言包默认文案）string
filterable可搜索，键入关键字按 label 过滤选项booleanfalse
filter-method自定义过滤函数，返回 true 保留该选项(query, option) => booleannull
remote远程搜索模式，过滤交给 remote-methodbooleanfalse
remote-method远程搜索方法，键入时以当前关键字调用(query: string) => voidnull
loading加载中，下拉展示加载文案booleanfalse
allow-create允许创建无匹配的新选项（需配合 filterable）booleanfalse
collapse-tags多选时折叠超出数量的 tagbooleanfalse
max-collapse-tags折叠模式下展示的 tag 数上限，其余折叠为 + Nnumber1
collapse-tags-tooltip预留参数（当前版本未启用）booleanfalse
label-in-value选中值形如 { value, label }（multiple 为对象数组）；回显兼容基础值与对象两种形态，清空仍为空串 / 空数组booleanfalse
max-count多选选中数上限，达上限后其余选项置灰且点击被拦截，已选标签可照常移除；0 表示不限number0
options数据模式选项数组，传入后下拉由组件渲染，无需手写 option；字段名可用 field-names 重映射{ value, label?, disabled? }[]null
field-names数据模式字段映射 { label, value, disabled }，默认取同名字段，与 Cascader / Tree 的 props 映射能力对齐objectnull
virtual虚拟滚动（需配合 options），万级选项只渲染可视窗口booleanfalse
name原生 name 属性string—
ripple激活涟漪动效开关：聚焦时实体色影向内收拢消散；也可在 Form 上批量关闭或全局 setRipple(false)booleantrue

Select Events

参数说明类型默认值
update:modelValue / change选中值变化（选择、移除 tag、清空、Backspace 均触发；label-in-value 时负载形如 { value, label }）(value) => void—
clear点击清空按钮() => void—
visible-change下拉展开 / 收起(visible: boolean) => void—
remove-tag多选移除某一选中项（tag 关闭或再次点击已选项）(value) => void—
filter-change搜索关键字变化(query: string) => void—
blur焦点真离开组件时触发（Esc 关闭下拉但焦点仍在触发器上不触发）() => void—
focus组件获得焦点时触发（含展开下拉时聚焦输入框 / 触发器）() => void—

Select Slots

参数说明类型默认值
popup-render下拉面板底部自定义区块（对齐 antd dropdownRender），在选项列表之后渲染；点击区块内元素默认不关闭下拉——

Select Methods

参数说明类型默认值
focusfilterable 时聚焦搜索输入框，否则打开下拉() => void—
blur收起下拉并使触发器失焦（焦点离开时触发 blur 事件）() => void—
toggleDropdown切换下拉展开 / 收起() => void—
clearSelection清空选中值() => void—
updateDropdown手动刷新下拉浮层定位() => void—

Option Props

参数说明类型默认值
value选项值（必填）string | number | boolean—
label选项显示文案，缺省显示 String(value)string | number
disabled该项不可选booleanfalse

Option Slots

参数说明类型默认值
default自定义选项内容（如图标 + 文案），缺省显示 label——

OptionGroup Props

参数说明类型默认值
label分组标题文案string
disabled分组禁用（预留声明，禁用请设置在 option 上）booleanfalse

移动端适配 ​

容器环境为 mobile 时（优先级：ConfigProvider platform > 全局 setPlatform() > 自动探测：视口 ≤ 768px 或触屏设备），选择器不再渲染浮动下拉，而是底部弹出选择面板（带遮罩、圆角、安全区适配），点选即回填并关闭；桌面环境保持原形态。下方演示通过 platform="mobile" 强制移动形态（无论当前设备）：