::: 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
当前选择
{{data.selectorArray[data.index].name}}
当前选择
{{data.multiArray[0][data.multiIndex[0]]}},{{data.multiArray[1][data.multiIndex[1]]}},{{data.multiArray[2][data.multiIndex[2]]}}
当前选择
{{data.time}}
当前选择
{{data.dayDate}}
当前选择
{{data.monthDate}}
当前选择
{{data.yearDate}}
当前选择
{{getCityDisplayText()}}
{{data.region[0]}}{{data.region[1] ? ',' : ''}}{{data.region[1]}}{{data.region[2] ? ',' : ''}}{{data.region[2]}}
当前选择
{{data.selectorArray[data.index].name}}
```
:::
### 参见
- [参见uni-app相关文档](https://uniapp.dcloud.io/component/picker.html)