Vant4 Cascader 級聯(lián)選擇

2023-02-16 17:54 更新

介紹

級聯(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="fieldValue"
  is-link
  readonly
  label="地區(qū)"
  placeholder="請選擇所在地區(qū)"
  @click="show = true"
/>
<van-popup v-model:show="show" round position="bottom">
  <van-cascader
    v-model="cascaderValue"
    title="請選擇所在地區(qū)"
    :options="options"
    @close="show = false"
    @finish="onFinish"
  />
</van-popup>
import { ref } from 'vue';

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

    return {
      show,
      options,
      onFinish,
      fieldValue,
      cascaderValue,
    };
  },
};

自定義顏色

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

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

異步加載選項

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

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

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

    return {
      show,
      options,
      onFinish,
      fieldValue,
      cascaderValue,
    };
  },
};

自定義字段名

通過 ?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,
    };
  },
};

自定義選項上方內(nèi)容

<van-cascader v-model="code" title="請選擇所在地區(qū)" :options="options">
  <template #options-top="{ tabIndex }">
    <div class="current-level">當(dāng)前為第 {{ tabIndex }} 級</div>
  </template>
</van-cascader>

<style>
  .current-level {
    padding: 10px 16px 0;
  }
</style>
import { ref } from 'vue';

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

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

API

Props

參數(shù) 說明 類型 默認(rèn)值
title 頂部標(biāo)題 string -
value 選中項的值 string | number -
options 可選項數(shù)據(jù)源 CascaderOption[] []
placeholder 未選中時的提示文案 string 請選擇
active-color 選中狀態(tài)的高亮顏色 string #1989fa
swipeable v3.0.11 是否開啟手勢左右滑動切換 boolean false
closeable 是否顯示關(guān)閉圖標(biāo) boolean true
show-header v3.4.2 是否展示標(biāo)題欄 boolean true
close-icon v3.0.10 關(guān)閉圖標(biāo)名稱或圖片鏈接,等同于 Icon 組件的 name 屬性 string cross
field-names v3.0.4 自定義 options 結(jié)構(gòu)中的字段 CascaderFieldNames { text: 'text', value: 'value', children: 'children' }

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

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

鍵名 說明 類型
text 選項文字(必填) string
value 選項對應(yīng)的值(必填) string | number
color v3.1.0 選項文字顏色 string
children 子選項列表 CascaderOption[]
disabled v3.1.2 是否禁用選項 boolean
className v3.1.0 為對應(yīng)列添加額外的 class string | Array | object

Events

事件 說明 回調(diào)參數(shù)
change 選中項變化時觸發(fā) { value: string | number, selectedOptions: CascaderOption[], tabIndex: number }
finish 全部選項選擇完成后觸發(fā) { value: string | number, selectedOptions: CascaderOption[], tabIndex: number }
close 點擊關(guān)閉圖標(biāo)時觸發(fā) -
click-tab 點擊標(biāo)簽時觸發(fā) tabIndex: number, title: string

Slots

名稱 說明 參數(shù)
title 自定義頂部標(biāo)題 -
option v3.1.4 自定義選項文字 { option: CascaderOption, selected: boolean }
options-top v3.2.7 自定義選項上方的內(nèi)容 { tabIndex: number }
options-bottom v3.2.8 自定義選項下方的內(nèi)容 { tabIndex: number }

類型定義

組件導(dǎo)出以下類型定義:

import type { CascaderProps, CascaderOption, CascaderFieldNames } from 'vant';

主題定制

樣式變量

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

名稱 默認(rèn)值 描述
--van-cascader-header-height 48px -
--van-cascader-header-padding 0 var(--van-padding-md) -
--van-cascader-title-font-size var(--van-font-size-lg) -
--van-cascader-title-line-height 20px -
--van-cascader-close-icon-size 22px -
--van-cascader-close-icon-color var(--van-gray-5) -
--van-cascader-selected-icon-size 18px -
--van-cascader-tabs-height 48px -
--van-cascader-active-color var(--van-danger-color) -
--van-cascader-options-height 384px -
--van-cascader-option-disabled-color var(--van-text-color-3) -
--van-cascader-tab-color var(--van-text-color) -
--van-cascader-unselected-tab-color var(--van-text-color-2) -


以上內(nèi)容是否對您有幫助:
在線筆記
App下載
App下載

掃描二維碼

下載編程獅App

公眾號
微信公眾號

編程獅公眾號