Cascader 级联选择

介绍

级联选择器，一般用于有层级关系的选择，如省市区选择、商品分类选择等。

导入

import Cascader from '@/components/form/Cascader.vue'
import CascaderField from '@/components/form/CascaderField.vue'

用法

基础用法

级联选择器提供了两种使用方式：Cascader 组件用于直接展示，CascaderField 组件结合了弹出层，更适合表单场景。

<template>
  <Field label="选择" showRightArrow>
    <CascaderField v-model="value" :data="data" placeholder="请选择选项" />
  </Field>
</template>

<script setup>
import { ref } from 'vue';
import CascaderField from '@/components/form/CascaderField.vue';
import Field from '@/components/form/Field.vue';
import type { CascaderItem } from '@/components/form/Cascader.vue';

const value = ref([]);
const data : CascaderItem[] = [
  {
    text: '电子产品',
    value: '1',
    children: [
      {
        text: '电脑设备',
        value: '11',
        children: [
          {
            text: '笔记本电脑',
            value: '111',
            children: [
              { text: '轻薄本', value: '1111' },
              { text: '游戏本', value: '1112' }
            ]
          }
        ]
      }
    ]
  }
];
</script>

中国省市区数据

通过自定义键名配置，可以适配中国省市区数据格式。

<template>
  <Field label="选择" showRightArrow>
    <CascaderField 
      v-model="value"
      :data="ChinaCityData"
      textKey="name"
      valueKey="code"
      childrenKey="children"
      placeholder="请选择省市区" 
    />
  </Field>
</template>

<script setup>
import { ref } from 'vue';
import CascaderField from '@/components/form/CascaderField.vue';
import Field from '@/components/form/Field.vue';
import ChinaCityData from '@/components/data/ChinaCityData.json';

const value = ref([]);
</script>

异步加载数据

对于层级较深的数据，可以使用异步加载功能，避免一次性加载过多数据。

<template>
  <Field label="选择" showRightArrow>
    <CascaderField 
      v-model="value"
      :data="data"
      :asyncLoadData="asyncLoadData"
      :maxSelectLevel="4"
      placeholder="请选择选项" 
    />
  </Field>
</template>

<script setup>
import { ref } from 'vue';
import CascaderField from '@/components/form/CascaderField.vue';
import Field from '@/components/form/Field.vue';
import type { CascaderItem } from '@/components/form/Cascader.vue';
import { waitTimeOut } from '@imengyu/imengyu-utils';

const value = ref([]);
const data : CascaderItem[] = [
  {
    text: '异步加载1',
    value: '1',
  },
  {
    text: '异步加载2',
    value: '2',
  },
];

async function asyncLoadData(item: CascaderItem, level: number) {
  // 模拟异步加载
  await waitTimeOut(1000);
  
  // 实际数据可从后端获取
  return [
    {
      text: '第' + level + '级1',
      value: item.value + '1',
    },
    {
      text: '第' + level + '级2',
      value: item.value + '2',
    },
  ];
}
</script>

API 参考

Cascader

级联选择器组件的核心部分，用于展示层级选择界面。

Props

名称	说明	类型	必填	默认值
modelValue	选中的值	`(number	string)[]`	是
data	数据源	CascaderItem[]	是	-
autoConfirm	是否在选择完成后直接关闭	boolean	-	true
listHeight	列表的高度（rpx）	number|string	-	700
textKey	选项的文本键名	string	-	'text'
valueKey	选项的值键名	string	-	'value'
childrenKey	选项的子选项键名	string	-	'children'
tabProps	Tab组件的自定义选项	Omit<TabsProps, 'tabs' | 'currentIndex'>	-	{ width: 750 - 70 }
asyncLoadData	异步加载数据函数	(group: CascaderItem, level: number) => Promise<CascaderItem[]>	-	-
maxSelectLevel	最大选择层级	number	-	undefined

Events

名称	说明	参数
update:modelValue	选中值变化事件	(number|string)[]
selectTextChange	选择文本变化事件	string
pickEnd	选择结束事件	无

Slots

名称	说明
header	自定义头部区域

CascaderField

级联选择器的表单字段形式，结合了弹出层使用。

Props

名称	说明	类型	必填	默认值
modelValue	选中的值	(string|number)[]	-	[]
data	数据源	CascaderItem[]	是	-
title	标题	string	-	'请选择'
placeholder	占位符	string	-	'请选择'
showSelectText	是否显示选择的文本	boolean	-	true
initalValue	初始值	string[]	-	-
shouldUpdateValueImmediately	是否在选择完成后立即更新值	boolean	-	false
textProps	显示的文本属性	TextProps	-	-
beforeConfirm	确认前的回调	(value: (string|number)[]|undefined) => Promise<boolean>	-	-
autoConfirm	是否在选择完成后直接关闭	boolean	-	true
listHeight	列表的高度（rpx）	number|string	-	700
textKey	选项的文本键名	string	-	'text'
valueKey	选项的值键名	string	-	'value'
childrenKey	选项的子选项键名	string	-	'children'
tabProps	Tab组件的自定义选项	Omit<TabsProps, 'tabs' | 'currentIndex'>	-	{ width: 750 - 70 }
asyncLoadData	异步加载数据函数	(group: CascaderItem, level: number) => Promise<CascaderItem[]>	-	-
maxSelectLevel	最大选择层级	number	-	undefined

Events

名称	说明	参数
update:modelValue	选中值变化事件	(number|string)[]
cancel	取消选择事件	无
confirm	确认选择事件	无
selectTextChange	选择文本变化事件	string
tempValueChange	临时值变化事件	(number|string)[]

Slots

名称	说明
footer	自定义底部区域

主题变量

名称	类型	默认值	说明
SimpleListItemPaddingHorizontal	number	35	列表项水平内边距