Cascader 级联选择

介绍

级联选择框,用于多层级数据的选择,典型场景为省市区选择。

引入

通过以下方式来全局注册组件,更多注册方式请参考组件注册

  1. import { createApp } from 'vue';
  2. import { Cascader } from 'vant';
  3. const app = createApp();
  4. app.use(Cascader);

代码演示

基础用法

级联选择组件可以搭配 Field 和 Popup 组件使用,示例如下:

  1. <van-field
  2. v-model="fieldValue"
  3. is-link
  4. readonly
  5. label="地区"
  6. placeholder="请选择所在地区"
  7. @click="show = true"
  8. />
  9. <van-popup v-model:show="show" round position="bottom">
  10. <van-cascader
  11. v-model="cascaderValue"
  12. title="请选择所在地区"
  13. :options="options"
  14. @close="show = false"
  15. @finish="onFinish"
  16. />
  17. </van-popup>
  1. import { ref } from 'vue';
  2. export default {
  3. setup() {
  4. const show = ref(false);
  5. const fieldValue = ref('');
  6. const cascaderValue = ref('');
  7. // 选项列表,children 代表子选项,支持多级嵌套
  8. const options = [
  9. {
  10. text: '浙江省',
  11. value: '330000',
  12. children: [{ text: '杭州市', value: '330100' }],
  13. },
  14. {
  15. text: '江苏省',
  16. value: '320000',
  17. children: [{ text: '南京市', value: '320100' }],
  18. },
  19. ];
  20. // 全部选项选择完毕后,会触发 finish 事件
  21. const onFinish = ({ selectedOptions }) => {
  22. show.value = false;
  23. fieldValue.value = selectedOptions.map((option) => option.text).join('/');
  24. };
  25. return {
  26. show,
  27. options,
  28. onFinish,
  29. fieldValue,
  30. cascaderValue,
  31. };
  32. },
  33. };

自定义颜色

通过 active-color 属性来设置选中状态的高亮颜色。

  1. <van-cascader
  2. v-model="cascaderValue"
  3. title="请选择所在地区"
  4. :options="options"
  5. active-color="#1989fa"
  6. @close="show = false"
  7. @finish="onFinish"
  8. />

异步加载选项

可以监听 change 事件并动态设置 options,实现异步加载选项。

  1. <van-field
  2. v-model="fieldValue"
  3. is-link
  4. readonly
  5. label="地区"
  6. placeholder="请选择所在地区"
  7. @click="show = true"
  8. />
  9. <van-popup v-model:show="show" round position="bottom">
  10. <van-cascader
  11. v-model="cascaderValue"
  12. title="请选择所在地区"
  13. :options="options"
  14. @close="show = false"
  15. @change="onChange"
  16. @finish="onFinish"
  17. />
  18. </van-popup>
  1. import { ref } from 'vue';
  2. export default {
  3. setup() {
  4. const show = ref(false);
  5. const fieldValue = ref('');
  6. const cascaderValue = ref('');
  7. const options = ref([
  8. {
  9. text: '浙江省',
  10. value: '330000',
  11. children: [],
  12. },
  13. ]);
  14. const onChange = ({ value }) => {
  15. if (value === options.value[0].value) {
  16. setTimeout(() => {
  17. options.value[0].children = [
  18. { text: '杭州市', value: '330100' },
  19. { text: '宁波市', value: '330200' },
  20. ];
  21. }, 500);
  22. }
  23. };
  24. const onFinish = ({ selectedOptions }) => {
  25. show.value = false;
  26. fieldValue.value = selectedOptions.map((option) => option.text).join('/');
  27. };
  28. return {
  29. show,
  30. options,
  31. onFinish,
  32. fieldValue,
  33. cascaderValue,
  34. };
  35. },
  36. };

自定义字段名

通过 field-names 属性可以自定义 options 里的字段名称。

  1. <van-cascader
  2. v-model="code"
  3. title="请选择所在地区"
  4. :options="options"
  5. :field-names="fieldNames"
  6. />
  1. import { ref } from 'vue';
  2. export default {
  3. setup() {
  4. const code = ref('');
  5. const fieldNames = {
  6. text: 'name',
  7. value: 'code',
  8. children: 'items',
  9. };
  10. const options = [
  11. {
  12. name: '浙江省',
  13. code: '330000',
  14. items: [{ name: '杭州市', code: '330100' }],
  15. },
  16. {
  17. name: '江苏省',
  18. code: '320000',
  19. items: [{ name: '南京市', code: '320100' }],
  20. },
  21. ];
  22. return {
  23. code,
  24. options,
  25. fieldNames,
  26. };
  27. },
  28. };

自定义选项上方内容

  1. <van-cascader v-model="code" title="请选择所在地区" :options="options">
  2. <template #options-top="{ tabIndex }">
  3. <div class="current-level">当前为第 {{ tabIndex }} 级</div>
  4. </template>
  5. </van-cascader>
  6. <style>
  7. .current-level {
  8. padding: 10px 16px 0;
  9. }
  10. </style>
  1. import { ref } from 'vue';
  2. export default {
  3. setup() {
  4. const code = ref('');
  5. const options = [
  6. {
  7. name: '浙江省',
  8. code: '330000',
  9. items: [{ name: '杭州市', code: '330100' }],
  10. },
  11. {
  12. name: '江苏省',
  13. code: '320000',
  14. items: [{ name: '南京市', code: '320100' }],
  15. },
  16. ];
  17. return {
  18. code,
  19. options,
  20. };
  21. },
  22. };

API

Props

参数说明类型默认值
title顶部标题string-
value选中项的值string | number-
options可选项数据源CascaderOption[][]
placeholder未选中时的提示文案string请选择
active-color选中状态的高亮颜色string#ee0a24
swipeable v3.0.11是否开启手势左右滑动切换booleanfalse
closeable是否显示关闭图标booleantrue
show-header v3.4.2是否展示标题栏booleantrue
close-icon v3.0.10关闭图标名称或图片链接,等同于 Icon 组件的 name 属性stringcross
field-names v3.0.4自定义 options 结构中的字段object{ text: ‘text’, value: ‘value’, children: ‘children’ }

CascaderOption 数据结构

options 属性是一个由对象构成的数组,数组中的每个对象配置一个可选项,对象可以包含以下值:

键名说明类型
text选项文字(必填)string
value选项对应的值(必填)string | number
color v3.1.0选项文字颜色string
children子选项列表CascaderOption[]
disabled v3.1.2是否禁用选项boolean
className v3.1.0为对应列添加额外的 classstring | Array | object

Events

事件说明回调参数
change选中项变化时触发{ value: string | number, selectedOptions: CascaderOption[], tabIndex: number }
finish全部选项选择完成后触发{ value: string | number, selectedOptions: CascaderOption[], tabIndex: number }
close点击关闭图标时触发-
click-tab点击标签时触发tabIndex: number, title: string

Slots

名称说明参数
title自定义顶部标题-
option v3.1.4自定义选项文字{ option: CascaderOption, selected: boolean }
options-top v3.2.7自定义选项上方的内容{ tabIndex: number }
options-bottom v3.2.8自定义选项下方的内容{ tabIndex: number }

类型定义

组件导出以下类型定义:

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

主题定制

样式变量

组件提供了下列 CSS 变量,可用于自定义样式,使用方法请参考 ConfigProvider 组件

名称默认值描述
—van-cascader-header-height48px-
—van-cascader-header-padding0 var(—van-padding-md)-
—van-cascader-title-font-sizevar(—van-font-size-lg)-
—van-cascader-title-line-height20px-
—van-cascader-close-icon-size22px-
—van-cascader-close-icon-colorvar(—van-gray-5)-
—van-cascader-selected-icon-size18px-
—van-cascader-tabs-height48px-
—van-cascader-active-colorvar(—van-danger-color)-
—van-cascader-options-height384px-
—van-cascader-option-disabled-colorvar(—van-text-color-3)-
—van-cascader-tab-colorvar(—van-text-color)-
—van-cascader-unselected-tab-colorvar(—van-text-color-2)-

Cascader 级联选择 - 图1