Select 选择器

xy-select 用于后台筛选栏和表单枚举值录入。当前版本已经统一为一套通用枚举选择器，支持单选、多选、远程搜索、创建项、清空和键盘导航。

迁移提示

• 后台项目如果只是想收口 Select 下拉面板的背景、边框、阴影、圆角或宽度，优先使用：
  • popper-class
  • popper-style
  • dropdown-min-width / dropdown-max-width
• 不建议继续在页面层 deep 到 .xy-select__dropdown、.xy-select__option、.xy-select__group 这类内部结构类名。
• 如果你只是想做“dashboard 概览筛选条”风格收口，优先在实例级样式里调整面板气质，而不是在每个业务页单独重写 option、empty、loading 的细节样式。

基础用法

最基础的用法是传入 options，再用 v-model 接住当前选中值。

基础用法单选筛选

支持前缀图标、搜索和自定义选项展示。

已启用

当前选择：已启用

搜索、清空与描述文案

选项支持 description 字段，适合在后台场景里补充状态解释或二级信息。

角色筛选

多选与标签折叠

开启 multiple 后，Select 会输出数组值；collapse-tags 和 max-tag-count 适合在筛选条里控制标签密度。

管理员

禁用态

既可以整体禁用 Select，也可以只禁用部分选项。禁用项适合表达“当前条件下不可选”的状态。

禁用状态禁用

禁用整个选择器或其中部分选项，表示当前不可操作。

财务

包含禁用项

分组选项

当枚举值很多时，可以把选项按业务域或角色域分组，降低认知负担。

请选择角色分组

面板插槽与加载态

header / footer / empty / option 适合把 Select 下拉面板变成更完整的业务选择面板。

选择项目

独立加载态

如果你只需要标准加载态，而不想自定义整块面板，可以直接使用 loading / loading-text。

点击上方按钮重新拉取选项

选择项目

实例级样式收口

当后台项目只想让筛选面板更贴近当前主题时，优先通过 popper-class 和实例级变量收口，而不是继续 deep 到内部类名。

全部业务线

远程搜索

remote 模式下组件只派发 search-change，外部根据关键词更新 options 和 loading 即可。

远程搜索Remote

输入关键词时从远程获取搜索结果，适合大数据量选项。

请选择

Select 这一轮仍然保持“状态项 loading”，不会改成遮罩。默认加载项的 spinner 和文案已对齐独立 Loading，并会读取 ConfigProvider.loading 的 text / spinner / svg / svgViewBox / background 作为视觉默认项；如果传入 loading-text 或自定义 loading 插槽，局部定义依然优先。

表单场景

放在 xy-form-item 内部时，Select 会自动关联错误消息并参与 change / blur 校验。

* 角色

请选择角色

方法控制

通过 expose 的 focus / blur / open / close，可以把 Select 接进更复杂的筛选条或快捷操作面板。

方法控制下拉面板

当前值：未选择，面板状态：关闭

键盘与行为约定

• ArrowDown / ArrowUp 在可选项之间移动。
• Enter / Space 选择当前高亮项。
• Escape 关闭下拉，并把焦点还给触发器。
• multiple 适合标签型筛选，collapse-tags 用于压缩触发器内容。
• remote 打开后，组件不会再做本地过滤，只展示外部传入选项。
• allow-create 适合轻量自定义枚举录入，仍然遵循当前选项值类型。

命名映射

Vue 模板中 props 和 events 使用 kebab-case，源码 / TS 类型层使用 camelCase，两者等价：

Props 映射

模板写法（kebab-case）	源码 / TS 写法（camelCase）
model-value	modelValue
loading-text	loadingText
search-placeholder	searchPlaceholder
create-text	createText
no-data-text	noDataText
no-match-text	noMatchText
prefix-icon	prefixIcon
suffix-icon	suffixIcon
clear-icon	clearIcon
popper-class	popperClass
popper-style	popperStyle
fit-trigger-width	fitTriggerWidth
fit-input-width	fitInputWidth
collapse-tags	collapseTags
max-tag-count	maxTagCount
allow-create	allowCreate
append-to	appendTo
dropdown-min-width	dropdownMinWidth
dropdown-max-width	dropdownMaxWidth

其余布尔型 / 短单词 props（disabled、clearable、searchable、multiple、remote、loading、teleported）以及单单词 props（options、placeholder、size、offset、placement）在模板与 TS 层写法一致，无需转换。

Events 映射

模板写法（kebab-case）	源码 emit 写法（camelCase）
update:model-value	update:modelValue
visible-change	visibleChange
search-change	searchChange

其余事件（change、clear、focus、blur）为单单词，模板与源码写法一致。

fit-input-width 与 fit-trigger-width 的关系

• 推荐使用 fit-input-width：控制下拉面板是否跟随触发器宽度。
• fit-trigger-width 是兼容别名，仅当 fit-input-width 未显式传入时才生效（即 fitInputWidth ?? fitTriggerWidth）。
• 两者功能相同，fit-input-width 优先级更高；新代码建议只写 fit-input-width，不需要同时传两个。

API

Select Attributes

属性	说明	类型	默认值
model-value	当前选中值	SelectValue<T>	null
options	选项列表	SelectOptionItem<T>[]	—
placeholder	未选择时的占位提示	string	'请选择'
disabled	是否禁用	boolean	false
clearable	是否允许清空当前选中值	boolean	false
searchable	是否启用搜索输入	boolean	false
multiple	是否开启多选	boolean	false
collapse-tags	多选时是否折叠标签	boolean	false
max-tag-count	折叠前最多展示的标签数	number	undefined
remote	是否启用远程搜索	boolean	false
allow-create	是否允许按搜索词创建新项	boolean	false
size	组件尺寸	ComponentSize	跟随全局配置
no-data-text	无选项时的文案	string	'暂无选项'
no-match-text	搜索无结果时的文案	string	'没有匹配项'
loading	是否处于加载态	boolean	false
loading-text	加载态文案	string	'加载中'
search-placeholder	搜索输入占位文案	string	'搜索选项'
create-text	创建项前缀文案	string	'创建'
prefix-icon	触发器前置图标	string	''
suffix-icon	触发器后置图标	string	'mdi:chevron-down'
clear-icon	清空图标	string	'mdi:close-circle'
teleported	是否把下拉面板传送到 body	boolean	true
append-to	下拉面板挂载目标	string | HTMLElement	'body'
placement	下拉面板弹出位置	Placement	'bottom-start'
offset	下拉面板偏移量	number	12
popper-class	下拉面板自定义类名	string	''
popper-style	下拉面板自定义样式	StyleValue	''
fit-trigger-width	兼容别名；当未显式传 fit-input-width 时，用它控制下拉面板是否跟随触发器宽度，不作为新的主推荐写法	boolean	true
fit-input-width	是否让下拉面板跟随触发器宽度	boolean	undefined（未传时回退 fit-trigger-width）
dropdown-min-width	下拉面板最小宽度	string | number	—
dropdown-max-width	下拉面板最大宽度	string | number	—

Select Events

事件	说明	参数
update:model-value	选中值变化时触发	SelectValueChangeHandler<T>
change	选中值确认变化时触发	SelectValueChangeHandler<T>
clear	点击清空按钮时触发	—
visible-change	下拉打开或关闭时触发	SelectVisibleChangeHandler
focus	下拉打开时触发	—
blur	下拉关闭时触发	—
search-change	搜索关键字变化时触发	SelectSearchChangeHandler

模板层监听事件使用 visible-change、search-change；源码 emit 和 TS 类型层对应的是 visibleChange、searchChange。

Select Option

选项类型为 SelectOption<T>。

Select Option Group

分组选项类型为 SelectOptionGroup<T>。

Select Slots

插槽	说明
prefix	触发器前缀内容
suffix	自定义触发器后缀图标
header	下拉面板头部内容
footer	下拉面板底部内容
loading	自定义加载态内容
empty	自定义空态内容
option	自定义选项内容，接收 SelectOptionSlotProps<T>

Select Exposes

暴露项	说明	类型
focus	聚焦触发器	SelectInstance["focus"]
blur	关闭并让触发器失焦	SelectInstance["blur"]
open	打开下拉面板	SelectInstance["open"]
close	关闭下拉面板	SelectInstance["close"]