更新记录

1.0.3(2025-10-14) 下载此版本

更新版本依赖

1.0.2(2025-10-14) 下载此版本

更新依赖

1.0.1(2025-10-14) 下载此版本

更新uni-ui依赖

查看更多

平台兼容性

uni-app

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

其他

多语言 暗黑模式 宽屏模式
× ×

zdp-search-picker

一、组件基础信息

项目 说明
组件名称 zdp-search-picker
核心功能 弹窗选择、关键词搜索、v-model 双向绑定、默认 label 字段渲染
依赖组件 uni-popup(弹窗容器)、uni-easyinput(搜索输入框)

二、组件参数(Props)

通过 props 配置组件数据源、渲染规则及初始状态,支持 v-model 双向绑定简化状态同步。

参数名 类型 默认值 必选 说明
data Array - 选择器核心数据源,支持两种格式:- 普通数组:如 ['选项1', '选项2'],无需额外配置;- 对象数组:如 [{label: '北京', code: '110'}],(通过 keyName 自定义)。
keyName String - 对象数组的渲染字段名,用于指定选择器中显示的文本字段。例如 data[{name: '上海', code: '310'}] 时,需设置 keyName="name" 以正确显示。
defaultIdx Number 0 选中项的数据源下标,支持 v-model:defaultIdx 双向绑定(如示例中 v-model:defaultIdx="defaultIdx"),父组件修改该值或子组件选择后,双方状态会自动同步。

三、组件事件(Events)

组件通过 $emit 触发事件,传递选择结果或操作状态,父组件可通过 @事件名 监听扩展逻辑。

事件名 触发时机 回调参数 说明
change 点击 “确定” 按钮后触发(v-model 依赖此事件同步状态) val:选中项在原 data 数组中的下标(Number) 无需手动监听(v-model 已自动处理),若需自定义逻辑可额外监听。
confirm 点击 “确定” 按钮后触发(携带完整选中信息) 1. text:选中项的显示文本(String,如 北京);2. val:选中项在原 data 中的下标(Number);3. record:选中项完整数据(与 data 元素格式一致,如 {label: '北京', code: '110'} 适用于需要获取选中项完整信息的场景,如获取对象数组中的 code 等额外字段。
cancel 点击 “取消” 按钮或关闭弹窗后触发 - 用于通知父组件 “取消选择” 操作,可在此事件中重置临时状态(如搜索输入框内容)。

四、组件插槽(Slots)

提供 content 插槽自定义触发区 UI,替代默认的 “请选择” 文本,支持插入图标、修改样式等个性化需求。

插槽名 作用域参数 说明
content 1. record:当前选中项的完整数据(与 data 元素格式一致);2. text:当前选中项的显示文本(String);3. idx:当前选中项在原 data 中的下标(Number) 点击插槽内容会唤起弹窗,可自定义触发区样式(如添加箭头、图标、修改文本对齐方式)。

五、核心用法示例

基于你提供的 zdp-search-picker 使用方式,提供完整示例,覆盖基础用法、自定义触发区等场景。

示例 1:基础用法(对象数组 + v-model 绑定)

适用于大多数业务场景,通过 v-model:defaultIdx 快速同步选中下标,默认使用 label 字段渲染文本。

<template>
  <view class="page-container">
    <!-- 组件使用:v-model绑定选中下标,keyName默认label(可省略) -->
    <zdp-search-picker
      ref="zdpSearchPicker"
      :data="cityData"
      v-model:defaultIdx="defaultIdx"
      @confirm="handleConfirm"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      // 对象数组数据源(默认使用label字段渲染)
      cityData: [
        { label: '北京', cityCode: '110000' },
        { label: '上海', cityCode: '310000' },
        { label: '广州', cityCode: '440100' },
        { label: '深圳', cityCode: '440300' }
      ],
      defaultIdx: 0 // 初始选中下标(北京),与组件v-model双向绑定
    };
  },
  methods: {
    // 监听confirm事件,获取选中项完整信息
    handleConfirm(text, val, record) {
      console.log('选中文本:', text); // 输出:北京(或其他选中项)
      console.log('选中下标:', val); // 输出:0(或其他选中下标)
      console.log('选中项完整数据:', record); // 输出:{label: '北京', cityCode: '110000'}
    }
  }
};
</script>

<style scoped>
.page-container {
  padding: 30rpx;
}
</style>

示例 2:自定义渲染字段(非 label 字段)

若数据源对象的显示字段不是 label(如 name),通过 keyName 指定渲染字段。

<template>
  <view class="page-container">
    <zdp-search-picker
      :data="productData"
      key-name="name" <!-- 指定渲染字段为name -->
      v-model:defaultIdx="defaultIdx"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      // 数据源字段为name,非默认label
      productData: [
        { id: 1, name: '手机', price: 5999 },
        { id: 2, name: '电脑', price: 9999 },
        { id: 3, name: '平板', price: 3999 }
      ],
      defaultIdx: 1 // 初始选中“电脑”
    };
  }
};
</script>

示例 3:自定义触发区(使用插槽)

通过 content 插槽修改触发区样式,添加图标和自定义文本,适配页面设计。

<template>
  <view class="page-container">
    <zdp-search-picker
      :data="payData"
      v-model:defaultIdx="defaultIdx"
    >
      <!-- 自定义触发区:插槽内容 -->
      <template #content="{ text }">
        <view class="custom-trigger">
          <uni-icons type="creditcard" size="24" color="#3C9CFF"></uni-icons>
          <text class="trigger-text">{{ text || '请选择支付方式' }}</text>
          <uni-icons type="right" size="20" color="#999"></uni-icons>
        </view>
      </template>
    </zdp-search-picker>
  </view>
</template>

<script>
export default {
  data() {
    return {
      payData: ['微信支付', '支付宝支付', '银行卡支付'], // 普通数组
      defaultIdx: 0
    };
  }
};
</script>

<style scoped>
.custom-trigger {
  display: flex;
  align-items: center;
  justify-content: space-between;
  padding: 20rpx 24rpx;
  border: 1px solid #eee;
  border-radius: 12rpx;
}
.trigger-text {
  margin: 0 16rpx;
  font-size: 28rpx;
  color: #333;
  flex: 1;
  text-align: left;
}
</style>

六、组件引用与方法调用(ref 用法)

通过 ref 引用组件,可在父组件中主动调用组件方法(如手动打开弹窗)。

方法名 说明 调用示例
open() 主动打开选择器弹窗 this.$refs.zdpSearchPicker.open()
close() 主动关闭选择器弹窗 this.$refs.zdpSearchPicker.close()

示例:父组件按钮触发弹窗打开

方法名 说明 调用示例
open() 主动打开选择器弹窗 this.$refs.zdpSearchPicker.open()
close() 主动关闭选择器弹窗 this.$refs.zdpSearchPicker.close()
<template>
  <view>
    <button @click="openPicker">打开选择器</button>
    <zdp-search-picker
      ref="zdpSearchPicker"
      :data="data"
      v-model:defaultIdx="defaultIdx"
    />
  </view>
</template>

<script>
export default {
  methods: {
    openPicker() {
      // 调用组件open方法打开弹窗
      this.$refs.zdpSearchPicker.open();
    }
  }
};
</script>

隐私、权限声明

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

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

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

许可协议

MIT协议