::: sourceCode ## picker > issues: https://issues.dcloud.net.cn/?mid=component.form-component.picker > 源码: https://github.com/dcloudio/uni-app/tree/uni-app-x-alpha/src/uni_modules/uni-form/components/picker ::: 从底部弹起的滚动选择器,现支持五种选择器,通过mode来区分,分别是普通选择器,多列选择器,时间选择器,日期选择器,省市区选择器,默认是普通选择器。 ### 兼容性 Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 5.08; iOS: 5.08; HarmonyOS: 4.61 picker组件其实是基于[picker-view组件](picker-view.md)封装了一个弹出形态。 5.08版本以前的Android/iOS平台可改用[picker-view组件](picker-view.md)、或[uni.showActionSheet](../api/action-sheet.md)。 或者使用开源组件[uni-data-picker](https://ext.dcloud.net.cn/plugin?id=3796)。这是也是基于[picker-view组件](picker-view.md)封装的云端一体组件,如果需要选择城市,那么推荐使用该组件。 支付宝小程序日期选择器的 `change` 事件返回值格式类似 `2026/10/11`,与微信小程序的 `2026-10-11` 不同。 ### 属性 | 名称 | 类型 | 默认值 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | disabled | boolean | false | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 5.08; iOS: 5.08; HarmonyOS: 4.61 | 是否禁用 | | mode | String as PropType\ | "selector" | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: x; Android: 5.08; iOS: 5.08; HarmonyOS: 4.61 | 选择器类型 | | range | string\[\] | \[\] | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 5.08; iOS: 5.08; HarmonyOS: 4.61 | mode为 selector 或 multiSelector 时,range 有效 | | range-key | string | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 5.08; iOS: 5.08; HarmonyOS: 4.61 | 当 range 是一个 Object Array 时,通过 range-key 来指定 Object 中 key 的值作为选择器显示内容 | | value | string \| number \| number\[\] | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 5.08; iOS: 5.08; HarmonyOS: 4.61 | 表示选择了 range 中的第几个(下标从 0 开始) | | start | string | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: x; Android: 5.08; iOS: 5.08; HarmonyOS: 4.61 | 表示有效时间范围的开始 | | end | string | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: x; Android: 5.08; iOS: 5.08; HarmonyOS: 4.61 | 表示有效时间范围的结束 | | fields | String as PropType\ | "day" | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: x; Android: 5.08; iOS: 5.08; HarmonyOS: 4.61 | 有效值 year,month,day,表示选择器的粒度 | | custom-item | string | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: x; Android: x; iOS: x; HarmonyOS: x | 可为每一列的顶部添加一个自定义的项 | | header-text | string | | Web: -; 微信小程序: 4.41; 支付宝小程序: x; Android: -; iOS: -; HarmonyOS: - | 选择器的标题,仅微信小程序安卓端可用 | | level | string | | Web: -; 微信小程序: 4.41; 支付宝小程序: x; Android: -; iOS: -; HarmonyOS: - | mode="region" 时有效,选择器层级 | | name | string | | Web: √; 微信小程序: x; 支付宝小程序: x; Android: 5.08; iOS: 5.08; HarmonyOS(VDOM): x; HarmonyOS(Vapor): 5.0 | 表单的控件名称,作为键值对的一部分与表单(form组件)一同提交 | | @change | (event: [UniPickerChangeEvent](#unipickerchangeevent)) => void | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: 5.31; Android: 5.08; iOS: 5.08; HarmonyOS: 4.61 | value 改变时触发 change 事件,event.detail = {value: value} | | @columnchange | (event: [UniPickerColumnChangeEvent](#unipickercolumnchangeevent)) => void | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: x; Android: 5.08; iOS: 5.08; HarmonyOS: 4.61 | 某一列的值改变时触发 columnchange 事件,event.detail = {column: column, value: value},column 的值表示改变了第几列(下标从0开始),value 的值表示变更值的下标 | | @cancel | (event: [UniPickerCancelEvent](#unipickercancelevent)) => void | | Web: 4.0; 微信小程序: 4.41; 支付宝小程序: x; Android: 5.08; iOS: 5.08; HarmonyOS: 4.61 | 取消选择时触发 | #### mode 的属性描述 | 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | selector | Web: -; 微信小程序: 4.41; 支付宝小程序: x; Android: 5.08; iOS: 5.08; HarmonyOS: 4.61 | 普通选择器 | | multiSelector | Web: -; 微信小程序: 4.41; 支付宝小程序: x; Android: 5.08; iOS: 5.08; HarmonyOS: 4.61 | 多列选择器 | | time | Web: -; 微信小程序: 4.41; 支付宝小程序: x; Android: 5.08; iOS: 5.08; HarmonyOS: 4.61 | 时间选择器 | | date | Web: -; 微信小程序: 4.41; 支付宝小程序: x; Android: 5.08; iOS: 5.08; HarmonyOS: 4.61 | 日期选择器 | | region | Web: -; 微信小程序: 4.41; 支付宝小程序: x; Android: -; iOS: -; HarmonyOS: - | 省市选择器 | #### fields 的属性描述 | 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | year | Web: -; 微信小程序: 4.41; 支付宝小程序: x; Android: 5.08; iOS: 5.08; HarmonyOS: 4.61 | 选择器粒度为年 | | month | Web: -; 微信小程序: 4.41; 支付宝小程序: x; Android: 5.08; iOS: 5.08; HarmonyOS: 4.61 | 选择器粒度为月份 | | day | Web: -; 微信小程序: 4.41; 支付宝小程序: x; Android: 5.08; iOS: 5.08; HarmonyOS: 4.61 | 选择器粒度为天 | #### level 的属性描述 | 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | province | Web: -; 微信小程序: 4.41; 支付宝小程序: x; Android: -; iOS: -; HarmonyOS: - | 省级选择器 | | city | Web: -; 微信小程序: 4.41; 支付宝小程序: x; Android: -; iOS: -; HarmonyOS: - | 市级选择器 | | region | Web: -; 微信小程序: 4.41; 支付宝小程序: x; Android: -; iOS: -; HarmonyOS: - | 区级选择器 | | sub-district | Web: -; 微信小程序: 4.41; 支付宝小程序: x; Android: -; iOS: -; HarmonyOS: - | 街道选择器 | ### 事件 #### UniPickerChangeEvent ```mermaid graph LR UniPickerChangeEvent -- Extends --> UniCustomEvent<UniPickerChangeEventDetail> style UniCustomEvent<UniPickerChangeEventDetail> color:#42b983 click UniCustomEvent<UniPickerChangeEventDetail> "https://doc.dcloud.net.cn/uni-app-x/component/common.html#unicustomevent" ``` ##### UniPickerChangeEventDetail ###### UniPickerChangeEventDetail 的属性值 | 名称 | 类型 | 必填 | | :- | :- | :- | | value | any | 是 | #### UniPickerColumnChangeEvent ```mermaid graph LR UniPickerColumnChangeEvent -- Extends --> UniCustomEvent<UniPickerColumnChangeEventDetail> style UniCustomEvent<UniPickerColumnChangeEventDetail> color:#42b983 click UniCustomEvent<UniPickerColumnChangeEventDetail> "https://doc.dcloud.net.cn/uni-app-x/component/common.html#unicustomevent" ``` ##### UniPickerColumnChangeEventDetail ###### UniPickerColumnChangeEventDetail 的属性值 | 名称 | 类型 | 必填 | | :- | :- | :- | | value | number | 是 | | column | number | 是 | #### UniPickerCancelEvent 取消事件触发 ```mermaid graph LR UniPickerCancelEvent -- Extends --> UniCustomEvent<UniPickerCancelEventDetail> style UniCustomEvent<UniPickerCancelEventDetail> color:#42b983 click UniCustomEvent<UniPickerCancelEventDetail> "https://doc.dcloud.net.cn/uni-app-x/component/common.html#unicustomevent" ``` ### 示例 示例为[hello uni-app x alpha分支](https://gitcode.com/dcloud/hello-uni-app-x/blob/prod_alpha/pages/component/picker/picker.uvue),与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例[另见](https://gitcode.com/dcloud/hello-uni-app-x/blob/master//pages/component/picker/picker.uvue) ::: preview https://hellouniappx.dcloud.net.cn/web/#/pages/component/picker/picker > appRedirect https://hellouniappx.dcloud.net.cn/appredirect.html?path=pages/component/picker/picker >示例 ```vue ``` ::: ### 参见 - [参见uni-app相关文档](https://uniapp.dcloud.io/component/picker.html)