跳到主要内容

Select 选择器 ​

WebH5

下拉选择器。支持单选与多选(multiple,标签展示已选项)、清空、禁用选项、键盘上下键导航与 Enter 选中/切换、Escape 收起。

何时使用 ​

选项较多、需要节省空间的单选场景,如表单字段、筛选条件。

何时不使用 ​

选项少于 5 个且需要一眼看全时,用 Radio 平铺更合适。

Props ​

名称类型默认值说明
modelValuestring | number | (string | number)[] | nullnull绑定值,配合 v-model 使用;multiple 时为 (string | number)[]
optionsArray<{label,value,disabled?}>[]选项列表,项为 { label: string; value: string | number; disabled?: boolean }
placeholderstring"请选择(取 locale 文案 select.placeholder)"未选中时的占位文本;默认走 locale,显式传入时优先
sizestring:'sm' | 'md' | 'lg'"md"尺寸;移动端建议 md 或 lg(触摸目标 ≥ 36px)
disabledbooleanfalse禁用
clearablebooleanfalse可清空;有值时 hover 触发器显示清空按钮,多选时清空整个数组
multiplebooleanfalse多选模式;触发器内以标签展示已选项,点选项切换选中且面板保持展开
collapseTagsbooleanfalse多选时折叠标签:只显示首个标签与 +N 计数标签
maxnumbernull多选最多可选数量,达到后未选中选项呈禁用态
filterablebooleanfalse可过滤:下拉顶部渲染搜索框,输入后本地按 label 包含匹配过滤(忽略大小写)
remotebooleanfalse远程搜索:需配合 remoteMethod,输入防抖后调用;打开面板时搜索框自动聚焦,空关键词展示 options 兜底
remoteMethod(keyword: string) => Promise<SelectOption[]> | SelectOption[] | void-远程搜索方法:入参为输入关键词,返回 Promise<SelectOption[]> 或同步数组;返回 void 时自行通过 loading 控制。结果与 options 按 value 去重合并
filterMethod(keyword: string, option: SelectOption) => boolean-自定义过滤函数(filterable 本地模式):返回 true 保留该选项;缺省按 label 包含匹配
loadingbooleanfalse外部受控加载态(remote 手动模式),与内部远程加载态取或;加载中搜索框内显示旋转小圆点
debouncenumber300远程搜索防抖毫秒数,默认 300

Events ​

名称载荷说明
update:modelValuestring | number | (string | number)[] | null选中、切换或清空时触发,用于 v-model;multiple 时载荷为数组
changestring | number | (string | number)[] | null值变化时触发(选中、切换或清空);multiple 时载荷为数组
clearvoid点击清空按钮时触发
visible-changeboolean下拉显隐变化时触发(远程搜索常用于打开时加载)

示例 ​

基础选择 ​

示例加载中…

可搜索:输入过滤,↑↓ 选择 ​

示例加载中…

可清空与禁用选项 ​

示例加载中…

三种尺寸 ​

示例加载中…

禁用态 ​

示例加载中…

事件监听 ​

示例加载中…

大量选项(内置滚动) ​

示例加载中…

表单中的联动 ​

示例加载中…

多选(标签展示) ​

示例加载中…

多选:折叠标签与数量上限 ​

示例加载中…

业务场景:订单筛选 ​

示例加载中…

Playground ​

加载中…

跨端版本 ​

该组件同时提供 uni-app / uni-app X 实现(H5 / 微信小程序 / App),API 可能略有差异,见 uni-app 端 Select 文档(含手机预览)。