外观
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>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[]; // 完整选择路径的项数组
};