更新记录

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

[1.0.0] - 2026-06-03

✨ 新增

• 初始版本发布
• 支持 v-model 双向绑定
• 支持关键词本地搜索
• 支持自定义字段映射（labelKey / valueKey）
• 底部弹窗 + 固定高度滚动列表
• 线条箭头动画
• 兼容 Vue 2 和 Vue 3

平台兼容性

自定义选择器组件（Selector）

一个为 uni-app 量身打造的选择器公用组件，支持 v-model 双向绑定、关键词搜索、选项回显，样式紧凑，开箱即用。

✨ 特性

• 支持 v-model，自动回显选中项
• 内置本地搜索（过滤选项 label）
• 底部弹窗设计，选项列表固定高度，滚动流畅
• 自定义字段映射（labelKey / valueKey）
• 禁用状态、占位文本
• 线条风格箭头，展开/收起动画
• 纯 uni_modules 形式，无需手动注册，直接使用
• 兼容 Vue 2 和 Vue 3

📦 安装方式（二选一）

方式一：通过插件市场导入（推荐）

1. 打开 DCloud 插件市场本插件页面（示例链接：https://ext.dcloud.net.cn/plugin?id=xxx）
2. 点击 使用 HBuilderX 导入插件 按钮
3. 选择你的 uni-app 项目，HBuilderX 会自动将插件下载到 uni_modules/yourname-uniapp-selector 目录
4. 完成！插件已全局可用，无需任何额外配置

方式二：手动下载复制

1. 下载本插件源码包

2. 将解压后的 yourname-uniapp-selector 文件夹完整复制到你的项目根目录下的 uni_modules 文件夹中（如不存在请新建）

3. 确保目录结构如下：

4. 插件已生效，可直接在页面中使用 <Selector />

🚀 快速上手

基础用法

<template>
    <view class="content">
        <selector v-model="selectedValue" :options="cityOptions" labelKey="name" valueKey="id" placeholder="请选择" @change="handleChange"></selector>
    </view>
</template>

<script>
    export default {
        data() {
            return {
                cityOptions:[
                    { name: '北京', id: 'beijing' },
                    { name: '上海', id: 'shanghai' },
                    { name: '广州', id: 'guangzhou' }
                ],
                selectedValue:'guangzhou'
            }
        },
        onLoad() {

        },
        methods: {
            handleChange(value,option){
                console.log('选中值:',value)
                console.log('选项对象:',option)
            }
        }
    }
</script>

属性名 类型  默认值 说明
v-model String / Number / Object    ''  当前选中的值，支持 v-model
options Array   []  选项列表，每项需包含 label 和 value（或通过 labelKey/valueKey 自定义）
placeholder String  '请选择'   未选中时的占位文本
disabled    Boolean false   是否禁用组件
labelKey    String  'label' 选项文本字段名
valueKey    String  'value' 选项值字段名
isSearch    Boolean true    是否使用搜索

组件内部使用 rpx 单位，适配不同屏幕宽度。如果需要自定义样式（例如修改选择框高度、选项列表高度、主色调等），可以在页面中覆盖对应的 CSS 类名：

/* 修改选择框背景和边框 */
.selector-trigger {
  background-color: #f8f8f8;
  border-color: #ddd;
}
/* 修改选项列表高度 */
.options-list {
  height: 500rpx;
}
/* 修改选中项的文字颜色 */
.option-item.is-selected .option-label {
  color: #ff6600;
}