picker

从底部弹起的滚动选择器。支持五种选择器，通过mode来区分，分别是普通选择器，多列选择器，时间选择器，日期选择器，省市区选择器，默认是普通选择器。

元服务
x

HarmonyOS Next 兼容性

HarmonyOS Next
HBuilderX 4.23

普通选择器

mode = selector

属性说明

属性名	类型	默认值	说明	平台差异说明
range	Array / Array<Object>	[]	mode为 selector 或 multiSelector 时，range 有效
range-key	String		当 range 是一个 Array＜Object＞ 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容
value	Number	0	value 的值表示选择了 range 中的第几个（下标从 0 开始）
selector-type	String	auto	UI类型,仅大屏时该属性生效，支持 picker、select、auto，默认在 iPad 以 picker 样式展示而在 PC 以 select 样式展示	H5 2.9.9+
disabled	Boolean	false	是否禁用	快手小程序不支持
@change	EventHandle		value 改变时触发 change 事件，event.detail = {value: value}
@cancel	EventHandle		取消选择或点遮罩层收起 picker 时触发	快手小程序不支持

• picker在各平台的实现是有UI差异的，有的平台如百度、支付宝小程序的Android端是从中间弹出的；有的平台支持循环滚动如百度小程序；有的平台没有取消按钮如App-iOS端。但均不影响功能使用。

多列选择器

mode = multiSelector

平台差异说明

App	H5	微信小程序	支付宝小程序	百度小程序	抖音小程序、飞书小程序	QQ小程序	快手小程序	京东小程序	元服务
vue支持，nvue自2.4起支持	√	√	x	√	√	√	√	√	x

支付宝小程序 picker 组件不支持多列选择，可以使用 picker-view 组件替代。

属性说明

属性名	类型	默认值	说明
range	二维 Array / 二维 Array＜Object＞	[]	mode为 selector 或 multiSelector 时，range 有效。二维数组，长度表示多少列，数组的每项表示每列的数据，如[["a","b"], ["c","d"]]
range-key	String		当 range 是一个二维 Array＜Object＞ 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容
value	Array	[]	value 每一项的值表示选择了 range 对应项中的第几个（下标从 0 开始）
@change	EventHandle		value 改变时触发 change 事件，event.detail = {value: value}
@columnchange	EventHandle		某一列的值改变时触发 columnchange 事件，event.detail = {column: column, value: value}，column 的值表示改变了第几列（下标从0开始），value 的值表示变更值的下标
@cancel	EventHandle		取消选择时触发（快手小程序不支持）
disabled	Boolean	false	是否禁用（快手小程序不支持）

bug & tips

• 由于 JavaScript 的限制 vue 不能观测如下方式设置 value：this.value[0] = 0 （vue 注意事项），解决方式参考：hello-uniapp 示例
• 微信开发工具的pc模拟器有可能出现拖动数据错乱，使用真机正常

时间选择器

mode = time

平台差异说明

App	H5	微信小程序	支付宝小程序	百度小程序	抖音小程序、飞书小程序	QQ小程序	快手小程序	京东小程序	元服务
√	√	√	√	√	√	√	x	√	x

• 时间选择在App端调用的是os的原生时间选择控件，在不同平台有不同的ui表现

属性说明

属性名	类型	默认值	说明	平台差异说明
value	String		表示选中的时间，格式为"hh:mm"
start	String		表示有效时间范围的开始，字符串格式为"hh:mm"	App 不支持
end	String		表示有效时间范围的结束，字符串格式为"hh:mm"	App 不支持
@change	EventHandle		value 改变时触发 change 事件，event.detail = {value: value}
@cancel	EventHandle		取消选择时触发
disabled	Boolean	false	是否禁用

日期选择器

mode = date

平台差异说明

App	H5	微信小程序	支付宝小程序	百度小程序	抖音小程序、飞书小程序	QQ小程序	快手小程序	京东小程序	元服务
√	√	√	√	√	√	√	x	√	x

日期选择默认在App端和H5端（PC版Chrome以及PC版FireFox）调用的是os的原生日期选择控件，在不同平台有不同的ui表现，当配置fields参数后使用统一的展示方式。

属性说明

属性名	类型	默认值	说明	平台差异说明
value	String	0	表示选中的日期，格式为"YYYY-MM-DD"
start	String		表示有效日期范围的开始，字符串格式为"YYYY-MM-DD"
end	String		表示有效日期范围的结束，字符串格式为"YYYY-MM-DD"
fields	String	day	有效值 year、month、day，表示选择器的粒度，默认为 day，App 端未配置此项时使用系统 UI	H5、App 2.6.3+、微信小程序、支付宝小程序、百度小程序、抖音小程序、飞书小程序
@change	EventHandle		value 改变时触发 change 事件，event.detail = {value: value}
@cancel	EventHandle		取消选择时触发
disabled	Boolean	false	是否禁用

fields 有效值

值	说明
year	选择器粒度为年
month	选择器粒度为月份
day	选择器粒度为天

省市区选择器

mode = region

平台差异说明

App	H5	微信小程序	支付宝小程序	百度小程序	抖音小程序、飞书小程序	QQ小程序	快手小程序	京东小程序	元服务
x	x	√	x	√	√	√	x	√	x

• 小程序平台在引擎层面内置了省市区数据。但省市区包含大量数据，占用体积，并非所有应用都需要，且很多城市数据有自维护需求，所以在App和H5平台没有在前端内置这些数据。可以基于多列picker或picker-view，自行填充城市数据。插件市场有较多类似插件，详见。注意基于多列picker方式的地区选择不能运行在支付宝小程序上，只有基于picker-view的可以全端运行。尤其推荐插件uni-data-picker，自带省市区的联网数据，自带懒加载。

属性名	类型	默认值	说明
value	Array	[]	表示选中的省市区，默认选中每一列的第一个值
custom-item	String		可为每一列的顶部添加一个自定义的项
@change	EventHandle		value 改变时触发 change 事件，event.detail = {value: value}
@cancel	EventHandle		取消选择时触发（快手小程序不支持）
disabled	Boolean	false	是否禁用（快手小程序不支持）

示例 查看演示

以下示例代码，来自于hello uni-app项目，推荐使用HBuilderX，新建uni-app项目，选择hello uni-app模板，可直接体验完整示例。

Template

Script

<!-- 本示例未包含完整css，获取外链css请参考上文，在hello uni-app项目中查看 -->
<template>
	<view>
		<view class="uni-title uni-common-pl">地区选择器</view>
		<view class="uni-list">
			<view class="uni-list-cell">
				<view class="uni-list-cell-left">
					当前选择
				</view>
				<view class="uni-list-cell-db">
					<picker @change="bindPickerChange" :value="index" :range="array">
						<view class="uni-input">{{array[index]}}</view>
					</picker>
				</view>
			</view>
		</view>

		<view class="uni-title uni-common-pl">时间选择器</view>
		<view class="uni-list">
			<view class="uni-list-cell">
				<view class="uni-list-cell-left">
					当前选择
				</view>
				<view class="uni-list-cell-db">
					<picker mode="time" :value="time" start="09:01" end="21:01" @change="bindTimeChange">
						<view class="uni-input">{{time}}</view>
					</picker>
				</view>
			</view>
		</view>

		<view class="uni-title uni-common-pl">日期选择器</view>
		<view class="uni-list">
			<view class="uni-list-cell">
				<view class="uni-list-cell-left">
					当前选择
				</view>
				<view class="uni-list-cell-db">
					<picker mode="date" :value="date" :start="startDate" :end="endDate" @change="bindDateChange">
						<view class="uni-input">{{date}}</view>
					</picker>
				</view>
			</view>
		</view>
	</view>
</template>

示例代码说明：以上示例代码从hello uni-app示例中复制，涉及的css样式在hello uni-app的app.vue和uni.css中

预览H5效果：使用浏览器的手机模式访问https://hellouniapp.dcloud.net.cn/pages/component/picker/picker

注意

• 在picker内容还在滚动时或滚动回弹动画还未结束时，点确定关闭弹出的picker，数据无法及时更新。需等待一下，或手动触停滚动再点确定。所有平台均如此

扩展

• uni ui提供了增强版<uni-data-picker>组件，详见：https://ext.dcloud.net.cn/plugin?id=3796
• 该组件优势如下：
  • 符合datacom规范，只需传入data，就可以自动生成界面
  • 符合uni-forms，表单校验规范
  • 突破多列picker的3列限制，可以承载更多列数据
  • 选择区域面积更高更大
  • 支持多列数据分级加载，比如省市区选择，先选择省，然后动态联网加载该省的市。
  • uniCloud自带了opendb表，opendb-city-china，包括全国的省市区数据。在<uni-data-picker>组件上可直接绑定该数据，生成全端可用的、联网懒加载的省市区选择。
  • unicloud数据库提供了DB Schema，还提供了schema2code自动生成全套表单页面，包括界面、校验逻辑、提交入库。在schema中配置字段的格式，比如在用户地址表uni-id-address的字段area_code配置值域指向opendb-city-china表，即可自动生成该用户地址的生成页面