更新记录

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

smart-picker​ 智能选择器组件正式发布！这是一个基于 uni-app 开发的现代化、功能丰富的选择器组件，为开发者提供强大而灵活的选择解决方案。

平台兼容性

uni-app(3.6.17)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
√ √ √ √ √ - √ - -
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
√ √ √ √ √ √ √ √ √ - √ √

smart-picker 智能选择器组件

基于 uni-app 的智能选择器组件，支持固定数据和API动态加载两种数据模式，提供单选和多选功能，包含搜索、分页、弹窗选择等完整功能。

特性

  • 🎯 多种模式：支持固定数据(fixed)和API动态加载(api)两种模式
  • 🔘 单选/多选：灵活支持单选和多选模式
  • 🔍 智能搜索：内置搜索功能，支持实时搜索
  • 📱 分页加载：API模式支持分页加载，大数据量无压力
  • 🎨 样式可定制：提供丰富的样式自定义选项
  • 📱 多端兼容：支持H5、小程序、App等多端
  • ⚡ 高性能：虚拟列表优化，大数据量流畅体验

安装

通过 uni_modules 安装

  1. 将组件文件夹 smart-picker 放入项目的 uni_modules 目录
  2. 无需手动引入，通过 Easycom 自动注册

目录结构

your-project/
├── uni_modules/
│   └── smart-picker/
│       ├── components/
│       │   └── smart-picker/
│       │       └── smart-picker.vue
│       └── package.json

快速开始

基本使用

<template>
    <view>
        <!-- 触发选择器 -->
        <view class="picker-trigger" @click="openPicker">
            <input 
                :value="selectedValue" 
                readonly
                placeholder="请选择"
                class="picker-input"
            />
            <view class="picker-icon">▼</view>
        </view>

        <!-- 智能选择器组件 -->
        <smart-picker 
            ref="smartPicker" 
            :options="options" 
            @selected="handleSelect" 
        />
    </view>
</template>

<script>
export default {
    data() {
        return {
            selectedValue: '',
            options: [
                { label: '北京', value: 1 },
                { label: '上海', value: 2 },
                { label: '广州', value: 3 },
                { label: '深圳', value: 4 }
            ]
        }
    },
    methods: {
        openPicker() {
            this.$refs.smartPicker.open()
        },
        handleSelect(item) {
            this.selectedValue = item.label
        }
    }
}
</script>

Props 属性

参数 类型 默认值 说明
type String 'fixed' 数据模式：fixed（固定数据）或 api（接口加载）
multiple Boolean false 是否多选模式
title String '' 选择器标题
paginate Object {} 分页配置，API模式必传
options Array [] 选项数据，type为'fixed'时必传
selected Array [] 默认选中的选项

paginate 配置

paginate: {
    loading: false,  // 加载状态
    limit: 10,       // 每页条数
    total: 0         // 总条数
}

options 数据结构

options: [
    { label: '显示文本', value: '唯一值' },
    { label: '选项1', value: 1 },
    { label: '选项2', value: 2 }
]

Events 事件

@request

  • 说明：API模式下的数据请求事件
  • 参数：
    • page：当前页码
    • keyword：搜索关键词

  • 示例：

    async handleRequest(page, keyword) {
// 调用接口获取数据
const res = await this.$http.get('/api/list', {
    params: { page, page_size: 10, keyword }
})

// 更新数据
this.pickerOptions = res.list
}

@selected

  • 说明：选择完成事件
  • 参数：
    • 单选：{ label, value }
    • 多选：[{ label, value }, ...]
  • 示例： 
    handleSelect(items) {
if (this.isMultiple) {
    // 多选结果处理
    console.log('多选结果:', items)
} else {
    // 单选结果处理
    console.log('单选结果:', items)
}
}

Methods 方法

通过 ref 调用组件方法：

// 打开选择器
this.$refs.smartPicker.open(clear = true)
// clear: 是否清空搜索关键词和页码，默认true

// 关闭选择器
this.$refs.smartPicker.close()

使用示例

示例1：固定数据单项选择

<template>
    <view>
        <view @click="openSinglePicker" class="picker-trigger">
            <input :value="singleValue" readonly placeholder="请选择城市" />
        </view>

        <smart-picker 
            ref="singlePicker" 
            title="选择城市" 
            :options="cityOptions" 
            @selected="handleSingleSelect" 
        />
    </view>
</template>

<script>
export default {
    data() {
        return {
            singleValue: '',
            cityOptions: [
                { label: '北京', value: 1 },
                { label: '上海', value: 2 },
                { label: '广州', value: 3 }
            ]
        }
    },
    methods: {
        openSinglePicker() {
            this.$refs.singlePicker.open()
        },
        handleSingleSelect(item) {
            this.singleValue = item.label
        }
    }
}
</script>

示例2：固定数据多项选择

<template>
    <view>
        <view @click="openMultiPicker" class="picker-trigger">
            <input :value="multiValue" readonly placeholder="请选择标签" />
        </view>

        <smart-picker 
            ref="multiPicker" 
            title="选择标签" 
            :multiple="true" 
            :options="tagOptions" 
            :selected="selectedTags" 
            @selected="handleMultiSelect" 
        />
    </view>
</template>

<script>
export default {
    data() {
        return {
            multiValue: '',
            selectedTags: [
                { label: '标签1', value: 1 }
            ],
            tagOptions: [
                { label: '标签1', value: 1 },
                { label: '标签2', value: 2 },
                { label: '标签3', value: 3 }
            ]
        }
    },
    methods: {
        openMultiPicker() {
            this.$refs.multiPicker.open()
        },
        handleMultiSelect(items) {
            this.multiValue = items.map(item => item.label).join(', ')
        }
    }
}
</script>

示例3：API动态加载数据

<template>
    <view>
        <view @click="openApiPicker" class="picker-trigger">
            <input :value="apiValue" readonly placeholder="请选择用户" />
        </view>

        <smart-picker 
            ref="apiPicker" 
            title="选择用户" 
            type="api" 
            :paginate="paginate" 
            @request="handleRequest" 
            @selected="handleApiSelect" 
        />
    </view>
</template>

<script>
export default {
    data() {
        return {
            apiValue: '',
            paginate: {
                loading: false,
                limit: 10,
                total: 0
            }
        }
    },
    methods: {
        openApiPicker() {
            this.$refs.apiPicker.open()
        },
        async handleRequest(page, keyword) {
            this.paginate.loading = true

            // 模拟API调用
            const res = await this.$http.get('/api/users', {
                params: { page, page_size: 10, keyword }
            })

            this.paginate = {
                loading: false,
                limit: 10,
                total: res.total
            }

            // 设置选项数据
            this.pickerOptions = res.data.map(user => ({
                label: user.name,
                value: user.id
            }))
        },
        handleApiSelect(item) {
            this.apiValue = item.label
        }
    }
}
</script>

样式定制

CSS 变量

:root {
    --smart-picker-primary: #007aff;     /* 主色调 */
    --smart-picker-border: #e5e5e5;      /* 边框色 */
    --smart-picker-bg: #ffffff;          /* 背景色 */
    --smart-picker-text: #333333;        /* 文字色 */
    --smart-picker-placeholder: #999999; /* 占位符色 */
}

自定义样式类

/* 修改弹窗高度 */
.smart-picker-popup .popup-container {
    height: 60vh;
}

/* 修改选项样式 */
.smart-picker-popup .option-item {
    padding: 15px 0;
}

/* 修改搜索框样式 */
.smart-picker-popup .search-input {
    border-radius: 20px;
}

注意事项

  1. 组件使用 Easycom 自动注册，无需手动引入
  2. 在 uni_modules 目录下正确放置组件文件
  3. 确保项目已安装 uni-icons 和 uni-popup 依赖
  4. API 模式下需要正确实现 @request 事件处理
  5. 多选模式下需要通过 @selected 事件获取结果

更新日志

v1.0.0

  • 初始版本发布
  • 支持固定数据和API模式
  • 支持单选和多选
  • 支持搜索和分页功能

隐私、权限声明

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

无

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

插件不采集任何数据

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

无

许可协议

MIT协议
评论列表 撰写评论 向官方投诉
加载更多...