codecamp

Vant3 Cascader 级联选择

介绍

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

实例演示

引入

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

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

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

代码演示

基础用法

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

基础用法

<van-field
  v-model="state.fieldValue"
  is-link
  readonly
  label="地区"
  placeholder="请选择所在地区"
  @click="state.show = true"
/>
<van-popup v-model:show="state.show" round position="bottom">
  <van-cascader
    v-model="state.cascaderValue"
    title="请选择所在地区"
    :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' }],
      },
    ];
    // 全部选项选择完毕后,会触发 finish 事件
    const onFinish = ({ selectedOptions }) => {
      state.show = false;
      state.fieldValue = selectedOptions.map((option) => option.text).join('/');
    };

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

自定义颜色

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

定义颜色

<van-cascader
  v-model="state.cascaderValue"
  title="请选择所在地区"
  :options="options"
  active-color="#1989fa"
  @close="state.show = false"
  @finish="onFinish"
/>

异步加载选项

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

异步加载选项

<van-field
  v-model="state.fieldValue"
  is-link
  readonly
  label="地区"
  placeholder="请选择所在地区"
  @click="state.show = true"
/>
<van-popup v-model:show="state.show" round position="bottom">
  <van-cascader
    v-model="state.cascaderValue"
    title="请选择所在地区"
    :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="请选择所在地区"
  :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

参数 说明 类型 默认值
title 顶部标题 string -
value 选中项的值 string | number -
options 可选项数据源 Option[] []
placeholder 未选中时的提示文案 string 请选择
active-color 选中状态的高亮颜色 string #ee0a24
swipeable v3.0.11 是否开启手势左右滑动切换 boolean false
closeable 是否显示关闭图标 boolean true
close-icon v3.0.10 关闭图标名称或图片链接 string cross
field-names v3.0.4 自定义 options 结构中的字段 object { text: 'text', value: 'value', children: 'children' }

Option 数据结构

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

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

Events

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

Slots

名称 说明 参数
title 自定义顶部标题 -
option v3.1.4 自定义选项文字 { option: Option, selected: boolean }

主题定制

样式变量

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

名称 默认值 描述
--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-close-icon-active-color var(--van-gray-6) -
--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 van(--van-gray-5) -
--van-cascader-tab-color var(--van-text-color) -
--van-cascader-unselected-tab-color var(--van-gray-6) -


Vant3 Calendar日历
Vant3 Checkbox复选框
温馨提示
下载编程狮App,免费阅读超1000+编程语言教程
取消
确定
目录

Vant3 废弃内容

关闭

MIP.setData({ 'pageTheme' : getCookie('pageTheme') || {'day':true, 'night':false}, 'pageFontSize' : getCookie('pageFontSize') || 20 }); MIP.watch('pageTheme', function(newValue){ setCookie('pageTheme', JSON.stringify(newValue)) }); MIP.watch('pageFontSize', function(newValue){ setCookie('pageFontSize', newValue) }); function setCookie(name, value){ var days = 1; var exp = new Date(); exp.setTime(exp.getTime() + days*24*60*60*1000); document.cookie = name + '=' + value + ';expires=' + exp.toUTCString(); } function getCookie(name){ var reg = new RegExp('(^| )' + name + '=([^;]*)(;|$)'); return document.cookie.match(reg) ? JSON.parse(document.cookie.match(reg)[2]) : null; }