跳到主要内容

Select 选择框 ​

uni-appH5微信小程序App

跨端下拉选择器:自绘触发器 + 选项面板(遮罩定位),支持单选/多选、标签折叠、数量上限、本地过滤与远程搜索,API 与 Web 端 Select 对齐。

何时使用 ​

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

何时不使用 ​

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

本文档为 uni-app 端组件契约;Web 端同名组件 API 可能略有差异,请以对应包文档为准。下方手机预览实时运行 uni-app H5 演示。

9:41
Select 选择框 · uni-app H5 实时运行 新窗口打开

Props ​

名称类型默认值说明
modelValuestring | number | (string | number)[] | nullnull绑定值,配合 v-model 使用;multiple 时为 (string | number)[]
optionsSelectOption[][]选项列表,项为 { label: string; value: string | number; disabled?: boolean };remote 模式下为初始/兜底选项
labelstring""表单标签,渲染在触发器上方(uni-app 端独有)
placeholderstring"请选择"未选中时的占位文本;默认走语言包,显式传入时优先
sizestring:'sm' | 'md' | 'lg'"md"尺寸;移动端建议 md 或 lg(触摸目标 ≥ 36px)
disabledbooleanfalse禁用
clearablebooleanfalse可清空;有值时触发器显示清空按钮,多选时清空整个数组
multiplebooleanfalse多选模式;触发器内以标签展示已选项,点选项切换选中且面板保持展开
collapseTagsbooleanfalse多选时折叠标签:只显示首个标签与 +N 计数标签
maxnumber"undefined"多选最多可选数量,达到后未选中选项呈禁用态
filterablebooleanfalse可过滤:面板顶部渲染搜索框,输入后本地按 label 包含匹配过滤(忽略大小写)
remotebooleanfalse远程搜索:需配合 remoteMethod,输入防抖后调用;空关键词展示 options 兜底
remoteMethod(keyword: string) => Promise<SelectOption[]> | SelectOption[] | void-远程搜索方法:入参为输入关键词,返回 Promise<SelectOption[]> 或同步数组;结果与 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下拉显隐变化时触发(远程搜索常用于打开时加载)

示例 ​

基础用法 ​

vue
<Select v-model="sel1" :options="options" label="部门" />

可清空 ​

vue
<Select v-model="sel2" :options="options" label="优先级" clearable />

多选 ​

vue
<Select v-model="sel3" :options="options" label="标签" multiple />

多选折叠标签与上限 ​

vue
<Select v-model="sel4" :options="options" label="最多两项" multiple collapse-tags :max="2" />

搜索过滤 ​

vue
<Select v-model="sel1" :options="options" label="可搜索" filterable />

大尺寸 ​

vue
<Select v-model="sel2" :options="options" label="大尺寸" size="lg" />

禁用 ​

vue
<Select v-model="sel1" :options="options" label="禁用" disabled />