uview-plus

# Cascader 级联选择器 3.5.30

打开

级联选择器，用于选择多级关联数据，如省市区、商品分类等。

# 使用场景

  • 需要从一组相关联的数据集合中进行选择，例如省市区、公司部门、商品分类等
  • 支持无限级联，可配置任意层级
  • 支持自定义字段名，适应不同的数据结构

# 平台差异说明

App（vue） App（nvue） H5 小程序
√ √ √ √

# 基本使用

  • 通过 data 设置级联数据
  • 通过 v-model 绑定选中的值
  • 通过 v-model:show 控制组件显示与隐藏
<template>
	<view>
		<up-button @click="show = true">选择地区</up-button>
		<up-cascader 
			v-model:show="show"
			v-model="value"
			:data="areaData"
		></up-cascader>
	</view>
</template>

<script setup>
import { ref } from 'vue';

const show = ref(false);
const value = ref([]);

const areaData = ref([
	{
		label: '北京市',
		value: '11',
		children: [
			{
				label: '北京市',
				value: '1101',
				children: [
					{ label: '东城区', value: '110101' },
					{ label: '西城区', value: '110102' },
					{ label: '朝阳区', value: '110105' }
				]
			}
		]
	}
]);
</script>

<script>
export default {
	data() {
		return {
			show: false,
			value: [],
			areaData: [
				{
					label: '北京市',
					value: '11',
					children: [
						{
							label: '北京市',
							value: '1101',
							children: [
								{ label: '东城区', value: '110101' },
								{ label: '西城区', value: '110102' },
								{ label: '朝阳区', value: '110105' }
							]
						}
					]
				}
			]
		};
	}
};
</script>

# 设置默认值

通过 v-model 可以设置默认选中值。

<template>
	<view>
		<up-button @click="show = true">选择商品分类</up-button>
		<up-cascader 
			v-model:show="show"
			v-model="value"
			:data="categoryData"
		></up-cascader>
	</view>
</template>

<script setup>
import { ref } from 'vue';

const show = ref(false);
const value = ref(['2', '2-2']); // 默认选中"数码" -> "电脑"

const categoryData = ref([
	{
		label: '服装',
		value: '1',
		children: [
			{
				label: '上装',
				value: '1-1',
				children: [
					{ label: 'T恤', value: '1-1-1' },
					{ label: '衬衫', value: '1-1-2' }
				]
			}
		]
	},
	{
		label: '数码',
		value: '2',
		children: [
			{
				label: '电脑',
				value: '2-2',
				children: [
					{ label: '笔记本', value: '2-2-1' },
					{ label: '台式机', value: '2-2-2' }
				]
			}
		]
	}
]);
</script>

<script>
export default {
	data() {
		return {
			show: false,
			value: ['2', '2-2'], // 默认选中"数码" -> "电脑"
			categoryData: [
				{
					label: '服装',
					value: '1',
					children: [
						{
							label: '上装',
							value: '1-1',
							children: [
								{ label: 'T恤', value: '1-1-1' },
								{ label: '衬衫', value: '1-1-2' }
							]
						}
					]
				},
				{
					label: '数码',
					value: '2',
					children: [
						{
							label: '电脑',
							value: '2-2',
							children: [
								{ label: '笔记本', value: '2-2-1' },
								{ label: '台式机', value: '2-2-2' }
							]
						}
					]
				}
			]
		};
	}
};
</script>

# 自定义字段名

通过 value-key、label-key、children-key 可自定义数据字段名。

<template>
	<view>
		<up-button @click="show = true">选择组织架构</up-button>
		<up-cascader 
			v-model:show="show"
			v-model="value"
			:data="orgData"
			value-key="id"
			label-key="name"
			children-key="childs"
		></up-cascader>
	</view>
</template>

<script setup>
import { ref } from 'vue';

const show = ref(false);
const value = ref([]);

const orgData = ref([
	{
		name: '总部',
		id: '1',
		childs: [
			{
				name: '研发部',
				id: '1-1',
				childs: [
					{ name: '前端组', id: '1-1-1' },
					{ name: '后端组', id: '1-1-2' }
				]
			}
		]
	}
]);
</script>

<script>
export default {
	data() {
		return {
			show: false,
			value: [],
			orgData: [
				{
					name: '总部',
					id: '1',
					childs: [
						{
							name: '研发部',
							id: '1-1',
							childs: [
								{ name: '前端组', id: '1-1-1' },
								{ name: '后端组', id: '1-1-2' }
							]
						}
					]
				}
			]
		};
	}
};
</script>

# 垂直头部及单列选项

如果选项的文案较长，可以配置headerDirection="column"和:optionsCols="1"来展示

<template>
	<view>
		<up-button @click="show = true">选择商品分类</up-button>
		<up-cascader 
			v-model:show="show"
			v-model="value"
			headerDirection="column"
            :optionsCols="1"
			:data="categoryData"
		></up-cascader>
	</view>
</template>

<script setup>
import { ref } from 'vue';

const show = ref(false);
const value = ref(['2', '2-2']); // 默认选中"数码" -> "电脑"

const categoryData = ref([
	{
		label: '服装',
		value: '1',
		children: [
			{
				label: '上装',
				value: '1-1',
				children: [
					{ label: 'T恤', value: '1-1-1' },
					{ label: '衬衫', value: '1-1-2' }
				]
			}
		]
	},
	{
		label: '数码',
		value: '2',
		children: [
			{
				label: '电脑',
				value: '2-2',
				children: [
					{ label: '笔记本', value: '2-2-1' },
					{ label: '台式机', value: '2-2-2' }
				]
			}
		]
	}
]);
</script>

<script>
export default {
	data() {
		return {
			show: false,
			value: ['2', '2-2'], // 默认选中"数码" -> "电脑"
			categoryData: [
				{
					label: '服装',
					value: '1',
					children: [
						{
							label: '上装',
							value: '1-1',
							children: [
								{ label: 'T恤', value: '1-1-1' },
								{ label: '衬衫', value: '1-1-2' }
							]
						}
					]
				},
				{
					label: '数码',
					value: '2',
					children: [
						{
							label: '电脑',
							value: '2-2',
							children: [
								{ label: '笔记本', value: '2-2-1' },
								{ label: '台式机', value: '2-2-2' }
							]
						}
					]
				}
			]
		};
	}
};
</script>

# 自动关闭

通过 auto-close 设置是否在选择最后一级时自动关闭并触发 confirm 事件。

<up-cascader 
	v-model:show="show"
	v-model="value"
	:data="areaData"
	:auto-close="true"
></up-cascader>

# 右侧演示页面源代码地址

点击以下链接以查看右侧演示页面的源码


 github  gitee

# API

# Props

参数 说明 类型 默认值 可选值
v-model / modelValue 绑定选中的值 Array [] -
v-model:show 控制组件显示或隐藏 Boolean false true
data 级联数据 Array [] -
value-key 指定选项的值为选项对象中的哪个属性值 String 'value' -
label-key 指定选项标签为选项对象中的哪个属性值 String 'label' -
children-key 指定选项的子选项为选项对象中的哪个属性值 String 'children' -
mask-close-able 是否允许通过点击遮罩关闭 Boolean true false
z-index 弹出时的 z-index 值 String | Number 0 -
auto-close 是否在选择最后一级时自动关闭并触发 confirm Boolean false true
headerDirection 头部项目展示方向 String row column
optionsCols 选项展示列表 Number 2 1

# Events

事件名 说明 回调参数
change 选中值发生变化时触发 选中的值数组
confirm 点击确认按钮或自动关闭时触发 选中的值数组

← Choose 选择器 →