Vant3 Cascader 級聯(lián)選擇

介紹

級聯(lián)選擇框，用于多層級數(shù)據(jù)的選擇，典型場景為省市區(qū)選擇。

實例演示

引入

通過以下方式來全局注冊組件，更多注冊方式請參考組件注冊。

import { createApp } from 'vue';
import { Cascader } from 'vant';

const app = createApp();
app.use(Cascader);

代碼演示

基礎(chǔ)用法

級聯(lián)選擇組件可以搭配 Field 和 Popup 組件使用，示例如下：

<van-field
  v-model="state.fieldValue"
  is-link
  readonly
  label="地區(qū)"
  placeholder="請選擇所在地區(qū)"
  @click="state.show = true"
/>
<van-popup v-model:show="state.show" round position="bottom">
  <van-cascader
    v-model="state.cascaderValue"
    title="請選擇所在地區(qū)"
    :options="options"
    @close="state.show = false"
    @finish="onFinish"
  />
</van-popup>

import { reactive } from 'vue';

export default {
  setup() {
    const state = reactive({
      show: false,
      fieldValue: '',
      cascaderValue: '',
    });
    // 選項列表，children 代表子選項，支持多級嵌套
    const options = [
      {
        text: '浙江省',
        value: '330000',
        children: [{ text: '杭州市', value: '330100' }],
      },
      {
        text: '江蘇省',
        value: '320000',
        children: [{ text: '南京市', value: '320100' }],
      },
    ];
    // 全部選項選擇完畢后，會觸發(fā) finish 事件
    const onFinish = ({ selectedOptions }) => {
      state.show = false;
      state.fieldValue = selectedOptions.map((option) => option.text).join('/');
    };

    return {
      state,
      options,
      onFinish,
    };
  },
};

自定義顏色

通過 active-color 屬性來設(shè)置選中狀態(tài)的高亮顏色。

<van-cascader
  v-model="state.cascaderValue"
  title="請選擇所在地區(qū)"
  :options="options"
  active-color="#1989fa"
  @close="state.show = false"
  @finish="onFinish"
/>

異步加載選項

可以監(jiān)聽 change 事件并動態(tài)設(shè)置 options，實現(xiàn)異步加載選項。

<van-field
  v-model="state.fieldValue"
  is-link
  readonly
  label="地區(qū)"
  placeholder="請選擇所在地區(qū)"
  @click="state.show = true"
/>
<van-popup v-model:show="state.show" round position="bottom">
  <van-cascader
    v-model="state.cascaderValue"
    title="請選擇所在地區(qū)"
    :options="state.options"
    @close="state.show = false"
    @change="onChange"
    @finish="onFinish"
  />
</van-popup>

import { reactive } from 'vue';

export default {
  setup() {
    const state = reactive({
      show: false,
      fieldValue: '',
      cascaderValue: '',
      options: [
        {
          text: '浙江省',
          value: '330000',
          children: [],
        },
      ],
    });
    const onChange = ({ value }) => {
      if (value === state.options[0].value) {
        setTimeout(() => {
          state.options[0].children = [
            { text: '杭州市', value: '330100' },
            { text: '寧波市', value: '330200' },
          ];
        }, 500);
      }
    };
    const onFinish = ({ selectedOptions }) => {
      state.show = false;
      state.fieldValue = selectedOptions.map((option) => option.text).join('/');
    };

    return {
      state,
      onChange,
      onFinish,
    };
  },
};

自定義字段名

通過 field-names 屬性可以自定義 options 里的字段名稱。

<van-cascader
  v-model="code"
  title="請選擇所在地區(qū)"
  :options="options"
  :field-names="fieldNames"
/>

import { ref } from 'vue';

export default {
  setup() {
    const code = ref('');
    const fieldNames = {
      text: 'name',
      value: 'code',
      children: 'items',
    };
    const options = [
      {
        name: '浙江省',
        code: '330000',
        items: [{ name: '杭州市', code: '330100' }],
      },
      {
        name: '江蘇省',
        code: '320000',
        items: [{ name: '南京市', code: '320100' }],
      },
    ];

    return {
      code,
      options,
      fieldNames,
    };
  },
};

API

Props

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

options 屬性是一個由對象構(gòu)成的數(shù)組，數(shù)組中的每個對象配置一個可選項，對象可以包含以下值：

Events

Slots

主題定制

樣式變量

組件提供了下列 CSS 變量，可用于自定義樣式，使用方法請參考 ConfigProvider 組件。