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

ParametersDescriptionTypeDefault value
v-modelThe value of the selected itemstring | number-
titletop titlestring-
optionsOption data sourceCascaderOption[]
placeholderPrompt text when not selectedstringPlease select
active-colorHighlight color of selected statestring#1989fa
swipeableWhether to enable left and right sliding switching with gesturesbooleantrue
closeableWhether to display the close iconbooleantrue
show-headerWhether to display the title barbooleantrue
close-iconClose the icon name or image link, which is equivalent to the name attribute of the Icon componentstringcross
field-namesCustom fields in the options structureCascaderFieldNames{ 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 nameDescriptionType
textoption text (required)string
valueThe value corresponding to the option (required)string | number
coloroption text colorstring
childrenlist of child optionsCascaderOption
disabledWhether to disable the optionboolean
classNameAdd additional class for the corresponding columnstring | Array | object

Events

EventDescriptionCallback Parameters
changeTriggered when the selected item changes{ value: string | number, selectedOptions: CascaderOption, tabIndex: number }
finishTriggered after all options are selected{ value: string | number, selectedOptions: CascaderOption, tabIndex: number }
closeTriggered when the close icon is clicked-
click-tabTriggered when a tab is clickedtabIndex: number, title: string

Slots

NameDescriptionParameters
titleCustom top title-
optionCustom option text{ option: CascaderOption, selected: boolean }
options-topCustomize the content above the options
options-bottomCustomize 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.

NameDefaultDescription
--z-cascader-header-height96rpx-
--z-cascader-header-padding0 var(--z-padding-md)-
--z-cascader-title-font-sizevar(--z-font-size-lg)-
--z-cascader-title-line-height40rpx-
--z-cascader-close-icon-size44rpx-
--z-cascader-close-icon-colorvar(--z-gray-5)-
--z-cascader-selected-icon-size36rpx-
--z-cascader-tabs-height96rpx-
--z-cascader-active-colorvar(--z-danger-color)-
--z-cascader-options-height768rpx-
--z-cascader-option-disabled-colorvar(--z-text-color-3)-
--z-cascader-tab-colorvar(--z-text-color)-
--z-cascader-unselected-tab-colorvar(--z-text-color-2)-