Cascader 级联选择器

约 1364 字大约 5 分钟

2025-10-31

级联选择器，用于多级数据的选择，常用于省市区选择、商品分类选择等场景。

注意：该组件的options属性为和 cascader-picker 组件的 options 属性相同，数据结构也相同, 可以通用

基础用法

通过 options 属性设置级联数据，通过 v-model 绑定选中值。

<template>
	<view class="demo-item" @click="showBasic = true">
		<text>请选择地区</text>
		<text class="selected-text">{{ basicLabel }}</text>
	</view>
	<un-cascader
		v-model="basicValue"
		:show="showBasic"
		:options="baseOptions"
		@close="showBasic = false"
		@confirm="onBasicConfirm"
		@select="onBasicSelect"
	/>
</template>

<script setup lang="uts">
import { UnCascaderOption, UnCascaderConfirmEvent, UnCascaderSelectEvent } from '@/uni_modules/uview-unix'
import { ref } from 'vue'

// 基础使用
const showBasic = ref(false)
const basicValue = ref<string[]>([])
const basicLabel = ref('')

// 地区数据
const baseOptions = ref<UnCascaderOption[]>([
	{
		text: '数码电器',
		value: 'digital',
		children: [
			{
				text: '手机',
				value: 'phone',
				children: [
					{ text: 'iPhone', value: 'iphone' },
					{ text: 'Android', value: 'android' }
				]
			},
			{
				text: '电脑',
				value: 'computer',
				children: [
					{ text: '笔记本', value: 'laptop' },
					{ text: '台式机', value: 'desktop' }
				]
			}
		]
	},
	{
		text: '服装鞋帽',
		value: 'clothing',
		children: [
			{
				text: '男装',
				value: 'mens',
				children: [
					{ text: 'T恤', value: 'tshirt' },
					{ text: '衬衫', value: 'shirt' }
				]
			},
			{
				text: '女装',
				value: 'womens',
				children: [
					{ text: '连衣裙', value: 'dress' },
					{ text: '半身裙', value: 'skirt' }
				]
			}
		]
	}
])

// 基础使用事件
const onBasicConfirm = (item: UnCascaderConfirmEvent) => {
  basicLabel.value = item.label.join('/')
}

// 选择事件
const onBasicSelect = (item: UnCascaderSelectEvent) => {
  basicLabel.value = item.label
}
</script>

<style lang="scss">
.demo-item {
  display: flex;
  flex-direction: row;
  justify-content: space-between;
  align-items: center;
}
.selected-text {
  font-size: 14px;
  color: #666;
}
</style>

使用触发器打开

通过 options 属性设置级联数据，通过 v-model 绑定选中值。

<template>
	<un-cascader v-model="basicValue" :options="baseOptions" @confirm="onBasicConfirm">
		<text>请选择地区</text>
	</un-cascader>
</template>

<script setup lang="uts">
import { UnCascaderOption, UnCascaderConfirmEvent, UnCascaderSelectEvent } from '@/uni_modules/uview-unix'
import { ref } from 'vue'

const basicValue = ref<string[]>([])

// 地区数据
const baseOptions = ref<UnCascaderOption[]>([
	{
		text: '数码电器',
		value: 'digital',
		children: [
			{
				text: '手机',
				value: 'phone',
				children: [
					{ text: 'iPhone', value: 'iphone' },
					{ text: 'Android', value: 'android' }
				]
			},
			{
				text: '电脑',
				value: 'computer',
				children: [
					{ text: '笔记本', value: 'laptop' },
					{ text: '台式机', value: 'desktop' }
				]
			}
		]
	},
	{
		text: '服装鞋帽',
		value: 'clothing',
		children: [
			{
				text: '男装',
				value: 'mens',
				children: [
					{ text: 'T恤', value: 'tshirt' },
					{ text: '衬衫', value: 'shirt' }
				]
			},
			{
				text: '女装',
				value: 'womens',
				children: [
					{ text: '连衣裙', value: 'dress' },
					{ text: '半身裙', value: 'skirt' }
				]
			}
		]
	}
])

// 基础使用事件
const onBasicConfirm = (item: UnCascaderConfirmEvent) => {

}
</script>

三级地区

我们提供一份中国省市区数据, 数据来源于 Vant，包含了中国所有的省、市、区（或县）数据。使用方法如下：

可以通过 v-model 设置初始选中值，组件会自动定位到对应的层级。

<template>
  <card title="三级地区">
    <view class="demo-item" @click="showPreset = true">
      <text>请选择地区</text>
      <text class="selected-text">{{ presetLabel }}</text>
    </view>
    <un-cascader
      :show="showPreset"
      v-model="presetValue"
      :options="areaList"
      @close="showPreset = false"
      @confirm="onPresetConfirm"
    />
  </card>
</template>

<script setup lang="uts">
import { ref } from 'vue'
import { useAreaCascaderData } from '@/uni_modules/uview-unix'
import { UnCascaderOption, UnCascaderConfirmEvent } from '@/uni_modules/uview-unix'

const areaList = useAreaCascaderData()

// 预设值
const showPreset = ref(false)
const presetValue = ref<string[]>(['110000', '110100', '110105','110105003']) // 预设选中朝阳区呼家楼街道
const presetLabel = ref('')

// 预设值事件
const onPresetConfirm = (item: UnCascaderConfirmEvent) => {
  presetLabel.value = item.label.join('/')
}
</script>

自定义样式

可以通过多个属性自定义选择器的样式。

<template>
  <card title="自定义样式">
    <view class="demo-item" @click="showCustomStyle = true">
      <text>请选择地区</text>
      <text class="selected-text">{{ customStyleLabel }}</text>
    </view>
    <un-cascader
      v-model="customStyleValue"
      :show="showCustomStyle"
      :options="areaList"
      :round="10"
      title="请选择地区"
      active-color="#ff6b6b"
      @close="showCustomStyle = false"
      @change="onCustomStyleConfirm"
    />
  </card>
</template>

<script setup lang="uts">
import { ref } from 'vue'
import { useAreaCascaderData } from '@/uni_modules/uview-unix'
import { UnCascaderOption, UnCascaderConfirmEvent } from '@/uni_modules/uview-unix'

const areaList = useAreaCascaderData()

// 预设值
const showPreset = ref(false)
const presetValue = ref<string[]>(['110000', '110100', '110105','110105003']) // 预设选中朝阳区呼家楼街道
const presetLabel = ref('')

// 预设值事件
const onPresetConfirm = (item: UnCascaderConfirmEvent) => {
  presetLabel.value = item.label.join('/')
}
</script>

选择事件

通过 @select 事件监听选择过程，获取当前选择的项信息。

<template>
  <un-cascader
    v-model="basicValue"
    :show="showBasic"
    :options="areaOptions"
    @close="showBasic = false"
    @confirm="onBasicConfirm"
    @select="onBasicSelect"
  />
</template>

<script setup lang="uts">
import { UnCascaderSelectEvent } from '@/uni_modules/uview-unix'

// 选择事件
const onBasicSelect = (item: UnCascaderSelectEvent) => {
  console.log('选择项:', item.text)
  console.log('选择值:', item.value)
  console.log('当前层级:', item.level)
  console.log('选择路径:', item.items)
}
</script>

| 参数 | 说明 | 类型 | 默认值 | | ------------------- | ---------------------- | ----------------------- | ------- | --- | | show | 是否显示级联选择器 | Boolean | false | | title | 选择器标题 | String | 请选择 | | height | 弹窗高度 | String / Number | 500px | | titleStyle | 自定义样式弹窗标题样式 | Object | String | - | - | | options | 选项数据 | Array | [] | | modelValue / value | 当前选中值 | Array<String | Number> | - | | placeholder | 占位符文本 | String | 请选择 | | closeable | 是否显示关闭按钮 | Boolean | true | | closeOnClickOverlay | 是否点击遮罩关闭 | Boolean | true | | bgColor | 背景色 | String | #ffffff | | activeColor | 主题色 | String | #3c9cff | | activeBgColor | 选中背景色 | String | - | | activeBold | 选中文本是否加粗 | Boolean | false | | iconColor | 图标颜色 | String | - | | color | 文本颜色 | String | #303133 | | fontSize | 字体大小 | String | 16px | | titleFontSize | 标题字体大小 | String | 18px | | titleColor | 标题颜色 | String | #303133 | | round | 圆角 | String / Number | 12px | | zIndex | 层级 | String / Number | 10075 | | safeAreaInsetBottom | 是否开启底部安全区适配 | Boolean | true | | itemHeight | 选项高度 | String | 50px |

Events

事件名	说明	类型
close	关闭时触发	Function
confirm	确认选择时触发（选择到最后一级时）	Function
change	选择某一项时触发	Function

数据类型

// 级联选择器的选项数据类型，用于定义 `options` 属性的数据结构。
type UnCascaderOption = {
  text: string; // 选项显示文本
  value: string | number; // 选项值
  children?: UnCascaderOption[]; // 子选项（可选）
};

// 选择事件回调参数类型，在 `@change` 事件中返回。
type UnCascaderChangeEvent = {
  text: string; // 当前选择项的显示文本
  value: string | number; // 当前选择项的值
  index: number; // 当前层级（从0开始）
  items: UnCascaderOption[]; // 选择路径上的所有项
};

// 确认事件回调参数类型，在 `@confirm` 事件中返回。
type UnCascaderConfirmEvent = {
  text: Array<string>; // 完整选择路径的标签数组
  value: Array<string | number>; // 完整选择路径的值数组
  items: UnCascaderOption[]; // 完整选择路径的项数组
};