UviewUltra 4.0

Appearance

Cascader 级联选择器 4.4.0 ​

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

使用场景 ​

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

平台差异说明 ​

|App（vue）|App（uvue/uni-app-x）|App（nvue）|H5|小程序| |:-😐:-😐:-😐:-😐:-😐:-😐 |√|√|√|√|

基本使用 ​

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

设置默认值 ​

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

html
<template>
	<view>
		<up-button @click="show = true">选择商品分类</up-button>
		<up-cascader 
			v-model:show="show"
			v-model="value"
			:data="categoryData"
		></up-cascader>
	</view>
</template>
js
<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>

自定义字段名 ​

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

html
<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>
js
<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>

垂直头部及单列选项 ​

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

html
<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>
js
<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>

自动关闭 ​

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

html
<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控制组件显示或隐藏Booleanfalsetrue
data级联数据Array[]-
value-key指定选项的值为选项对象中的哪个属性值String'value'-
label-key指定选项标签为选项对象中的哪个属性值String'label'-
children-key指定选项的子选项为选项对象中的哪个属性值String'children'-
mask-close-able是否允许通过点击遮罩关闭Booleantruefalse
z-index弹出时的 z-index 值String | Number0-
auto-close是否在选择最后一级时自动关闭并触发 confirmBooleanfalsetrue
headerDirection头部项目展示方向Stringrowcolumn
optionsCols选项展示列表Number21
closeable4.4.0是否显示右上角关闭图标Booleantruefalse

Events ​

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