Select 选择框

基于element-plus select组件的二次封装。简化遍历操作。

基础用法

选项组

禁用

对象值

属性

属性名	说明	类型	是否拓展	默认值
v-model	选中项绑定值	enum stringnumberbooleanobjectarray	否	-
options	选项列表	SelectOption[]	是	[]
clearable	是否可以清空选项	boolean	否	false
multiple	是否多选	boolean	否	false
disabled	是否禁用	boolean	否	false
value-key	作为 value 唯一标识的键名，绑定值为对象类型时必填	string	否	value
size	输入框尺寸	enum ''largedefaultsmall	否	—
collapse-tags	多选时是否将选中值按文字的形式展示	boolean	否	false
collapse-tags-tooltip	当鼠标悬停于折叠标签的文本时，是否显示所有选中的标签。 要使用此属性，collapse-tags属性必须设定为 true	boolean	否	false
multiple-limit	multiple 属性设置为 true 时，代表多选场景下用户最多可以选择的项目数， 为 0 则不限制	number	否	0
name	原生 name 属性	string	否	—
effect	tooltip 主题	enum darklight	否	light
autocomplete	原生 autocomplete 属性	string	否	off
placeholder	占位符	string	否	—
filterable	是否可筛选	boolean	否	false
allow-create	是否允许用户创建新条目，只有当 filterable 设置为 true 时才会生效。	boolean	否	false
filter-method	自定义筛选方法	Function	否	—
remote	其中的选项是否从服务器远程加载	boolean	否	false
remote-method	自定义远程搜索方法	Function	否	—
remote-show-suffix	远程搜索方法显示后缀图标	boolean	否	false
loading	是否正在从远程获取数据	boolean	否	false
loading-text	从服务器加载数据时显示的文本	string	否	-
no-match-text	搜索条件无匹配时显示的文字	string	否	-
no-data-text	无选项时显示的文字	string	否	-
popper-class	选择器下拉菜单的自定义类名	string	否	''
reserve-keyword	当 multiple 和 filterable被设置为 true 时，是否在选中一个选项后保留当前的搜索关键词	boolean	否	true
default-first-option	是否在输入框按下回车时，选择第一个匹配项。需配合 filterable 或 remote 使用	boolean	否	false
teleported	是否将下拉列表插入至 body 元素	boolean	否	true
persistent	当下拉选择器未被激活并且persistent设置为false，选择器会被删除。	boolean	否	true
automatic-dropdown	对于不可搜索的 Select，是否在输入框获得焦点后自动弹出选项菜单	boolean	否	false
clear-icon	自定义清除图标	enum stringobject	否	CircleClose
fit-input-width	下拉框的宽度是否与输入框相同	boolean	否	false
suffix-icon	自定义后缀图标组件	enum stringobject	否	ArrowDown
suffix-transition deprecated	下拉菜单显示/消失时后缀图标的动画	boolean	否	true
tag-type	标签类型	enum ''successinfowarningdanger	否	info
tag-effect el^2.7.7	标签效果	enum ''lightdarkplain	否	light
validate-event	是否触发表单验证	boolean	否	true
placement	下拉框出现的位置	enum toptop-starttop-endbottombottom-startbottom-endleftleft-startleft-endrightright-startright-end	否	bottom-start
max-collapse-tags	需要显示的 Tag 的最大数量 只有当 collapse-tags 设置为 true 时才会生效。	number	否	1
popper-options	popper.js 参数	object	否	-
aria-label	等价于原生 input aria-label 属性	string	否	-
empty-values el^2.7.0	组件的空值配置 参考config-provider	array	否	-
value-on-clear el^2.7.0	清空选项的值 参考 config-provider	enum stringnumberbooleanFunction	否	-

SelectOption

属性名	说明	类型	是否必须	默认值
label	选项名称	string	是	-
value	选项值	enum stringnumberbooleanobject	是	-
disabled	是否禁用	boolean	否	false
options	选项组列表	BaseOption[]	否	-

事件

本组件支持 Element Plus Select 的所有原生事件，所有事件会自动透传到底层的 el-select 组件。

常用事件示例：

事件名	说明	类型
change	选中值发生变化时触发	Function (value) => void
visible-change	下拉框出现/隐藏时触发	Function (visible) => void
remove-tag	多选模式下移除tag时触发	Function (value) => void
clear	可清空的单选模式下用户点击清空按钮时触发	Function () => void
blur	当 input 失去焦点时触发	Function (event) => void
focus	当 input 获得焦点时触发	Function (event) => void

💡 多版本兼容：支持 Element Plus 2.x 所有版本，包括未来新增的事件也会自动可用。

💡 组件默认行为：EzSelect 默认行为与底层 el-select 保持一致，未写死 clearable；如需清空能力，请显式传入 clearable。

💡 对象值建议：当 v-model 绑定对象值时，请始终配置 value-key（例如 id）。这能避免选项回显不稳定，也更符合 Element Plus 的对象值比较约定。