Select 选择器
WebH5
下拉选择器。支持单选与多选(multiple,标签展示已选项)、清空、禁用选项、键盘上下键导航与 Enter 选中/切换、Escape 收起。
何时使用
选项较多、需要节省空间的单选场景,如表单字段、筛选条件。
何时不使用
选项少于 5 个且需要一眼看全时,用 Radio 平铺更合适。
Props
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
modelValue | string | number | (string | number)[] | null | null | 绑定值,配合 v-model 使用;multiple 时为 (string | number)[] |
options | Array<{label,value,disabled?}> | [] | 选项列表,项为 { label: string; value: string | number; disabled?: boolean } |
placeholder | string | "请选择(取 locale 文案 select.placeholder)" | 未选中时的占位文本;默认走 locale,显式传入时优先 |
size | string:'sm' | 'md' | 'lg' | "md" | 尺寸;移动端建议 md 或 lg(触摸目标 ≥ 36px) |
disabled | boolean | false | 禁用 |
clearable | boolean | false | 可清空;有值时 hover 触发器显示清空按钮,多选时清空整个数组 |
multiple | boolean | false | 多选模式;触发器内以标签展示已选项,点选项切换选中且面板保持展开 |
collapseTags | boolean | false | 多选时折叠标签:只显示首个标签与 +N 计数标签 |
max | number | null | 多选最多可选数量,达到后未选中选项呈禁用态 |
filterable | boolean | false | 可过滤:下拉顶部渲染搜索框,输入后本地按 label 包含匹配过滤(忽略大小写) |
remote | boolean | false | 远程搜索:需配合 remoteMethod,输入防抖后调用;打开面板时搜索框自动聚焦,空关键词展示 options 兜底 |
remoteMethod | (keyword: string) => Promise<SelectOption[]> | SelectOption[] | void | - | 远程搜索方法:入参为输入关键词,返回 Promise<SelectOption[]> 或同步数组;返回 void 时自行通过 loading 控制。结果与 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 | 下拉显隐变化时触发(远程搜索常用于打开时加载) |
示例
基础选择
示例加载中…
可搜索:输入过滤,↑↓ 选择
示例加载中…
可清空与禁用选项
示例加载中…
三种尺寸
示例加载中…
禁用态
示例加载中…
事件监听
示例加载中…
大量选项(内置滚动)
示例加载中…
表单中的联动
示例加载中…
多选(标签展示)
示例加载中…
多选:折叠标签与数量上限
示例加载中…
业务场景:订单筛选
示例加载中…
Playground
加载中…
md
跨端版本
该组件同时提供 uni-app / uni-app X 实现(H5 / 微信小程序 / App),API 可能略有差异,见 uni-app 端 Select 文档(含手机预览)。