Select 选择框
uni-appH5微信小程序App
跨端下拉选择器:自绘触发器 + 选项面板(遮罩定位),支持单选/多选、标签折叠、数量上限、本地过滤与远程搜索,API 与 Web 端 Select 对齐。
何时使用
选项较多、需要节省空间的单选/多选场景,如表单字段、筛选条件。
何时不使用
选项少于 5 个且需要一眼看全时,用 Radio 平铺更合适。
本文档为 uni-app 端组件契约;Web 端同名组件 API 可能略有差异,请以对应包文档为准。下方手机预览实时运行 uni-app H5 演示。
Props
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
modelValue | string | number | (string | number)[] | null | null | 绑定值,配合 v-model 使用;multiple 时为 (string | number)[] |
options | SelectOption[] | [] | 选项列表,项为 { label: string; value: string | number; disabled?: boolean };remote 模式下为初始/兜底选项 |
label | string | "" | 表单标签,渲染在触发器上方(uni-app 端独有) |
placeholder | string | "请选择" | 未选中时的占位文本;默认走语言包,显式传入时优先 |
size | string:'sm' | 'md' | 'lg' | "md" | 尺寸;移动端建议 md 或 lg(触摸目标 ≥ 36px) |
disabled | boolean | false | 禁用 |
clearable | boolean | false | 可清空;有值时触发器显示清空按钮,多选时清空整个数组 |
multiple | boolean | false | 多选模式;触发器内以标签展示已选项,点选项切换选中且面板保持展开 |
collapseTags | boolean | false | 多选时折叠标签:只显示首个标签与 +N 计数标签 |
max | number | "undefined" | 多选最多可选数量,达到后未选中选项呈禁用态 |
filterable | boolean | false | 可过滤:面板顶部渲染搜索框,输入后本地按 label 包含匹配过滤(忽略大小写) |
remote | boolean | false | 远程搜索:需配合 remoteMethod,输入防抖后调用;空关键词展示 options 兜底 |
remoteMethod | (keyword: string) => Promise<SelectOption[]> | SelectOption[] | void | - | 远程搜索方法:入参为输入关键词,返回 Promise<SelectOption[]> 或同步数组;结果与 options 按 value 去重合并 |
filterMethod | (keyword: string, option: SelectOption) => boolean | - | 自定义过滤函数(filterable 本地模式):返回 true 保留该选项;缺省按 label 包含匹配 |
loading | boolean | false | 外部受控加载态(remote 手动模式),与内部远程加载态取或 |
debounce | number | 300 | 远程搜索防抖毫秒数,默认 300 |
Events
| 名称 | 载荷 | 说明 |
|---|---|---|
update:modelValue | string | number | (string | number)[] | null | 选中、切换或清空时触发,用于 v-model;multiple 时载荷为数组 |
change | string | number | (string | number)[] | null | 值变化时触发(选中、切换或清空);multiple 时载荷为数组 |
clear | void | 点击清空按钮时触发 |
visible-change | boolean | 下拉显隐变化时触发(远程搜索常用于打开时加载) |
示例
基础用法
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 />