mirror of
https://gitee.com/vant-contrib/vant-weapp.git
synced 2025-04-06 03:58:05 +08:00
207 lines
5.5 KiB
Markdown
207 lines
5.5 KiB
Markdown
# Picker 选择器
|
||
|
||
### 介绍
|
||
|
||
提供多个选项集合供用户选择，支持单列选择和多列级联，通常与 [弹出层](#/popup) 组件配合使用。
|
||
|
||
### 引入
|
||
|
||
在`app.json`或`index.json`中引入组件，详细介绍见[快速上手](#/quickstart#yin-ru-zu-jian)。
|
||
|
||
```json
|
||
"usingComponents": {
|
||
"van-picker": "@vant/weapp/picker/index"
|
||
}
|
||
```
|
||
|
||
## 代码演示
|
||
|
||
### 基础用法
|
||
|
||
```html
|
||
<van-picker columns="{{ columns }}" bind:change="onChange" />
|
||
```
|
||
|
||
```javascript
|
||
import Toast from 'path/to/@vant/weapp/dist/toast/toast';
|
||
|
||
Page({
|
||
data: {
|
||
columns: ['杭州', '宁波', '温州', '嘉兴', '湖州'],
|
||
},
|
||
|
||
onChange(event) {
|
||
const { picker, value, index } = event.detail;
|
||
Toast(`当前值：${value}, 当前索引：${index}`);
|
||
},
|
||
});
|
||
```
|
||
|
||
### 默认选中项
|
||
|
||
单列选择器可以直接通过`default-index`属性设置初始选中项的索引值。
|
||
|
||
```html
|
||
<van-picker
|
||
columns="{{ columns }}"
|
||
default-index="{{ 2 }}"
|
||
bind:change="onChange"
|
||
/>
|
||
```
|
||
|
||
### 展示顶部栏
|
||
|
||
```html
|
||
<van-picker
|
||
show-toolbar
|
||
title="标题"
|
||
columns="{{ columns }}"
|
||
bind:cancel="onCancel"
|
||
bind:confirm="onConfirm"
|
||
/>
|
||
```
|
||
|
||
```javascript
|
||
import Toast from 'path/to/@vant/weapp/dist/toast/toast';
|
||
|
||
Page({
|
||
data: {
|
||
columns: ['杭州', '宁波', '温州', '嘉兴', '湖州'],
|
||
},
|
||
|
||
onConfirm(event) {
|
||
const { picker, value, index } = event.detail;
|
||
Toast(`当前值：${value}, 当前索引：${index}`);
|
||
},
|
||
|
||
onCancel() {
|
||
Toast('取消');
|
||
},
|
||
});
|
||
```
|
||
|
||
### 多列联动
|
||
|
||
```html
|
||
<van-picker columns="{{ columns }}" bind:change="onChange" />
|
||
```
|
||
|
||
```javascript
|
||
const citys = {
|
||
浙江: ['杭州', '宁波', '温州', '嘉兴', '湖州'],
|
||
福建: ['福州', '厦门', '莆田', '三明', '泉州'],
|
||
};
|
||
|
||
Page({
|
||
data: {
|
||
columns: [
|
||
{
|
||
values: Object.keys(citys),
|
||
className: 'column1',
|
||
},
|
||
{
|
||
values: citys['浙江'],
|
||
className: 'column2',
|
||
defaultIndex: 2,
|
||
},
|
||
],
|
||
},
|
||
|
||
onChange(event) {
|
||
const { picker, value, index } = event.detail;
|
||
picker.setColumnValues(1, citys[value[0]]);
|
||
},
|
||
});
|
||
```
|
||
|
||
### 禁用选项
|
||
|
||
选项可以为对象结构，通过设置 disabled 来禁用该选项。
|
||
|
||
```html
|
||
<van-picker columns="{{ columns }}" />
|
||
```
|
||
|
||
```javascript
|
||
Page({
|
||
data: {
|
||
columns: [
|
||
{ text: '杭州', disabled: true },
|
||
{ text: '宁波' },
|
||
{ text: '温州' },
|
||
],
|
||
},
|
||
});
|
||
```
|
||
|
||
### 加载状态
|
||
|
||
当 Picker 数据是通过异步获取时，可以通过 `loading` 属性显示加载提示。
|
||
|
||
```html
|
||
<van-picker columns="{{ columns }}" loading />
|
||
```
|
||
|
||
## API
|
||
|
||
### Props
|
||
|
||
| 参数 | 说明 | 类型 | 默认值 |
|
||
| --- | --- | --- | --- |
|
||
| columns | 对象数组，配置每一列显示的数据 | _Array_ | `[]` |
|
||
| show-toolbar | 是否显示顶部栏 | _boolean_ | `false` |
|
||
| toolbar-position | 顶部栏位置，可选值为`bottom` | _string_ | `top` |
|
||
| title | 顶部栏标题 | _string_ | `''` |
|
||
| loading | 是否显示加载状态 | _boolean_ | `false` |
|
||
| value-key | 选项对象中，文字对应的 key | _string_ | `text` |
|
||
| item-height | 选项高度 | _number_ | `44` |
|
||
| confirm-button-text | 确认按钮文字 | _string_ | `确认` |
|
||
| cancel-button-text | 取消按钮文字 | _string_ | `取消` |
|
||
| visible-item-count | 可见的选项个数 | _number_ | `6` |
|
||
| default-index | 单列选择器的默认选中项索引，<br>多列选择器请参考下方的 Columns 配置 | _number_ | `0` |
|
||
|
||
### Events
|
||
|
||
Picker 组件的事件会根据 columns 是单列或多列返回不同的参数。
|
||
|
||
| 事件名 | 说明 | 参数 |
|
||
| --- | --- | --- |
|
||
| confirm | 点击完成按钮时触发 | 单列：选中值，选中值对应的索引<br>多列：所有列选中值，所有列选中值对应的索引 |
|
||
| cancel | 点击取消按钮时触发 | 单列：选中值，选中值对应的索引<br>多列：所有列选中值，所有列选中值对应的索引 |
|
||
| change | 选项改变时触发 | 单列：Picker 实例，选中值，选中值对应的索引<br>多列：Picker 实例，所有列选中值，当前列对应的索引 |
|
||
|
||
### Columns 数据结构
|
||
|
||
当传入多列数据时，`columns`为一个对象数组，数组中的每一个对象配置每一列，每一列有以下`key`。
|
||
|
||
| key | 说明 |
|
||
| ------------ | -------------------------- |
|
||
| values | 列中对应的备选值 |
|
||
| defaultIndex | 初始选中项的索引，默认为 0 |
|
||
|
||
### 外部样式类
|
||
|
||
| 类名 | 说明 |
|
||
| ------------- | ------------ |
|
||
| custom-class | 根节点样式类 |
|
||
| active-class | 选中项样式类 |
|
||
| toolbar-class | 顶部栏样式类 |
|
||
| column-class | 列样式类 |
|
||
|
||
### 方法
|
||
|
||
通过 selectComponent 可以获取到 picker 实例并调用实例方法。
|
||
|
||
| 方法名 | 参数 | 返回值 | 介绍 |
|
||
| --- | --- | --- | --- |
|
||
| getValues | - | values | 获取所有列选中的值 |
|
||
| setValues | values | - | 设置所有列选中的值 |
|
||
| getIndexes | - | indexes | 获取所有列选中值对应的索引 |
|
||
| setIndexes | indexes | - | 设置所有列选中值对应的索引 |
|
||
| getColumnValue | columnIndex | value | 获取对应列选中的值 |
|
||
| setColumnValue | columnIndex, value | - | 设置对应列选中的值 |
|
||
| getColumnIndex | columnIndex | optionIndex | 获取对应列选中项的索引 |
|
||
| setColumnIndex | columnIndex, optionIndex | - | 设置对应列选中项的索引 |
|
||
| getColumnValues | columnIndex | values | 获取对应列中所有选项 |
|
||
| setColumnValues | columnIndex, values | - | 设置对应列中所有选项 |
|