级联选择框,用于多层级数据的选择,典型场景为省市区选择。
通过以下方式来全局注册组件,更多注册方式请参考组件注册。
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,
};
},
};
参数 | 说明 | 类型 | 默认值 |
---|---|---|---|
title | 顶部标题 | string | - |
value | 选中项的值 | string | number | - |
options | 可选项数据源 | Option[] |
|
placeholder | 未选中时的提示文案 | string |
|
active-color | 选中状态的高亮颜色 | string |
|
swipeable | 是否开启手势左右滑动切换 | boolean |
|
closeable | 是否显示关闭图标 | boolean |
|
close-icon | 关闭图标名称或图片链接 | string |
|
field-names | 自定义 options 结构中的字段 | object |
|
options 属性是一个由对象构成的数组,数组中的每个对象配置一个可选项,对象可以包含以下值:
键名 | 说明 | 类型 |
---|---|---|
text | 选项文字(必填) | string |
value | 选项对应的值(必填) | string | number |
color | 选项文字颜色 | string |
children | 子选项列表 | Option[] |
disabled | 是否禁用选项 | boolean |
className | 为对应列添加额外的 class | string | Array | object |
事件 | 说明 | 回调参数 |
---|---|---|
change | 选中项变化时触发 |
|
finish | 全部选项选择完成后触发 |
|
close | 点击关闭图标时触发 | - |
click-tab | 点击标签时触发 | tabIndex: number, title: string |
名称 | 说明 | 参数 |
---|---|---|
title | 自定义顶部标题 | - |
option | 自定义选项文字 | { 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) | - |