Select 下拉选择框

下拉选择框组件，用于从选项列表中选择一项。支持多种数据格式：对象数组、字符串数组、数字数组。可选配搜索过滤功能。

何时使用：需要用户从预定义选项列表中选择时使用。选项少于 3 个时可考虑 Radio。

基础用法（对象数组）

自定义字段名

如果数据字段不是 label/value，可通过 label-key 和 value-key 指定。

字符串数组

数字数组

占位文本

设置 placeholder 属性，会显示一个不可选中的默认选项。

可搜索

设置 filterable 属性，下拉框支持输入过滤。选项较多时非常实用。

搜索模式下的键盘操作

按键	操作
↓	向下移动高亮
↑	向上移动高亮
Home	跳到第一条
End	跳到最后一条
Enter	选中当前高亮项
Esc	关闭下拉面板

无障碍：下拉面板通过 Teleport 挂载到 body（position: fixed，坐标由组件计算），即使在 overflow: hidden 的容器内也能完整显示；键盘高亮通过 aria-activedescendant 同步到输入框，配合屏幕阅读器阅读当前选项。

远程搜索

结合 @search 事件实现远程搜索：

自定义选项渲染

通过 #option 插槽自定义每个选项的显示内容。

自定义空状态

搜索无结果时，可通过 #empty 插槽自定义提示内容。

下拉面板高度

通过 max-height 属性控制下拉面板的最大高度（单位：px），超出后自动滚动。

多选

设置 multiple 属性启用多选（需与 filterable 配合）。已选项以标签形式展示，可点击移除。选择后下拉保持打开，方便连续多选。

注意：多选模式要求 modelValue 为数组（v-model 绑定 ref([])），且仅支持 filterable 可搜索模式。

多选模式说明

• 标签展示：已选项以 chip 标签形式显示在输入框内，点击 × 可单独移除
• 键盘操作：Enter 选中后保持下拉打开（方便连续多选），Esc 关闭
• 连续多选：点击选项后输入框搜索文本自动清空，无需手动删除
• change 事件：多选时始终返回数组（即使只有一个值）

尺寸

禁用状态

错误状态

error 属性仅控制选择框边框颜色，不渲染错误消息。

禁用选项

在选项中设置 disabled: true 可禁用特定选项。

API

Props

属性	类型	默认值	说明
modelValue	string | number | (string | number)[]	'' / []	选中的值（v-model），多选时为数组
options	any[]	[]	选项列表，支持对象数组、字符串数组、数字数组
labelKey	string	'label'	对象数组中作为显示文本的字段名
valueKey	string	'value'	对象数组中作为选项值的字段名
placeholder	string	''	占位文本（显示为不可选中的默认选项）
size	'sm' | 'md' | 'lg'	'md'	尺寸
disabled	boolean	false	是否禁用
error	boolean	false	是否显示错误状态（仅边框样式）
filterable	boolean	false	是否可搜索（启用后替换为自定义下拉框）
multiple	boolean	false	是否多选（需与 filterable 配合，v-model 为数组）
emptyText	string	'暂无数据'	搜索无结果时的空状态文案
maxHeight	number	240	下拉面板最大高度（单位：px）

Events

事件	参数	说明
update:modelValue	(value: string | number | array)	值变化时触发（v-model），多选时为数组
change	(value: string | number | array)	值变化时触发（多选时始终返回数组）
search	(value: string)	搜索输入时触发（仅在 filterable 模式下可用）

Slots

名称	参数	说明
option	{ item, label }	自定义选项渲染内容
empty	—	自定义搜索无结果时的空状态内容

类型支持

options 支持以下三种数据格式：

格式	示例	显示值	选中值
对象数组	[{ label: '技术', value: 'tech' }]	label 字段	value 字段
字符串数组	['红', '绿', '蓝']	元素本身	元素本身
数字数组	[1, 2, 3]	元素本身	元素本身

对象数组可通过 label-key / value-key 自定义字段名。在 Vue SFC 中 TypeScript 会根据 :options 传入的数据自动推断类型，无需手动标注。

注意事项

• Select 默认使用原生 <select> 元素，极致轻量，支持键盘导航
• 设置 filterable 后会替换为自定义下拉框，支持搜索过滤和键盘导航
• 自定义下拉框支持 ↓ ↑ 键切换选项，Enter 键确认，Esc 键关闭
• 下拉箭头为内联 SVG，颜色自动继承文字颜色（currentColor）
• placeholder 选项会自动设置为 disabled 和 hidden，不会被选中
• error 属性仅控制边框颜色，不渲染错误消息
• 聚焦时显示主题色边框和聚焦环
• 对象数组默认使用 label/value 字段，可通过 label-key/value-key 自定义
• 基本类型（字符串、数字）数组自动处理：显示值和选中值均为该值本身
• 通过 max-height 可控制下拉面板最大高度，超出后自动滚动
• 多选模式需同时设置 multiple + filterable，v-model 绑定数组
• 多选模式下 Enter 选中后保持下拉打开，方便连续多选；Esc 关闭
• 多选模式下 change 事件始终返回数组（即使只有一个元素）