更新记录
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>