Vant Picker Selector

Introduced

Multiple sets of options are available for users to choose from, supporting single-column selection and multi-column cascading, typically in conjunction with pop-up layer components

Introduced

import Vue from 'vue';
import { Picker } from 'vant';

Vue.use(Picker);

Code demo

Basic usage

The Picker component configures option data through the columns property, and columns is an array that contains strings or objects

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

import { Toast } from 'vant';

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

The default selection

When a single column is selected, the index of the initial selection can be set by the default-index property

<van-picker :columns="columns" :default-index="2" />

Show the top bar

When you set the show-toolbar property, the top action bar is displayed, the confirm event is triggered by clicking the confirmation button, and the cancel event is triggered by clicking the cancel button

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

import { Toast } from 'vant';

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

Multi-column selection

The columns property allows you to configure multiple column selections

<van-picker show-toolbar title="标题" :columns="columns" />

export default {
  data() {
    return {
      columns: [
        // 第一列
        {
          values: ['周一', '周二', '周三', '周四', '周五'],
          defaultIndex: 2
        },
        // 第二列
        {
          values: ['上午', '下午', '晚上'],
          defaultIndex: 1
        }
      ]
    };
  }
};

Cascading selection

Use the children field of columns to achieve the effect of option cascading (supported from version 2.4.5)

<van-picker show-toolbar title="标题" :columns="columns" />

export default {
  data() {
    return {
      columns: [{
        text: '浙江',
        children: [{
          text: '杭州',
          children: [{ text: '西湖区' }, { text: '余杭区' }]
        }, {
          text: '温州',
          children: [{ text: '鹿城区' }, { text: '瓯海区' }]
        }]
      }, {
        text: '福建',
        children: [{
          text: '福州',
          children: [{ text: '鼓楼区' }, { text: '台江区' }]
        }, {
          text: '厦门',
          children: [{ text: '思明区' }, { text: '海沧区' }]
        }]
      }]
    };
  }
};

Disable the option

The option can be an object structure and is disabled by setting the disabled

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

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

Dynamically set options

The instance method on picker gives you more flexibility to control the selectors, for example by using the setColumnValues method for multi-column linkage

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

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

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

The load status

If the selector data is obtained asynchronously, the load prompt can be displayed through the loading property

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

export default {
  data() {
    return {
      columns: [],
      loading: true
    };
  },
  created() {
    setTimeout(() => {
      this.loading = false;
      this.columns = ['选项'];
    }, 1000);
  }
};

Use with a pop-up layer

In a real-world scenario, Picker is typically used as a secondary form to fill out, which can be achieved with Popup and Field

<van-field
  readonly
  clickable
  label="城市"
  :value="value"
  placeholder="选择城市"
  @click="showPicker = true"
/>
<van-popup v-model="showPicker" position="bottom">
  <van-picker
    show-toolbar
    :columns="columns"
    @cancel="showPicker = false"
    @confirm="onConfirm"
  />
</van-popup>

export default {
  data() {
    return {
      value: '',
      showPicker: false,
      columns: ['杭州', '宁波', '温州', '嘉兴', '湖州']
    }
  },
  methods: {
    onConfirm(value) {
      this.value = value;
      this.showPicker = false;
    }
  }
};

Api

Props

Parameters	Description	Type	The default
columns	An array of objects, configuring the data displayed in each column	Column[]	[]
title	The title of the top bar	string	-
confirm-button-text	Confirm the button text	string	确认
cancel-button-text	Cancel the button text	string	取消
value-key	In the option object, the key name for the option text	string	text
toolbar-position	The top bar position, with an optional value of bottom	string	top
loading	Whether to display the load status	boolean	false
show-toolbar	Whether to display the top bar	boolean	false
allow-html v2.1.8	Whether to allow HTML to be rendered in the content of the option	boolean	true
default-index	When a single column is selected, the index of the item is selected by default	number | string	0
item-height	The height of the option	number | string	44
visible-item-count	The number of visible options	number | string	5
swipe-duration v2.2.10	The length of inertial scrolling when sliding quickly, in ms	number | string	1000

Events

When the selector has more than one column, the event callback parameter returns an array

The name of the event	Description	Callback parameters
confirm	Triggered when the finish button is clicked	Single column: Select the value, select the index corresponding to the value Multiple columns: All columns select values, all columns select the index corresponding to the values
cancel	Triggered when the cancel button is clicked	Single column: Select the value, select the index corresponding to the value Multiple columns: All columns select values, all columns select the index corresponding to the values
change	Triggered when the option changes	Single column: Picker instance, check value, check index corresponding to value Multiple columns: Picker instance, all column-selected values, index for the current column

Slots

Name	Description
default	Customize the top bar content
title	Customize the title content
columns-top	What's above the custom options
columns-bottom	What's below the custom options

Column data structure

When multiple columns of data are passed in, columns are an array of objects, each of which is configured with each column, each with the following key

The key name	Description	Type
values	The alternative value in the column	string[]
defaultIndex	The index of the initially selected item, which defaults to 0	number
className	Add additional class names to the corresponding columns	any
children v2.4.5	Cascading options	Column

Method

Ref allows you to get to the Picker instance and call the instance method, as detailed in the component instance method

The method name	Description	Parameters	Returns a value
getValues	Gets the values selected for all columns	-	values
setValues	Set the values selected for all columns	values	-
getIndexes	Gets the index for all column-selected values	-	indexes
setIndexes	Set the index for all column-selected values	indexes	-
getColumnValue	Gets the value selected for the corresponding column	columnIndex	value
setColumnValue	Set the value selected for the corresponding column	columnIndex, value	-
getColumnIndex	Gets an index of the selected items for the corresponding column	columnIndex	optionIndex
setColumnIndex	Set the index for the selected items for the corresponding column	columnIndex, optionIndex	-
getColumnValues	Gets all the options in the corresponding column	columnIndex	values
setColumnValues	Set all the options in the corresponding column	columnIndex, values	-
confirm v2.4.0	Stop inertial scrolling and trigger the confirm event	-	-

Problems

Can't operate components on the desktop side?

See Use on the desktop side.