vant/packages/picker/zh-CN.md

Picker 选择器

选择器组件通常与 弹出层 组件配合使用

使用指南

import { Picker } from 'vant';

Vue.use(Picker);

代码演示

基础用法

<van-picker :columns="columns" @change="onChange" />

export default {
  data() {
    return {
      columns: ['杭州', '宁波', '温州', '嘉兴', '湖州']
    };
  },
  methods: {
    onChange(picker, value, index) {
      Toast(`当前值：${value}, 当前索引：${index}`);
    }
  }
};

禁用选项

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

<van-picker :columns="columns" />

export default {
  data() {
    return {
      columns: [
        { text: '杭州', disabled: true },
        { text: '宁波' },
        { text: '温州' }
      ]
    };
  }
};

展示顶部栏

<van-picker
  show-toolbar
  title="标题"
  :columns="columns"
  @cancel="onCancel"
  @confirm="onConfirm"
/>

export default {
  data() {
    return {
      columns: ['杭州', '宁波', '温州', '嘉兴', '湖州']
    }
  },
  methods: {
    onConfirm(value, index) {
      Toast(`当前值：${value}, 当前索引：${index}`);
    },
    onCancel() {
      Toast('取消');
    }
  }
};

多列联动

<van-picker :columns="columns" @change="onChange" />

const citys = {
  '浙江': ['杭州', '宁波', '温州', '嘉兴', '湖州'],
  '福建': ['福州', '厦门', '莆田', '三明', '泉州']
};

export default {
  data() {
    return {
      columns: [
        {
          values: Object.keys(citys),
          className: 'column1'
        },
        {
          values: citys['浙江'],
          className: 'column2',
          defaultIndex: 2
        }
      ]
    };
  },
  methods: {
    onChange(picker, values) {
      picker.setColumnValues(1, citys[values[0]]);
    }
  }
};

加载状态

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

<van-picker :columns="columns" loading />

API

参数	说明	类型	默认值
columns	对象数组，配置每一列显示的数据	Array	[]
show-toolbar	是否显示顶部栏	Boolean	false
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	5

Event

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

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

Columns 数据结构

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

key	说明
values	列中对应的备选值
defaultIndex	初始选中项的索引，默认为 0
className	为对应列添加额外的class

方法

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

方法名	参数	返回值	介绍
getValues	-	values	获取所有列选中的值
setValues	values	-	设置所有列选中的值
getIndexes	-	indexes	获取所有列选中值对应的索引
setIndexes	indexes	-	设置所有列选中值对应的索引
getColumnValue	columnIndex	value	获取对应列选中的值
setColumnValue	columnIndex, value	-	设置对应列选中的值
getColumnIndex	columnIndex	optionIndex	获取对应列选中项的索引
setColumnIndex	columnIndex, optionIndex	-	设置对应列选中项的索引
getColumnValues	columnIndex	values	获取对应列中所有选项
setColumnValue	columnIndex, values	-	设置对应列中所有选项

更新日志

版本	类型	内容
1.1.13	bugfix	修复部分安卓机型下选项高度错误的问题
1.1.11	improvement	优化渲染性能
1.1.6	feature	支持 html 类型的选项
1.1.5	improvement	优化未选中项的颜色
1.1.0	bugfix	修复系统字体大小缩放时布局错乱的问题
1.0.4	feature	支持 Picker 组件所有属性
0.12.9	feature	新增 loading 属性
0.12.8	bugfix	修复部分设备下的样式问题
0.12.4	feature	新增 confirm-text、cancel-button-text 属性
0.12.4	bugfix	修复 visible-item-count 属性拼写错误
0.12.3	bugfix	修复点击选项时无法触发 change 事件的问题
0.12.2	bugfix	修复 change 事件触发时机
0.11.13	improvement	优化性能
0.11.12	bugfix	修复滑动时未禁止页面滚动的问题
0.11.12	bugfix	修复底部区域无法滑动的问题
0.11.6	feature	支持点击切换选项、禁用选项
0.5.8	feature	新增 title 属性