更新记录
0.0.1(2025-07-10) 下载此版本
init
平台兼容性
uni-app(4.06)
Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 |
---|---|---|---|---|---|---|---|---|
- | - | - | - | - | - | - | - | - |
微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 快应用-华为 | 快应用-联盟 |
---|---|---|---|---|---|---|---|---|---|---|
- | - | - | - | - | - | - | - | - | - | - |
uni-app x(4.06)
Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
---|---|---|---|---|---|
- | - | - | - | - | - |
CustomPicker 自定义选择器组件
概述
CustomPicker 是一个功能强大、灵活易用的自定义选择器组件,专为 uni-app 框架设计。组件支持单选、多选、搜索过滤、自定义数据格式等多种功能,提供优秀的用户体验。
特性
- ✅ 单选/多选支持 - 支持单选和多选两种模式
- ✅ 搜索过滤 - 内置搜索功能,支持关键词高亮显示
- ✅ 自定义过滤 - 支持自定义过滤函数
- ✅ 灵活数据格式 - 支持字符串、对象等多种数据格式
- ✅ 响应式设计 - 适配不同屏幕尺寸
- ✅ 动画效果 - 流畅的进入退出动画
- ✅ 易于定制 - 支持样式定制和主题修改
安装使用
1. 导入组件
将 customPicker.vue
文件放置到项目的 components
目录下。
2. 注册组件
<script>
import CustomPicker from '@/components/customPicker.vue'
export default {
components: {
CustomPicker
}
}
</script>
3. 基础使用
<template>
<view>
<button @tap="showPicker">选择城市</button>
<CustomPicker
:visible="pickerVisible"
:options="cityOptions"
title="选择城市"
@confirm="handleConfirm"
@cancel="handleCancel"
@update:visible="pickerVisible = $event"
/>
</view>
</template>
<script>
export default {
data() {
return {
pickerVisible: false,
cityOptions: [
{ label: '北京', value: 'beijing' },
{ label: '上海', value: 'shanghai' },
{ label: '深圳', value: 'shenzhen' },
{ label: '广州', value: 'guangzhou' }
]
}
},
methods: {
showPicker() {
this.pickerVisible = true
},
handleConfirm(result) {
console.log('选择结果:', result)
// 单选结果格式: { selectedItem: {...}, selectedValue: 'value', selectedIndex: 0 }
},
handleCancel() {
console.log('取消选择')
}
}
}
</script>
API 文档
Props
属性名 | 类型 | 默认值 | 必填 | 说明 |
---|---|---|---|---|
visible | Boolean | false | 是 | 是否显示选择器 |
title | String | '请选择' | 否 | 选择器标题 |
options | Array | [] | 是 | 选项数据数组 |
displayKey | String | 'label' | 否 | 显示字段名(对象格式数据时使用) |
valueKey | String | 'value' | 否 | 值字段名(对象格式数据时使用) |
value | String/Number/Object | '' | 否 | 当前选中值 |
searchable | Boolean | true | 否 | 是否显示搜索框 |
multiple | Boolean | false | 否 | 是否启用多选模式 |
filterMethod | Function | null | 否 | 自定义过滤函数 |
Events
事件名 | 参数 | 说明 |
---|---|---|
confirm | result | 确认选择时触发 |
cancel | - | 取消选择时触发 |
change | result | 选择改变时触发(同confirm) |
update:visible | Boolean | 显示状态改变时触发(支持v-model) |
confirm/change 事件返回值格式
单选模式:
{
selectedItem: {...}, // 选中的完整数据项
selectedValue: 'value', // 选中项的值
selectedIndex: 0 // 选中项在原数组中的索引
}
多选模式:
{
selectedItems: [...], // 选中的完整数据项数组
selectedValues: [...] // 选中项的值数组
}
Methods
组件暴露的方法(通过 ref 调用):
方法名 | 参数 | 说明 |
---|---|---|
hide | - | 隐藏选择器 |
使用示例
1. 字符串数组数据
<template>
<CustomPicker
:visible="visible"
:options="stringOptions"
title="选择水果"
@confirm="handleConfirm"
/>
</template>
<script>
export default {
data() {
return {
stringOptions: ['苹果', '香蕉', '橙子', '葡萄', '西瓜']
}
}
}
</script>
2. 多选模式
<template>
<CustomPicker
:visible="visible"
:options="options"
:multiple="true"
title="选择标签"
@confirm="handleMultiConfirm"
/>
</template>
<script>
export default {
methods: {
handleMultiConfirm(result) {
console.log('选中的项目:', result.selectedItems)
console.log('选中的值:', result.selectedValues)
}
}
}
</script>
3. 自定义数据字段
<template>
<CustomPicker
:visible="visible"
:options="customOptions"
displayKey="name"
valueKey="id"
title="选择用户"
@confirm="handleConfirm"
/>
</template>
<script>
export default {
data() {
return {
customOptions: [
{ id: 1, name: '张三', age: 25 },
{ id: 2, name: '李四', age: 30 },
{ id: 3, name: '王五', age: 28 }
]
}
}
}
</script>
4. 自定义过滤函数
<template>
<CustomPicker
:visible="visible"
:options="options"
:filterMethod="customFilter"
title="搜索用户"
@confirm="handleConfirm"
/>
</template>
<script>
export default {
data() {
return {
options: [
{ name: '张三丰', department: '技术部', phone: '***' },
{ name: '李小龙', department: '销售部', phone: '***' },
{ name: '王小明', department: '技术部', phone: '***' }
]
}
},
methods: {
// 自定义过滤:支持按姓名、部门、手机号搜索
customFilter(keyword, item) {
const searchText = keyword.toLowerCase()
return item.name.toLowerCase().includes(searchText) ||
item.department.toLowerCase().includes(searchText) ||
item.phone.includes(searchText)
}
}
}
</script>
5. 禁用搜索功能
<template>
<CustomPicker
:visible="visible"
:options="options"
:searchable="false"
title="选择等级"
@confirm="handleConfirm"
/>
</template>
6. 使用 v-model 控制显示
<template>
<view>
<button @tap="visible = true">显示选择器</button>
<CustomPicker
v-model:visible="visible"
:options="options"
@confirm="handleConfirm"
/>
</view>
</template>
<script>
export default {
data() {
return {
visible: false
}
}
}
</script>
样式定制
主要 CSS 类
组件提供了丰富的 CSS 类供样式定制:
// 遮罩层
.custom-picker-overlay {
background-color: rgba(0, 0, 0, 0.5);
}
// 主容器
.custom-picker-container {
background-color: #fff;
border-radius: 24rpx 24rpx 0 0;
}
// 头部区域
.picker-header {
.picker-cancel { color: #999; }
.picker-title { color: #333; font-weight: 600; }
.picker-confirm { color: #12b792; font-weight: 600; }
}
// 搜索框
.search-box {
background-color: #f8f8f8;
border-radius: 24rpx;
}
// 选项列表
.option-item {
&.selected {
.option-text { color: #12b792; }
.option-check { color: #12b792; }
}
}
// 搜索高亮
.highlight {
background-color: #fff2e8;
color: #ff6b35;
font-weight: 600;
}
定制主题色
创建自定义样式文件:
// custom-picker-theme.scss
.custom-picker-container {
.picker-header {
.picker-confirm {
color: #007aff; // 自定义确认按钮颜色
}
}
.option-item.selected {
.option-content {
.option-text,
.option-check {
color: #007aff; // 自定义选中状态颜色
}
}
}
}
常见问题
Q: 如何设置默认选中值?
A: 通过 value
属性设置默认选中值:
<CustomPicker
:value="'shanghai'"
:options="cityOptions"
@confirm="handleConfirm"
/>
多选模式下传入数组:
<CustomPicker
:value="[city1, city2]"
:multiple="true"
:options="cityOptions"
@confirm="handleConfirm"
/>
Q: 如何监听选择器的显示/隐藏?
A: 监听 update:visible
事件:
<CustomPicker
:visible="visible"
@update:visible="onVisibleChange"
/>
<script>
export default {
methods: {
onVisibleChange(newVisible) {
console.log('选择器显示状态:', newVisible)
this.visible = newVisible
}
}
}
</script>
Q: 如何自定义无数据时的提示文字?
A: 目前组件内置了无数据提示,如需自定义可以修改组件源码中的相关文字,或通过 CSS 覆盖样式。
Q: 选择器的层级(z-index)是多少?
A: 组件使用 z-index: 9999
,如有层级冲突可以通过 CSS 调整:
.custom-picker-overlay {
z-index: 10000 !important;
}
Q: 如何实现异步加载选项数据?
A: 在显示选择器前异步加载数据:
async showPicker() {
this.loading = true
try {
this.options = await this.fetchOptions()
this.pickerVisible = true
} finally {
this.loading = false
}
}
注意事项
- 数据格式一致性:确保
options
数组中的数据格式保持一致 - 性能优化:当选项数据量较大时,建议启用搜索功能以提升用户体验
- 兼容性:组件基于 uni-app 框架,支持多端运行
- 样式隔离:组件使用
scoped
样式,不会影响全局样式
更新日志
v1.0.0
- 初始版本发布
- 支持单选/多选模式
- 支持搜索过滤功能
- 支持自定义数据格式
- 支持自定义过滤函数