---
name: "picker-view"
mode: "component"
versionRequirements:
  - { name: "基础库", version: "2.10.0" }
title: "picker-view - 嵌入页面的滚动选择器"
---

## picker-view

> [VERSION] 基础库 >= 2.10.0

### 描述

嵌入页面的滚动选择器，需搭配 picker-view-column 使用。

### 属性

| 属性 | 类型 | 必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `checked` | `boolean` | 否 | `false` | 是否选中 |
| `disabled` | `boolean` | 否 | `false` | 是否禁用 |
| `color` | `string` | 否 | `""` | 选中时的颜色，同 CSS color |
| `value` | `any[]` | 否 | `[]` | 数组中的数字依次表示 picker-view 内的 picker-view-column 选择的第几项 |
| `indicator-style` | `string` | 否 | `""` | 设置选择器中间选中框的样式 |
| `mask-style` | `string` | 否 | `""` | 设置蒙层的样式 |

#### 事件

| 事件名 | 类型 | 描述 |
| --- | --- | --- |
| `change` | `(event: PickerViewChangeEvent) => void` | 滚动选择时触发 |
| `pickstart` | `(event: Object) => void` | 滚动选择开始时触发 |
| `pickend` | `(event: Object) => void` | 滚动选择结束时触发 |

**PickerViewChangeEvent**

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

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

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"pickstart"` | 事件类型 |

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

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"pickend"` | 事件类型 |

### 示例代码

#### 基础用法

*index.tyml*

```xml
<picker-view value="{{value}}" class="picker" bindchange="onChange">
  <picker-view-column>
    <view ty:for="{{years}}">{{item}}年</view>
  </picker-view-column>
</picker-view>
```

*index.tyss*

```css
.picker { height: 300rpx; }
```

*index.js*

```javascript
Page({
  data: {
    years: [2024, 2025, 2026],
    value: [0],
  },
  onChange(e) {
    this.setData({ value: e.detail.value });
  },
});
```

#### 多列选择

*index.tyml*

```xml
<picker-view value="{{value}}" class="picker" bindchange="onChange">
  <picker-view-column>
    <view ty:for="{{hours}}">{{item}}时</view>
  </picker-view-column>
  <picker-view-column>
    <view ty:for="{{minutes}}">{{item}}分</view>
  </picker-view-column>
</picker-view>
```

*index.tyss*

```css
.picker { height: 300rpx; }
```

*index.js*

```javascript
Page({
  data: {
    hours: Array.from({ length: 24 }, function (_, i) {
      return i;
    }),
    minutes: Array.from({ length: 60 }, function (_, i) {
      return i;
    }),
    value: [0, 0],
  },
  onChange(e) {
    this.setData({ value: e.detail.value });
  },
});
```

#### 自定义指示器与蒙层样式

*index.tyml*

```xml
<picker-view
  value="{{value}}"
  class="picker"
  indicator-style="height: 40px; border-top: 1px solid #e5e5e5; border-bottom: 1px solid #e5e5e5;"
  mask-style="background-image: linear-gradient(to bottom, rgba(255,255,255,0.9), rgba(255,255,255,0.4)), linear-gradient(to top, rgba(255,255,255,0.9), rgba(255,255,255,0.4));"
  bind:change="onChange"
  bind:pickstart="onPickStart"
  bind:pickend="onPickEnd"
>
  <picker-view-column>
    <view ty:for="{{items}}" class="picker-item">{{item}}</view>
  </picker-view-column>
</picker-view>
```

*index.tyss*

```css
.picker { height: 300rpx; }
.picker-item { line-height: 40px; text-align: center; }
```

*index.js*

```javascript
Page({
  data: {
    items: ['选项A', '选项B', '选项C', '选项D', '选项E'],
    value: [0],
  },
  onChange(e) {
    this.setData({ value: e.detail.value });
  },
  onPickStart() {
    console.log('开始滚动');
  },
  onPickEnd() {
    console.log('结束滚动');
  },
});
```