Cascader cascade selection

introduce

Cascading selection boxes are used for selecting multi-level data. Typical scenarios are province and city selection.

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,
     };
   },
};

Props

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:

Events

Slots

Style variables

The component provides the following CSS variables, which can be used to customize styles. For usage, please refer to ConfigProvider component.