Cascader 级联选择器

约 1371 字大约 5 分钟

2025-10-31

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

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

基础用法

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

<template>
  <view class="u-page">
    <card title="基础使用">
      <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"
       />
    </card>
  </view>
</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>

三级地区

我们提供一份中国省市区数据, 数据来源于 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>

API

Props

参数	说明	类型	默认值
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[]           // 完整选择路径的项数组
}

Scss 变量

关于组件 SCSS 变量的用法，请参考组件 SCSS 变量用法。

变量名	默认值	说明
$un-cascader-item-padding	0 15px	级联选择器选项内边距
$un-cascader-item-height	40px	级联选择器选项高度
$un-cascader-item-text-font-size	$text-base	级联选择器选项文本字体大小
$un-cascader-item-text-color	$text-color	级联选择器选项文本颜色
$un-cascader-item-text-selected-font-weight	bold	级联选择器选中选项文本字体粗细
$un-cascader-item-text-selected-color	$color-primary	级联选择器选中选项文本颜色