uView Next
4.0.105

外观

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用于控制选择器的弹出与收起Booleanfalsetrue
showToolbar是否显示顶部的操作栏Booleantruefalse
title顶部中间的标题String--
options级联选择器的数据数组，支持树形结构Array<UnCascaderOption>--
loading加载状态Booleanfalsetrue
itemHeight各列中，单个选项的高度String | Number44-
cancelText取消按钮的文字String取消-
confirmText确认按钮的文字String确认-
cancelColor取消按钮的颜色String#909193-
confirmColor确认按钮的颜色String#3c9cff-
visibleItemCount每列中可见选项的数量String | Number5-
closeOnClickOverlay是否允许点击遮罩关闭选择器（注意：关闭事件需要自行处理，只会在开启closeOnClickOverlay后点击遮罩层执行close回调）Booleantruefalse
immediateChange是否在手指松开时立即触发change事件。若不开启则会在滚动动画结束后触发change事件Booleanfalsetrue
round圆角值，默认无圆角String | Number0-

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[]; // 当前选中的项数组
}

Copyright © 2026 uView Next