Cascader 级联选择器 | uView Next - 企业级、高质量、更贴近业务场景的 uniapp ui框架

# Cascader 级联选择器

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

# 基础用法

通过 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="areaOptions" 
        @close="showBasic = false" 
        @confirm="onBasicConfirm"
        @select="onBasicSelect"
       />
    </card>
  </view>
</template>

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

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

// 地区数据
const areaOptions = ref<UnCascaderItem[]>([
  {
    label: '北京市',
    value: '110000',
    children: [
      {
        value: '110100',
        label: '北京市',
        children: [
          {
            value: '110101',
            label: '东城区',
            children: [
              { value: '110101001', label: '东华门街道' },
              { value: '110101002', label: '景山街道' },
              { value: '110101003', label: '交道口街道' }
            ]
          },
          {
            value: '110102',
            label: '西城区',
            children: [
              { value: '110102001', label: '西长安街街道' },
              { value: '110102002', label: '新街口街道' },
              { value: '110102003', label: '月坛街道' }
            ]
          },
          {
            value: '110105',
            label: '朝阳区',
            children: [
              { value: '110105001', label: '建外街道' },
              { value: '110105002', label: '朝外街道' },
              { value: '110105003', label: '呼家楼街道' }
            ]
          }
        ]
      }
    ]
  }
])

// 基础使用事件
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>
✅ Copy success!

# 预设值

可以通过 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="areaOptions" 
      @close="showPreset = false" 
      @confirm="onPresetConfirm" 
    />
  </card>
</template>

<script setup lang="uts">
import { UnCascaderItem, UnCascaderConfirmEvent } from '@/uni_modules/uview-unix/components/un-cascader'
import { ref } from 'vue'

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

// 地区数据（同上）
const areaOptions = ref<UnCascaderItem[]>([
  // ... 同上
])

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

# 自定义样式

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

<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="areaOptions"
      :round="10"
      title="请选择地区"
      active-color="#ff6b6b" 
      @close="showCustomStyle = false" 
      @change="onCustomStyleConfirm" />
  </card>
</template>

<script setup lang="uts">
import { UnCascaderItem, UnCascaderConfirmEvent } from '@/uni_modules/uview-unix/components/un-cascader'
import { ref } from 'vue'

// 自定义样式
const showCustomStyle = ref(false)
const customStyleValue = ref<string[]>([])
const customStyleLabel = ref('')

// 地区数据（同上）
const areaOptions = ref<UnCascaderItem[]>([
  // ... 同上
])

// 自定义样式事件
const onCustomStyleConfirm = (item: UnCascaderConfirmEvent) => {
  customStyleLabel.value = item.label.join('/')
}
</script>
✅ Copy success!

# 选择事件

通过 @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/components/un-cascader'

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

# API

# Props

参数	说明	类型	默认值
show	是否显示级联选择器	Boolean	false
title	选择器标题	String	请选择
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	关闭时触发	-
confirm	确认选择时触发（选择到最后一级时）	UnCascaderConfirmEvent
select	选择某一项时触发	UnCascaderSelectEvent

# 类型定义

# UnCascaderItem

级联选择器的选项数据类型，用于定义 options 属性的数据结构。

type UnCascaderItem = {
    label: string                    // 选项显示文本
    value: string | number           // 选项值
    children?: UnCascaderItem[]     // 子选项（可选）
}
✅ Copy success!

示例：

const options: UnCascaderItem[] = [
    {
        label: '北京市',
        value: '110000',
        children: [
            {
                label: '北京市',
                value: '110100',
                children: [
                    {
                        label: '东城区',
                        value: '110101',
                        children: [
                            { label: '东华门街道', value: '110101001' },
                            { label: '景山街道', value: '110101002' }
                        ]
                    }
                ]
            }
        ]
    }
]
✅ Copy success!

# UnCascaderSelectEvent

选择事件回调参数类型，在 @select 事件中返回。

type UnCascaderSelectEvent = {
    label: string               // 当前选择项的显示文本
    value: string | number      // 当前选择项的值
    level: number              // 当前层级（从0开始）
    items: UnCascaderItem[]    // 选择路径上的所有项
}
✅ Copy success!

# UnCascaderConfirmEvent

确认事件回调参数类型，在 @confirm 事件中返回。

type UnCascaderConfirmEvent = {
    label: Array<string>               // 完整选择路径的标签数组
    value: Array<string | number>      // 完整选择路径的值数组
    items: UnCascaderItem[]           // 完整选择路径的项数组
}
✅ Copy success!

属性说明：

label: 完整选择路径的标签数组，如 ['北京市', '北京市', '东城区', '东华门街道']
value: 完整选择路径的值数组，如 ['110000', '110100', '110101', '110101001']
items: 完整选择路径的项数组

# 注意事项

数据格式: options 数据必须符合 UnCascaderItem 类型定义，每个选项必须包含 label 和 value 属性
层级嵌套: 组件支持无限层级嵌套，通过 children 属性定义子选项
事件参数: 事件回调参数类型严格，使用时需要正确导入对应的类型定义
值类型: v-model 绑定的值必须是数组类型，包含完整选择路径的值

← Calendar 日历 Picker 选择器 →