Picker 选择器

介绍

提供多个选项集合供用户选择,支持单列选择和多列级联,通常与 弹出层 组件配合使用。

引入

app.jsonindex.json中引入组件,详细介绍见快速上手

  1. "usingComponents": {
  2. "van-picker": "@vant/weapp/picker/index"
  3. }

代码演示

基础用法

  1. <van-picker columns="{{ columns }}" bind:change="onChange" />
  1. import Toast from 'path/to/@vant/weapp/dist/toast/toast';
  2. Page({
  3. data: {
  4. columns: ['杭州', '宁波', '温州', '嘉兴', '湖州'],
  5. },
  6. onChange(event) {
  7. const { picker, value, index } = event.detail;
  8. Toast(`当前值:${value}, 当前索引:${index}`);
  9. },
  10. });

默认选中项

单列选择器可以直接通过default-index属性设置初始选中项的索引值。

  1. <van-picker
  2. columns="{{ columns }}"
  3. default-index="{{ 2 }}"
  4. bind:change="onChange"
  5. />

展示顶部栏

  1. <van-picker
  2. show-toolbar
  3. title="标题"
  4. columns="{{ columns }}"
  5. bind:cancel="onCancel"
  6. bind:confirm="onConfirm"
  7. />
  1. import Toast from 'path/to/@vant/weapp/dist/toast/toast';
  2. Page({
  3. data: {
  4. columns: ['杭州', '宁波', '温州', '嘉兴', '湖州'],
  5. },
  6. onConfirm(event) {
  7. const { picker, value, index } = event.detail;
  8. Toast(`当前值:${value}, 当前索引:${index}`);
  9. },
  10. onCancel() {
  11. Toast('取消');
  12. },
  13. });

多列联动

  1. <van-picker columns="{{ columns }}" bind:change="onChange" />
  1. const citys = {
  2. 浙江: ['杭州', '宁波', '温州', '嘉兴', '湖州'],
  3. 福建: ['福州', '厦门', '莆田', '三明', '泉州'],
  4. };
  5. Page({
  6. data: {
  7. columns: [
  8. {
  9. values: Object.keys(citys),
  10. className: 'column1',
  11. },
  12. {
  13. values: citys['浙江'],
  14. className: 'column2',
  15. defaultIndex: 2,
  16. },
  17. ],
  18. },
  19. onChange(event) {
  20. const { picker, value, index } = event.detail;
  21. picker.setColumnValues(1, citys[value[0]]);
  22. },
  23. });

禁用选项

选项可以为对象结构,通过设置 disabled 来禁用该选项。

  1. <van-picker columns="{{ columns }}" />
  1. Page({
  2. data: {
  3. columns: [
  4. { text: '杭州', disabled: true },
  5. { text: '宁波' },
  6. { text: '温州' },
  7. ],
  8. },
  9. });

加载状态

当 Picker 数据是通过异步获取时,可以通过 loading 属性显示加载提示。

  1. <van-picker columns="{{ columns }}" loading />

API

Props

参数说明类型默认值版本
columns对象数组,配置每一列显示的数据Array[]-
show-toolbar是否显示顶部栏booleanfalse-
toolbar-position顶部栏位置,可选值为bottomstringtop-
title顶部栏标题string‘’-
loading是否显示加载状态booleanfalse-
value-key选项对象中,文字对应的 keystringtext-
item-height选项高度number44-
confirm-button-text确认按钮文字string确认-
cancel-button-text取消按钮文字string取消-
visible-item-count可见的选项个数number6-
default-index单列选择器的默认选中项索引,
多列选择器请参考下方的 Columns 配置
number0-

Events

Picker 组件的事件会根据 columns 是单列或多列返回不同的参数。

事件名说明参数
confirm点击完成按钮时触发单列:选中值,选中值对应的索引
多列:所有列选中值,所有列选中值对应的索引
cancel点击取消按钮时触发单列:选中值,选中值对应的索引
多列:所有列选中值,所有列选中值对应的索引
change选项改变时触发单列:Picker 实例,选中值,选中值对应的索引
多列:Picker 实例,所有列选中值,当前列对应的索引

Columns 数据结构

当传入多列数据时,columns为一个对象数组,数组中的每一个对象配置每一列,每一列有以下key

key说明
values列中对应的备选值
defaultIndex初始选中项的索引,默认为 0

外部样式类

类名说明
custom-class根节点样式类
active-class选中项样式类
toolbar-class顶部栏样式类
column-class列样式类

方法

通过 selectComponent 可以获取到 picker 实例并调用实例方法。

方法名参数返回值介绍
getValues-values获取所有列选中的值
setValuesvalues-设置所有列选中的值
getIndexes-indexes获取所有列选中值对应的索引
setIndexesindexes-设置所有列选中值对应的索引
getColumnValuecolumnIndexvalue获取对应列选中的值
setColumnValuecolumnIndex, value-设置对应列选中的值
getColumnIndexcolumnIndexoptionIndex获取对应列选中项的索引
setColumnIndexcolumnIndex, optionIndex-设置对应列选中项的索引
getColumnValuescolumnIndexvalues获取对应列中所有选项
setColumnValuescolumnIndex, values-设置对应列中所有选项

Picker 选择器 - 图1