Cascader cascade selection
introduce
Cascading selection boxes are used for selecting multi-level data. Typical scenarios are province and city selection.
Code Demo
Basic usage
The cascading selection component can be used with Field and Popup components. Examples are as follows:
<z-field
v-model="fieldValue"
is-link
readonly
label="region"
placeholder="Please select your region"
@click="show = true"
/>
<z-popup v-model:show="show" round position="bottom">
<z-cascader
v-model="cascaderValue"
title="Please select your region"
:options="options"
@close="show = false"
@finish="onFinish"
/>
</z-popup>
import { ref } from 'vue';
export default {
setup() {
const show = ref(false);
const fieldValue = ref('');
const cascaderValue = ref('');
//Option list, children represents sub-options, supports multi-level nesting
const options = [
{
text: 'Zhejiang Province',
value: '330000',
children: [{ text: 'Hangzhou City', value: '330100' }],
},
{
text: 'Jiangsu Province',
value: '320000',
children: [{ text: 'Nanjing City', value: '320100' }],
},
];
//After all options are selected, the finish event will be triggered
const onFinish = ({ selectedOptions }) => {
show.value = false;
fieldValue.value = selectedOptions.map((option) => option.text).join('/');
};
return {
show,
options,
onFinish,
fieldValue,
cascaderValue,
};
},
};
China province and city data
The Cascader component is often used to select provinces and municipalities. The example project of zebra
provides a Chinese province and municipality data, which can be downloaded and introduced into your own project:
<z-field
v-model="fieldValue"
is-link
readonly
label="region"
placeholder="Please select your region"
@click="show = true"
/>
<z-popup v-model:show="show" round position="bottom">
<z-cascader
v-model="cascaderValue"
title="Please select your region"
:options="options"
@close="show = false"
@finish="onFinish"
/>
</z-popup>
import { ref } from 'vue';
import { useCascaderAreaData } from '../../common/js/area'
export default {
setup() {
const show = ref(false);
const fieldValue = ref('');
const cascaderValue = ref('');
const options = useCascaderAreaData();
const onFinish = ({ selectedOptions }) => {
show.value = false;
fieldValue.value = selectedOptions.map((option) => option.text).join('/');
};
return {
show,
options,
onFinish,
fieldValue,
cascaderValue,
};
},
};
Custom color
Use the active-color
property to set the highlight color of the selected state.
<z-cascader
v-model="cascaderValue"
title="Please select your region"
:options="options"
active-color="#ee0a24"
@close="show = false"
@finish="onFinish"
/>
Asynchronous loading options
You can listen to the change
event and set options
dynamically to implement asynchronous loading of options.
<z-field
v-model="fieldValue"
is-link
readonly
label="region"
placeholder="Please select your region"
@click="show = true"
/>
<z-popup v-model:show="show" round position="bottom">
<z-cascader
v-model="cascaderValue"
title="Please select your region"
:options="options"
@close="show = false"
@change="onChange"
@finish="onFinish"
/>
</z-popup>
import { ref } from 'vue';
import { useToast } from '../../uni_modules/zebra-ui'
export default {
setup() {
const toast = useToast()
const show = ref(false);
const fieldValue = ref('');
const cascaderValue = ref('');
const options = ref([
{
text: 'Zhejiang Province',
value: '330000',
children: [],
},
]);
const onChange = ({ value }) => {
if (
value === options.value[0].value &&
options.value[0].children.length === 0
) {
// Simulate data request
toast.showLoadingToast('Loading...');
setTimeout(() => {
options.value[0].children = [
{ text: 'Hangzhou City', value: '330100' },
{ text: 'Ningbo City', value: '330200' },
];
toast.closeToast();
}, 1000);
}
};
const onFinish = ({ selectedOptions }) => {
show.value = false;
fieldValue.value = selectedOptions.map((option) => option.text).join('/');
};
return {
show,
options,
onFinish,
fieldValue,
cascaderValue,
};
},
};
Custom field name
The field names in options
can be customized through the field-names
attribute.
<z-cascader
v-model="code"
title="Please select your region"
: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: 'Zhejiang Province',
code: '330000',
items: [{ name: 'Hangzhou City', code: '330100' }],
},
{
name: 'Jiangsu Province',
code: '320000',
items: [{ name: 'Nanjing City', code: '320100' }],
},
];
return {
code,
options,
fieldNames,
};
},
};
Customize the content above the options
<z-cascader v-model="code" title="Please select your region" :options="options">
<template #options-top="{ tabIndex }">
<div class="current-level">The current level is {{ tabIndex + 1 }}</div>
</template>
</z-cascader>
<style>
.demo-cascader {
.current-level {
padding: 32rpx 32rpx 0;
font-size: 28rpx;
color: var(--z-gray-6);
}
}
</style>
import { ref } from 'vue';
export default {
setup() {
const code = ref('');
const options = [
{
name: 'Zhejiang Province',
code: '330000',
items: [{ name: 'Hangzhou City', code: '330100' }],
},
{
name: 'Jiangsu Province',
code: '320000',
items: [{ name: 'Nanjing City', code: '320100' }],
},
];
return {
code,
options,
};
},
};
API
Props
Parameters | Description | Type | Default value |
---|---|---|---|
v-model | The value of the selected item | string | number | - |
title | top title | string | - |
options | Option data source | CascaderOption | [] |
placeholder | Prompt text when not selected | string | Please select |
active-color | Highlight color of selected state | string | #1989fa |
swipeable | Whether to enable left and right sliding switching with gestures | boolean | true |
closeable | Whether to display the close icon | boolean | true |
show-header | Whether to display the title bar | boolean | true |
close-icon | Close the icon name or image link, which is equivalent to the name attribute of the Icon component | string | cross |
field-names | Custom fields in the options structure | CascaderFieldNames | { text: 'text', value: 'value', children: 'children' } |
CascaderOption data structure
The options
property is an array of objects. Each object in the array is configured with an option. The object can contain the following values:
Key name | Description | Type |
---|---|---|
text | option text (required) | string |
value | The value corresponding to the option (required) | string | number |
color | option text color | string |
children | list of child options | CascaderOption |
disabled | Whether to disable the option | boolean |
className | Add additional class for the corresponding column | string | Array | object |
Events
Event | Description | Callback Parameters |
---|---|---|
change | Triggered when the selected item changes | { value: string | number, selectedOptions: CascaderOption, tabIndex: number } |
finish | Triggered after all options are selected | { value: string | number, selectedOptions: CascaderOption, tabIndex: number } |
close | Triggered when the close icon is clicked | - |
click-tab | Triggered when a tab is clicked | tabIndex: number, title: string |
Slots
Name | Description | Parameters |
---|---|---|
title | Custom top title | - |
option | Custom option text | { option: CascaderOption, selected: boolean } |
options-top | Customize the content above the options | |
options-bottom | Customize the content below the options |
Theme customization
Style variables
The component provides the following CSS variables, which can be used to customize styles. For usage, please refer to ConfigProvider component.
Name | Default | Description |
---|---|---|
--z-cascader-header-height | 96rpx | - |
--z-cascader-header-padding | 0 var(--z-padding-md) | - |
--z-cascader-title-font-size | var(--z-font-size-lg) | - |
--z-cascader-title-line-height | 40rpx | - |
--z-cascader-close-icon-size | 44rpx | - |
--z-cascader-close-icon-color | var(--z-gray-5) | - |
--z-cascader-selected-icon-size | 36rpx | - |
--z-cascader-tabs-height | 96rpx | - |
--z-cascader-active-color | var(--z-danger-color) | - |
--z-cascader-options-height | 768rpx | - |
--z-cascader-option-disabled-color | var(--z-text-color-3) | - |
--z-cascader-tab-color | var(--z-text-color) | - |
--z-cascader-unselected-tab-color | var(--z-text-color-2) | - |