更新记录

0.0.1（2025-07-10） 下载此版本

init

平台兼容性

uni-app(4.06)

uni-app x(4.06)

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

Events

confirm/change 事件返回值格式

单选模式：

{
  selectedItem: {...},      // 选中的完整数据项
  selectedValue: 'value',   // 选中项的值
  selectedIndex: 0          // 选中项在原数组中的索引
}

多选模式：

{
  selectedItems: [...],     // 选中的完整数据项数组
  selectedValues: [...]     // 选中项的值数组
}

Methods

组件暴露的方法（通过 ref 调用）：

使用示例

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

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