Cascader 级联选择器 | uView Next - 全面兼容 nvue 的 uni-app 生态框架

# Cascader 级联选择器新

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

# 平台差异说明

App（vue）	App（nvue）	H5	小程序
√	√	√	√

# 基础用法

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

<template>
  <view>
    <view class="demo-item" @click="show = true">
      <text>地区选择</text>
      <text>{{ selectedLabel }}</text>
    </view>
    <u-cascader 
      :show="show" 
      v-model="value" 
      :options="options" 
      @close="show = false" 
      @confirm="onConfirm" 
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      show: false,
      value: '',
      selectedLabel: '',
      options: [
        {
          label: '北京市',
          value: '110000',
          children: [
            {
              value: '110100',
              label: '北京市',
              children: [
                { value: '110101', label: '东城区' },
                { value: '110102', label: '西城区' },
                { value: '110105', label: '朝阳区' }
              ]
            }
          ]
        }
      ]
    }
  },
  methods: {
    onConfirm({ label }) {
      this.selectedLabel = label.join('/')
    }
  }
}
</script>
✅ Copy success!

# 预设值

可以通过 v-model 设置初始选中值，组件会自动定位到对应的层级。

<template>
  <u-cascader 
    :show="show" 
    v-model="presetValue" 
    :options="options" 
    @close="show = false" 
    @confirm="onConfirm" 
  />
</template>

<script>
export default {
  data() {
    return {
      show: false,
      presetValue: ['110000', '110100', '110105'], // 预设选中朝阳区
      options: [
        // ... 同上
      ]
    }
  }
}
</script>
✅ Copy success!

# 自定义样式

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

<template>
  <u-cascader 
    :show="show" 
    v-model="value" 
    :options="options"
    title="请选择地区"
    active-color="#ff6b6b"
    :round="10"
    @close="show = false" 
    @change="onChange" 
  />
</template>
✅ Copy success!

# 自定义字段名

当数据结构与默认字段名不一致时，可以通过 field 属性自定义字段名。

<template>
  <u-cascader 
    :show="show" 
    v-model="value" 
    :options="options"
    :field="{ label: 'name', value: 'id', children: 'kids' }"
    @close="show = false" 
  />
</template>

<script>
export default {
  data() {
    return {
      options: [
        {
          name: '北京市',
          id: '110000',
          kids: [
            // ...
          ]
        }
      ]
    }
  }
}
</script>
✅ Copy success!

# API

# Props

参数	说明	类型	默认值
show	是否显示级联选择器	Boolean	false
title	选择器标题	String	请选择
options	选项数据	Array	[]
modelValue/value	当前选中值	String / Number / Array	-
placeholder	占位符文本	String	请选择
field	自定义字段名	Object	{label: 'label', value: 'value', children: 'children'}
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

事件名	说明	回调参数
change	选择改变时触发	{value: 选中值数组, label: 选中标签数组, selectedItems: 选中项数组}
close	关闭时触发	-
confirm	确认选择时触发（选择到最后一级时）	{value: 选中值数组, label: 选中标签数组, selectedItems: 选中项数组}
selected	选择某一项时触发	{item: 选中项, level: 当前层级, selectedPath: 选择路径}

# Options 数据结构

每个选项应包含以下字段（可通过 field 属性自定义）：

{
  label: '显示文本',
  value: '选项值',
  children: [ // 子选项（可选）
    {
      label: '子选项文本',
      value: '子选项值',
      children: [...]
    }
  ]
}
✅ Copy success!

# 注意事项

options 数据必须是树形结构，每个节点可以包含 children 字段
选中值 v-model 可以是单个值或数组，数组表示从根到叶子的完整路径
当选择到最后一级（没有子项）时，会自动触发 confirm 事件并关闭选择器
可以通过 field 属性自定义数据字段名，适配不同的数据结构

← Fab 悬浮按钮 Pagination 分页 →

# Cascader 级联选择器 新