引入

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

Vue.use(Picker);

基礎(chǔ)用法

選項(xiàng)配置

Picker 組件通過 columns 屬性配置選項(xiàng)數(shù)據(jù)，columns 是一個(gè)包含字符串或?qū)ο蟮臄?shù)組。

頂部欄

設(shè)置 show-toolbar 屬性后會(huì)展示頂部操作欄，頂部欄包含標(biāo)題、確認(rèn)按鈕和取消按鈕，點(diǎn)擊確認(rèn)按鈕觸發(fā) confirm 事件，點(diǎn)擊取消按鈕觸發(fā) cancel 事件。

<van-picker
  title="標(biāo)題"
  show-toolbar
  :columns="columns"
  @confirm="onConfirm"
  @cancel="onCancel"
  @change="onChange"
/>

import { Toast } from 'vant';

export default {
  data() {
    return {
      columns: ['杭州', '寧波', '溫州', '紹興', '湖州', '嘉興', '金華', '衢州'],
    };
  },
  methods: {
    onConfirm(value, index) {
      Toast(`當(dāng)前值：${value}, 當(dāng)前索引：${index}`);
    },
    onChange(picker, value, index) {
      Toast(`當(dāng)前值：${value}, 當(dāng)前索引：${index}`);
    },
    onCancel() {
      Toast('取消');
    },
  },
};

默認(rèn)選中項(xiàng)

單列選擇時(shí)，可以通過 default-index 屬性設(shè)置初始選中項(xiàng)的索引。

<van-picker show-toolbar title="標(biāo)題" :columns="columns" :default-index="2" />

多列選擇

columns 屬性可以通過對(duì)象數(shù)組的形式配置多列選擇，對(duì)象中可以配置選項(xiàng)數(shù)據(jù)、初始選中項(xiàng)等，詳細(xì)格式見下方表格。

<van-picker show-toolbar title="標(biāo)題" :columns="columns" />

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

級(jí)聯(lián)選擇

使用 columns 的 children 字段可以實(shí)現(xiàn)選項(xiàng)級(jí)聯(lián)的效果（從 2.4.5 版本開始支持）。

<van-picker show-toolbar title="標(biāo)題" :columns="columns" />

export default {
  data() {
    return {
      columns: [
        {
          text: '浙江',
          children: [
            {
              text: '杭州',
              children: [{ text: '西湖區(qū)' }, { text: '余杭區(qū)' }],
            },
            {
              text: '溫州',
              children: [{ text: '鹿城區(qū)' }, { text: '甌海區(qū)' }],
            },
          ],
        },
        {
          text: '福建',
          children: [
            {
              text: '福州',
              children: [{ text: '鼓樓區(qū)' }, { text: '臺(tái)江區(qū)' }],
            },
            {
              text: '廈門',
              children: [{ text: '思明區(qū)' }, { text: '海滄區(qū)' }],
            },
          ],
        },
      ],
    };
  },
};

級(jí)聯(lián)選擇的數(shù)據(jù)嵌套深度需要保持一致，如果部分選項(xiàng)沒有子選項(xiàng)，可以使用空字符串進(jìn)行占位

禁用選項(xiàng)

選項(xiàng)可以為對(duì)象結(jié)構(gòu)，通過設(shè)置 disabled 來禁用該選項(xiàng)。

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

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

動(dòng)態(tài)設(shè)置選項(xiàng)

通過 Picker 上的實(shí)例方法可以更靈活地控制選擇器，比如使用 setColumnValues 方法實(shí)現(xiàn)多列聯(lián)動(dòng)。

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

const cities = {
  浙江: ['杭州', '寧波', '溫州', '嘉興', '湖州'],
  福建: ['福州', '廈門', '莆田', '三明', '泉州'],
};

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

加載狀態(tài)

若選擇器數(shù)據(jù)是異步獲取的，可以通過 loading 屬性顯示加載提示。

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

export default {
  data() {
    return {
      columns: [],
      loading: true,
    };
  },
  created() {
    setTimeout(() => {
      this.loading = false;
      this.columns = ['選項(xiàng)'];
    }, 1000);
  },
};

搭配彈出層使用

在實(shí)際場(chǎng)景中，Picker 通常作為用于輔助表單填寫，可以搭配 Popup 和 Field 實(shí)現(xiàn)該效果。

<van-field
  readonly
  clickable
  label="城市"
  :value="value"
  placeholder="選擇城市"
  @click="showPicker = true"
/>
<van-popup v-model="showPicker" round 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;
    },
  },
};

Props

Events

當(dāng)選擇器有多列時(shí)，事件回調(diào)參數(shù)會(huì)返回?cái)?shù)組

Slots

Column 數(shù)據(jù)結(jié)構(gòu)

當(dāng)傳入多列數(shù)據(jù)時(shí)，columns 為一個(gè)對(duì)象數(shù)組，數(shù)組中的每一個(gè)對(duì)象配置每一列，每一列有以下 key:

方法

通過 ref 可以獲取到 Picker 實(shí)例并調(diào)用實(shí)例方法，詳見組件實(shí)例方法。

樣式變量

組件提供了下列 Less 變量，可用于自定義樣式，使用方法請(qǐng)參考主題定制。

在桌面端無法操作組件？

參見桌面端適配。