外观
CascaderPicker 级联选择器
约 1178 字大约 4 分钟
2025-10-31
注意:该组件的
options属性为和cascader组件的options属性相同,数据结构也相同, 可以通用
基础使用
以下示例展示了如何使用级联选择器的基本功能:
<template>
<view>
<un-cell-group>
<un-cell @click="showPicker1" title="基础使用" isLink></un-cell>
</un-cell-group>
<un-cascader-picker
v-model="defaultValue"
:options="options"
:title="title"
:show="show"
@change="change"
@close="close"
@cancel="cancel"
@confirm="confirm"
></un-cascader-picker>
</view>
</template>
<script setup lang="uts">
import { ref } from 'vue'
import type { UnCascaderOption, UnCascaderConfirmEvent, UnCascaderChangeEvent } from '@/uni_modules/uview-unix'
const title = ref('')
const show = ref(false)
const options = ref<UnCascaderOption[]>([])
const defaultValue = ref<string[]>([])
const close = () => {
show.value = false
}
const confirm = (event: UnCascaderConfirmEvent) => {
console.log('confirm', event)
show.value = false
}
const cancel = () => {
show.value = false
}
const change = (event: UnCascaderChangeEvent) => {
console.log('change', event)
}
const showPicker1 = () => {
show.value = true
title.value = ''
options.value = [
{
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' }
]
}
]
}
]
}
</script>三级地区选择
我们提供一份中国省市区数据, 数据来源于 Vant,包含了中国所有的省、市、区(或县)数据。 使用方法如下:
可以通过 v-model 设置初始选中值,组件会自动定位到对应的层级。
<template>
<view>
<un-cell-group>
<un-cell @click="showPicker2" title="三级地区" isLink></un-cell>
</un-cell-group>
<un-cascader-picker
v-model="defaultValue"
:options="options"
:title="title"
:show="show"
@change="change"
@close="close"
@cancel="cancel"
@confirm="confirm"
></un-cascader-picker>
</view>
</template>
<script setup lang="uts">
import { ref } from 'vue'
import { useAreaCascaderData } from '@/uni_modules/uview-unix'
import type { UnCascaderOption, UnCascaderConfirmEvent, UnCascaderChangeEvent } from '@/uni_modules/uview-unix'
const areaList = useAreaCascaderData()
const title = ref('请选择地区')
const show = ref(false)
const options = ref<UnCascaderOption[]>([])
const defaultValue = ref<string[]>([])
const close = () => {
show.value = false
}
const confirm = (event: UnCascaderConfirmEvent) => {
console.log('confirm', event)
show.value = false
}
const cancel = () => {
show.value = false
}
const change = (event: UnCascaderChangeEvent) => {
console.log('change', event)
}
const showPicker2 = () => {
show.value = true
options.value = areaList
}
</script>设置默认值
通过设置v-model的值,可以在打开选择器时预设选中项:
<template>
<view>
<un-cell-group>
<un-cell @click="showPicker3" title="设置默认值" isLink></un-cell>
</un-cell-group>
<un-cascader-picker
v-model="defaultValue"
:options="options"
:title="title"
:show="show"
@change="change"
@close="close"
@cancel="cancel"
@confirm="confirm"
></un-cascader-picker>
</view>
</template>
<script setup lang="uts">
import { ref } from 'vue'
import { useAreaCascaderData } from '@/uni_modules/uview-unix'
import type { UnCascaderOption, UnCascaderConfirmEvent, UnCascaderChangeEvent } from '@/uni_modules/uview-unix'
const areaList = useAreaCascaderData()
const title = ref('请选择地区')
const show = ref(false)
const options = ref<UnCascaderOption[]>([])
const defaultValue = ref<string[]>([])
const close = () => {
show.value = false
}
const confirm = (event: UnCascaderConfirmEvent) => {
console.log('confirm', event)
show.value = false
}
const cancel = () => {
show.value = false
}
const change = (event: UnCascaderChangeEvent) => {
console.log('change', event)
}
const showPicker3 = () => {
show.value = true
options.value = areaList
defaultValue.value = ['130000', '130400', '130407'] // 预设河北省邯郸市肥乡区
}
</script>API
Props
| 参数 | 说明 | 类型 | 默认值 | 可选值 |
|---|---|---|---|---|
| v-model | 当前选中项对应的值 | Array<string | number> | - | - |
| show | 用于控制选择器的弹出与收起 | Boolean | false | true |
| showToolbar | 是否显示顶部的操作栏 | Boolean | true | false |
| title | 顶部中间的标题 | String | - | - |
| options | 级联选择器的数据数组,支持树形结构 | Array<UnCascaderOption> | - | - |
| loading | 加载状态 | Boolean | false | true |
| itemHeight | 各列中,单个选项的高度 | String | Number | 44 | - |
| cancelText | 取消按钮的文字 | String | 取消 | - |
| confirmText | 确认按钮的文字 | String | 确认 | - |
| cancelColor | 取消按钮的颜色 | String | #909193 | - |
| confirmColor | 确认按钮的颜色 | String | #3c9cff | - |
| visibleItemCount | 每列中可见选项的数量 | String | Number | 5 | - |
| closeOnClickOverlay | 是否允许点击遮罩关闭选择器(注意:关闭事件需要自行处理,只会在开启closeOnClickOverlay后点击遮罩层执行close回调) | Boolean | true | false |
| immediateChange | 是否在手指松开时立即触发change事件。若不开启则会在滚动动画结束后触发change事件 | Boolean | false | true |
| round | 圆角值,默认无圆角 | String | Number | 0 | - |
Events
| 事件名 | 说明 | 回调参数 | 版本 |
|---|---|---|---|
| close | 关闭选择器时触发 | - | - |
| confirm | 点击确定按钮,返回当前选择的值 | UnCascaderConfirmEvent: 包含选中的值和标签文本 | - |
| change | 当选择值变化时触发 | UnCascaderChangeEvent: 包含选中的值、标签文本和当前层级信息 | - |
| cancel | 点击取消按钮 | - | - |
数据类型
// 级联选择器的选项数据类型,用于定义 `options` 属性的数据结构。
type UnCascaderOption = {
text: string; // 显示的文本
value: string; // 对应的值
children?: UnCascaderOption[]; // 子选项数组
}
// 级联选择器确认事件数据类型,用于定义 `confirm` 事件回调参数的数据结构。
type UnCascaderConfirmEvent = {
value: string[]; // 选中项的值数组
text: string[]; // 选中项的文本数组
items: UnCascaderOption[]; // 选中项的完整对象数组
}
// 级联选择器选择事件数据类型,用于定义 `change` 事件回调参数的数据结构。
type UnCascaderChangeEvent = {
value: string[]; // 当前选中的值数组
text: string[]; // 当前选中的文本数组
index: number; // 当前变化的列索引
items: UnCascaderOption[]; // 当前选中的项数组
}