更新记录

1.0.2（2026-08-03） 下载此版本

修改文档

1.0.1（2026-08-03） 下载此版本

优化截图和文档

1.0.0（2026-08-03） 下载此版本

• 首次发布。
• 支持多列滚动吸附选择。
• 支持 show.sync、confirm、cancel、columnchange 事件。
• 内置默认背景图资源 static/picker-bg.png。
• 支持 backgroundImage、backgroundColor、useDefaultBackground 背景配置。
• 新增 background 配置，支持纯色和渐变背景。

平台兼容性

uni-app(4.07)

custom-picker

custom-picker 是一个适用于 uni-app 的自定义多列滚动选择器组件，支持滚动吸附、选中项缩放、遮罩关闭、show.sync 双向控制。

特性

• 支持单列、多列选择
• 支持 show.sync 控制显示隐藏
• 支持 confirm、cancel、columnchange 事件
• 内置默认背景图，支持自定义背景图和纯色背景
• 纯前端实现，无第三方依赖
• 兼容 vue2 / vue3

目录结构

uni_modules/custom-picker/
├─ components/custom-picker/custom-picker.vue
├─ pages/demo/demo.vue
├─ screenshots/demo-default.png
├─ screenshots/demo-gradient.png
├─ screenshots/demo-columns.png
├─ static/picker-bg.png
├─ changelog.md
├─ package.json
└─ readme.md

安装方式

下载插件后，放入项目 uni_modules 目录。

使用方式

组件安装后可通过 easycom 直接使用：

<template>
  <custom-picker
    :show="visible"
    @update:show="visible = $event"
    title="出生日期"
    :columns="columns"
    :value="value"
    background-color="#ffffff"
    @confirm="onConfirm"
    @cancel="onCancel"
    @columnchange="onColumnChange"
  />
</template>

<script>
export default {
  data() {
    return {
      visible: false,
      columns: [
        ['北京', '上海', '广州'],
        ['朝阳', '浦东', '天河']
      ],
      value: [0, 0]
    }
  },
  methods: {
    onConfirm(e) {
      console.log('选中结果', e)
    },
    onCancel() {
      console.log('取消选择')
    },
    onColumnChange(e) {
      console.log('列变化', e)
    }
  }
}
</script>

Props

Events

confirm 返回值示例

{
  value: ['1995年', '1月', '1日'],
  index: [25, 0, 0]
}

注意事项

• columns 需要传二维数组。
• value 需要传索引数组，长度建议与 columns 列数一致。
• 如果用于联动选择，建议在 columnchange 中按需更新后续列数据。
• 建议统一使用 :show="visible" 和 @update:show="visible = $event"，不要依赖 .sync。
• 若要纯背景色或渐变背景，请设置 :use-default-background="false" 并传入 background。
• 若要自定义背景图，请传入宿主项目可访问的图片路径到 backgroundImage。

背景样式示例

使用内置背景图：

<custom-picker
  :show="visible"
  @update:show="visible = $event"
  title="默认背景"
  :columns="columns"
  :value="value"
/>

使用自定义背景图：

<custom-picker
  :show="visible"
  @update:show="visible = $event"
  title="自定义背景图"
  :columns="columns"
  :value="value"
  background-image="/static/my-picker-bg.png"
/>

使用纯色背景：

<custom-picker
  :show="visible"
  @update:show="visible = $event"
  title="纯色背景"
  :columns="columns"
  :value="value"
  :use-default-background="false"
  background="#f3e8ff"
 />

使用渐变背景：

<custom-picker
  :show="visible"
  @update:show="visible = $event"
  title="渐变背景"
  :columns="columns"
  :value="value"
  :use-default-background="false"
  background="linear-gradient(180deg, #f3e8ff 0%, #ffffff 100%)"
  />

演示页

示例页面位于 uni_modules/custom-picker/pages/demo/demo.vue。