---
name: "picker"
mode: "component"
versionRequirements:
  - { name: "基础库", version: "2.10.0" }
title: "picker - 从底部弹起的滚动选择器"
---

## picker

> [VERSION] 基础库 >= 2.10.0

### 描述

从底部弹起的滚动选择器。

### 属性

| 属性 | 类型 | 必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `checked` | `boolean` | 否 | `false` | 是否选中 |
| `color` | `string` | 否 | `""` | 选中时的颜色，同 CSS color |
| `range` | `any[]` | 否 | `[]` | 选择器的数据源，mode 为 selector 或 multiSelector 时有效 |
| `value` | `any[] \| string` | 否 | `""` | mode = selector，表示选择了 range 中的第几个（下标从 0 开始） mode = multiSelector，表示选择了 range 中的第几个（下标从 0 开始） mode = time，表示选中的时间，格式为"hh:mm" mode = date，表示选中的日期，格式为"YYYY-MM-DD" |
| `mode` | `string` | 否 | `"selector"` | 选择器类型，可选值：selector 单列选择，multiSelector 多列选择，time 时间选择，date 日期选择 |
| `fields` | `string` | 否 | `"day"` | 仅 date 模式有效，可选值：year 精确到年，month 精确到月，day 精确到日 |
| `start` | `string` | 否 | `""` | 仅 time/date 模式有效，表示有效时间/日期范围的开始 |
| `end` | `string` | 否 | `""` | 仅 time/date 模式有效，表示有效时间/日期范围的结束 |
| `disabled` | `boolean` | 否 | `false` | 是否禁用 |
| `range-key` | `string` | 否 | `""` | range 为对象数组时，通过 rangeKey 来指定 Object 中 key 的值作为选择器显示内容 |
| `confirm-text` | `string` | 否 | `"确定"` | 确认按钮文字 |
| `cancel-text` | `string` | 否 | `"取消"` | 取消按钮文字 |

#### 事件

| 事件名 | 类型 | 描述 |
| --- | --- | --- |
| `change` | `(event: PickerChangeEvent) => void` | 确定选择时触发 |
| `cancel` | `(event: Object) => void` | 取消选择时触发 |
| `columnchange` | `(event: PickerColumnChangeEvent) => void` | 多列选择器某一列选项变化时触发 |

**PickerChangeEvent**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"change"` | 事件类型 |
| `detail` | `PickerChangeDetail` | 事件数据 |

**cancel 的回调参数对象**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"cancel"` |  |

**PickerColumnChangeEvent**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"columnchange"` | 事件类型 |
| `detail` | `PickerColumnChangeDetail` | 事件数据 |

### 示例代码

#### 基础用法

*index.tyml*

```xml
<picker mode="selector" range="{{array}}" bind:change="onChange">
  <view class="picker">当前选择: {{array[index]}}</view>
</picker>
```

*index.tyss*

```css
.picker { padding: 20rpx; background-color: #f5f5f5; }
```

*index.js*

```javascript
Page({
  data: { array: ['美国', '中国', '巴西'], index: 0 },
  onChange(e) {
    this.setData({ index: e.detail.value });
  },
});
```

#### 时间选择器

*index.tyml*

```xml
<picker mode="time" value="{{time}}" start="09:00" end="18:00" bind:change="onTimeChange">
  <view class="picker">当前选择: {{time}}</view>
</picker>
```

*index.tyss*

```css
.picker { padding: 20rpx; background-color: #f5f5f5; }
```

*index.js*

```javascript
Page({
  data: { time: '12:00' },
  onTimeChange(e) {
    this.setData({ time: e.detail.value });
  },
});
```

#### 日期选择器

*index.tyml*

```xml
<picker mode="date" value="{{date}}" start="2020-01-01" end="2030-12-31" fields="day" bind:change="onDateChange" bind:cancel="onCancel">
  <view class="picker">当前日期: {{date}}</view>
</picker>
```

*index.tyss*

```css
.picker { padding: 20rpx; background-color: #f5f5f5; }
```

*index.js*

```javascript
Page({
  data: { date: '2026-01-01' },
  onDateChange(e) {
    this.setData({ date: e.detail.value });
  },
  onCancel() {
    console.log('取消选择');
  },
});
```

#### 多列选择器

*index.tyml*

```xml
<picker mode="multiSelector" range="{{range}}" value="{{value}}" bind:change="onChange" bind:columnchange="onColumnChange">
  <view class="picker">{{range[0][value[0]]}} - {{range[1][value[1]]}}</view>
</picker>
```

*index.tyss*

```css
.picker { padding: 20rpx; background-color: #f5f5f5; }
```

*index.js*

```javascript
Page({
  data: {
    range: [
      ['广东', '浙江', '江苏'],
      ['广州', '杭州', '南京'],
    ],
    value: [0, 0],
  },
  onChange(e) {
    this.setData({ value: e.detail.value });
  },
  onColumnChange(e) {
    console.log('列变更:', e.detail.column, e.detail.value);
  },
});
```