更新记录

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
  }
}

注意事项

  1. 数据格式一致性:确保 options 数组中的数据格式保持一致
  2. 性能优化:当选项数据量较大时,建议启用搜索功能以提升用户体验
  3. 兼容性:组件基于 uni-app 框架,支持多端运行
  4. 样式隔离:组件使用 scoped 样式,不会影响全局样式

更新日志

v1.0.0

  • 初始版本发布
  • 支持单选/多选模式
  • 支持搜索过滤功能
  • 支持自定义数据格式
  • 支持自定义过滤函数

隐私、权限声明

1. 本插件需要申请的系统权限列表:

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集任何数据

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

许可协议

MIT协议

暂无用户评论。

使用中有什么不明白的地方,就向插件作者提问吧~ 我要提问