picker GitCode GitHub

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

兼容性

Web	微信小程序	Android	iOS	HarmonyOS
4.0	4.41	x	x	4.61

picker组件其实是基于picker-view组件封装了一个弹出形态。

Android/iOS平台可改用picker-view组件、或uni.showActionSheet。

或者使用开源组件uni-data-picker。这是也是基于picker-view组件封装的云端一体组件，如果需要选择城市，那么推荐使用该组件。

属性

名称	类型	默认值	兼容性	描述
disabled	boolean	-	Web 微信小程序 Android iOS HarmonyOS 4.0 4.41 3.9 x 4.61	是否禁用
mode	string	-	Web 微信小程序 Android iOS HarmonyOS 4.0 4.41 3.9 x 4.61	选择器类型
合法值 兼容性 描述 selector Web 微信小程序 Android iOS HarmonyOS - 4.41 - - 4.61 普通选择器 multiSelector Web 微信小程序 Android iOS HarmonyOS - 4.41 - - 4.61 多列选择器 time Web 微信小程序 Android iOS HarmonyOS - 4.41 - - 4.61 时间选择器 date Web 微信小程序 Android iOS HarmonyOS - 4.41 - - 4.61 日期选择器 region Web 微信小程序 Android iOS HarmonyOS - 4.41 - - - 省市选择器
range	array	-	Web 微信小程序 Android iOS HarmonyOS 4.0 4.41 3.9 x 4.61	mode为 selector 或 multiSelector 时，range 有效
range-key	string	-	Web 微信小程序 Android iOS HarmonyOS 4.0 4.41 3.9 x 4.61	当 range 是一个 Object Array 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容
value	string	-	Web 微信小程序 Android iOS HarmonyOS 4.0 4.41 3.9 x 4.61	mode为select或multiSelector时：value 的值表示选择了 range 中的第几个（下标从 0 开始）；mode为time时：表示选中的时间，格式为"hh:mm"；mode为date时：表示选中的日期，格式为"YYYY-MM-DD"；mode为region时： 表示选中的省市区，默认选中每一列的第一个值。
start	string	-	Web 微信小程序 Android iOS HarmonyOS 4.0 4.41 3.9 x 4.61	mode为time：表示有效时间范围的开始，字符串格式为"hh:mm"；mode为date：表示有效日期范围的开始，字符串格式为"YYYY-MM-DD"
end	string	-	Web 微信小程序 Android iOS HarmonyOS 4.0 4.41 3.9 x 4.61	mode为time：表示有效时间范围的结束，字符串格式为"hh:mm"；mode为date：表示有效日期范围的结束，字符串格式为"YYYY-MM-DD"
fields	string	-	Web 微信小程序 Android iOS HarmonyOS 4.0 4.41 3.9 x 4.61	有效值 year,month,day，表示选择器的粒度
合法值 兼容性 描述 year Web 微信小程序 Android iOS HarmonyOS - 4.41 - - 4.61 选择器粒度为年 month Web 微信小程序 Android iOS HarmonyOS - 4.41 - - 4.61 选择器粒度为月份 day Web 微信小程序 Android iOS HarmonyOS - 4.41 - - 4.61 选择器粒度为天
custom-item	string	-	Web 微信小程序 Android iOS HarmonyOS 4.0 4.41 3.9 x 4.61	可为每一列的顶部添加一个自定义的项
@change	(event: UniPickerChangeEvent) => void	-	Web 微信小程序 Android iOS HarmonyOS 4.0 4.41 3.9 x 4.61	value 改变时触发 change 事件，event.detail = {value: value}
@columnchange	(event: UniPickerColumnChangeEvent) => void	-	Web 微信小程序 Android iOS HarmonyOS 4.0 4.41 3.9 x 4.61	某一列的值改变时触发 columnchange 事件，event.detail = {column: column, value: value}，column 的值表示改变了第几列（下标从0开始），value 的值表示变更值的下标
@cancel	(event: UniPickerCancelEvent) => void	-	Web 微信小程序 Android iOS HarmonyOS 4.0 4.41 3.9 x 4.61	取消选择时触发
header-text	string	-	Web 微信小程序 Android iOS HarmonyOS - 4.41 - - -	(string) 选择器的标题，仅安卓可用
level	string	-	Web 微信小程序 Android iOS HarmonyOS - 4.41 - - -	mode="region" 时有效，选择器层级
合法值 兼容性 描述 province Web 微信小程序 Android iOS HarmonyOS - 4.41 - - - 省级选择器 city Web 微信小程序 Android iOS HarmonyOS - 4.41 - - - 市级选择器 region Web 微信小程序 Android iOS HarmonyOS - 4.41 - - - 区级选择器 sub-district Web 微信小程序 Android iOS HarmonyOS - 4.41 - - - 街道选择器

事件

UniPickerChangeEvent

UniPickerChangeEventDetail

UniPickerChangeEventDetail 的属性值

名称	类型	必填	默认值	兼容性	描述
value	any	是	-	-	-

UniPickerColumnChangeEvent

UniPickerColumnChangeEventDetail

UniPickerColumnChangeEventDetail 的属性值

名称	类型	必填	默认值	兼容性	描述
value	number	是	-	-	-
column	number	是	-	-	-

示例

示例为hello uni-app x alpha分支，与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见

Template

Script

<template>
  <!-- #ifdef APP -->
  <scroll-view style="flex: 1">
  <!-- #endif -->
    <page-head :title="title"></page-head>
    <text class="uni-title uni-common-pl">禁用选择器</text>
    <view class="uni-list">
      <view class="uni-list-cell">
        <view class="uni-list-cell-left">当前选择</view>
        <view class="uni-list-cell-db">
          <picker class="picker-disabled--test" @change="bindPickerChange" disabled :value="index" :range="selectorArray" range-key="name">
            <view class="uni-input picker-disabled--value">{{selectorArray[index].name}}</view>
          </picker>
        </view>
      </view>
    </view>
    <text class="uni-picker-tips">注：值与普通选择器同步，但不可选择</text>
    <text class="uni-title uni-common-pl">普通选择器</text>
    <view class="uni-list">
      <view class="uni-list-cell">
        <view class="uni-list-cell-left">当前选择</view>
        <view class="uni-list-cell-db">
          <picker class="picker-selector--test" @change="bindPickerChange" :value="index" :range="selectorArray" range-key="name">
            <view class="uni-input picker-selector--value">{{selectorArray[index].name}}</view>
          </picker>
        </view>
      </view>
    </view>

    <text class="uni-title uni-common-pl">多列选择器</text>
    <view class="uni-list">
      <view class="uni-list-cell">
        <text class="uni-list-cell-left">当前选择</text>
        <view class="uni-list-cell-db">
          <picker class="picker-multi--test" mode="multiSelector" @columnchange="bindMultiPickerColumnChange" :value="multiIndex" :range="multiArray">
            <view class="uni-input picker-multi--value">
              {{multiArray[0][multiIndex[0]]}}，{{multiArray[1][multiIndex[1]]}}，{{multiArray[2][multiIndex[2]]}}
            </view>
          </picker>
        </view>
      </view>
    </view>

    <text class="uni-title uni-common-pl">时间选择器</text>
    <view class="uni-list">
      <view class="uni-list-cell">
        <view class="uni-list-cell-left">当前选择</view>
        <view class="uni-list-cell-db">
          <picker class="picker-time--test" mode="time" :value="time" start="09:01" end="21:01" @change="bindTimeChange">
            <view class="uni-input">{{time}}</view>
          </picker>
        </view>
      </view>
    </view>
    <text class="uni-picker-tips">注：选择 09:01 ~ 21:01 之间的时间, 不在区间内不能选中</text>

    <text class="uni-title uni-common-pl">日期选择器 fields = day</text>
    <view class="uni-list">
      <view class="uni-list-cell">
        <text class="uni-list-cell-left">当前选择 </text>
        <view class="uni-list-cell-db">
          <picker class="picker-date-day--test" mode="date" :value="dayDate" :start="startDate" :end="endDate" @change="bindDayDateChange">
            <view class="uni-input">{{dayDate}}</view>
          </picker>
        </view>
      </view>
    </view>
    <text class="uni-picker-tips">注：选择当前时间 ±10 年之间的时间, 不在区间内不能选中</text>

    <text class="uni-title uni-common-pl">日期选择器 fields = month</text>
    <view class="uni-list">
      <view class="uni-list-cell">
        <text class="uni-list-cell-left">当前选择 </text>
        <view class="uni-list-cell-db">
          <picker class="picker-date-month--test" mode="date" fields="month" :value="monthDate" :start="startDate" :end="endDate" @change="bindMonthDateChange">
            <view class="uni-input">{{monthDate}}</view>
          </picker>
        </view>
      </view>
    </view>
    <text class="uni-picker-tips">注：选择当前时间 ±10 年之间的时间, 不在区间内不能选中，且日不可选</text>

    <text class="uni-title uni-common-pl">日期选择器 fields = year</text>
    <view class="uni-list">
      <view class="uni-list-cell">
        <text class="uni-list-cell-left">当前选择 </text>
        <view class="uni-list-cell-db">
          <picker class="picker-date-year--test" mode="date" fields="year" :value="yearDate" :start="startDate" :end="endDate" @change="bindYearDateChange">
            <view class="uni-input">{{yearDate}}</view>
          </picker>
        </view>
      </view>
    </view>
    <text class="uni-picker-tips">注：选择当前时间 ±10 年之间的时间, 不在区间内不能选中，且只能选择年</text>

  <!-- #ifdef APP -->
  </scroll-view>
  <!-- #endif -->
</template>


<style>
  .uni-title {
    font-size: 14px;
  }

  .uni-picker-tips {
    font-size: 12px;
    color: #666;
    margin-top: 5px;
    margin-bottom: 15px;
    padding: 0 15px;
  }
</style>

参见

• 相关 Bug
• 参见uni-app相关文档
• 微信小程序文档
• 支付宝小程序文档
• 百度小程序文档
• 抖音小程序文档
• 飞书小程序文档
• 钉钉小程序文档
• QQ小程序文档
• 快手小程序文档
• 京东小程序文档
• 华为快应用文档
• 360小程序文档