Cascader 级联选择器

当一个数据集合有清晰的层级结构时，可以通过级联选择器逐级查看并选择。VISTA B 直接使用 Element Plus 的 el-cascader，样式沿用组件库，适合项目分类、区域层级、素材目录、户型层级等有父子关系的数据选择。

基础用法

为 options 指定选项数组即可渲染级联选择器。默认点击展开子级，也可以通过 props.expandTrigger 改为鼠标悬停展开。

vue

<script setup>
import { ref } from 'vue'

const value = ref([])
const options = [
  {
    value: 'project',
    label: '项目管理',
    children: [
      {
        value: 'active',
        label: '进行中项目',
        children: [
          { value: 'detail', label: '项目详情' },
          { value: 'quote', label: '报价配置' }
        ]
      }
    ]
  }
]

const props = {
  expandTrigger: 'hover'
}
</script>

<template>
  <el-cascader v-model="value" :options="options" :props="props" />
</template>

禁用选项

在选项中设置 disabled: true 后，该项及其子级不能被选择。默认字段名为 disabled，也可以通过 props.disabled 改成业务里的其他字段。

vue

<el-cascader :options="options" />

<script setup>
const options = [
  {
    value: 'project',
    label: '项目管理',
    children: [
      { value: 'active', label: '进行中项目' },
      { value: 'archive', label: '归档项目', disabled: true }
    ]
  }
]
</script>

可清空

设置 clearable 后，输入框右侧会显示清空按钮，适合筛选表单和可选条件。

vue

<el-cascader
  v-model="value"
  :options="options"
  clearable
/>

仅显示最后一级

默认情况下，输入框会显示完整路径。设置 show-all-levels="false" 后，只展示最后一级标签。

vue

<el-cascader
  v-model="value"
  :options="options"
  :show-all-levels="false"
/>

多选

设置 props.multiple 后，可以选择多个节点。多选模式可配合 collapse-tags 收起已选标签，避免输入框过长。

vue

<script setup>
const props = {
  multiple: true
}
</script>

<template>
  <el-cascader
    v-model="value"
    :options="options"
    :props="props"
    collapse-tags
    collapse-tags-tooltip
  />
</template>

选择任意一级

设置 props.checkStrictly 后，父子节点不再关联，用户可以选择任意一级节点。它也可以和多选一起使用。

vue

<script setup>
const props = {
  checkStrictly: true
}
</script>

<template>
  <el-cascader v-model="value" :options="options" :props="props" />
</template>

动态加载

设置 props.lazy 后，可以在展开节点时动态加载子级。lazyLoad 接收当前节点和 resolve 回调，调用 resolve(nodes) 后追加子节点。

vue

<script setup>
const props = {
  lazy: true,
  lazyLoad(node, resolve) {
    const { level } = node
    setTimeout(() => {
      const nodes = Array.from({ length: level + 1 }).map((_, index) => ({
        value: `${level}-${index}`,
        label: `选项 ${level}-${index}`,
        leaf: level >= 2
      }))
      resolve(nodes)
    }, 500)
  }
}
</script>

<template>
  <el-cascader :props="props" />
</template>

可搜索

设置 filterable 后，可以搜索选项。默认匹配节点的 label，如需业务自定义匹配逻辑，可使用 filter-method。

vue

<el-cascader
  v-model="value"
  :options="options"
  filterable
  clearable
/>

自定义节点内容

通过默认插槽可以拿到 node 和 data，用于展示数量、状态或其他业务信息。

vue

<el-cascader :options="options">
  <template #default="{ node, data }">
    <span>{{ data.label }}</span>
    <span v-if="!node.isLeaf">（{{ data.children.length }}）</span>
  </template>
</el-cascader>

级联面板

如果只需要级联选择面板，不需要输入框触发器，可以直接使用 el-cascader-panel。

vue

<el-cascader-panel
  v-model="value"
  :options="options"
/>

API

Cascader 属性

属性	说明	类型	默认值
`model-value` / `v-model`	选中项绑定值	`string` / `number` / `array`	空
`options`	可选项数据源	`array`	`[]`
`props`	配置选项，见 CascaderProps	`object`	空
`size`	输入框尺寸	`large` / `default` / `small`	空
`placeholder`	输入框占位文本	`string`	`Select`
`disabled`	是否禁用	`boolean`	`false`
`clearable`	是否支持清空选项	`boolean`	`false`
`show-all-levels`	输入框中是否显示完整路径	`boolean`	`true`
`collapse-tags`	多选模式下是否折叠标签	`boolean`	`false`
`collapse-tags-tooltip`	折叠标签时是否显示提示	`boolean`	`false`
`max-collapse-tags`	折叠前最多显示的标签数量	`number`	`1`
`separator`	选项分隔符	`string`	`/`
`filterable`	是否可搜索选项	`boolean`	`false`
`filter-method`	自定义搜索方法	`(node, keyword) => boolean`	空
`debounce`	搜索防抖延迟，单位毫秒	`number`	`300`
`before-filter`	搜索前的钩子，返回 `false` 或 rejected Promise 时取消搜索	`(keyword) => boolean` / `Promise`	空
`popper-class`	下拉弹层自定义类名	`string`	`''`
`teleported`	下拉弹层是否挂载到 `body`	`boolean`	`true`
`tag-type`	标签类型	`success` / `info` / `warning` / `danger`	`info`
`tag-effect`	标签主题	`light` / `dark` / `plain`	`light`
`validate-event`	输入时是否触发表单校验	`boolean`	`true`
`persistent`	下拉框未显示时是否保留 DOM	`boolean`	`true`

CascaderProps

属性	说明	类型	默认值
`expandTrigger`	展开次级菜单的触发方式	`click` / `hover`	`click`
`multiple`	是否多选	`boolean`	`false`
`checkStrictly`	是否严格遵守父子节点不互相关联	`boolean`	`false`
`emitPath`	选中节点的值是否包含完整路径	`boolean`	`true`
`lazy`	是否动态加载子节点	`boolean`	`false`
`lazyLoad`	动态加载子节点的方法	`(node, resolve) => void`	空
`value`	指定选项值的字段名	`string`	`value`
`label`	指定选项标签的字段名	`string`	`label`
`children`	指定选项子节点的字段名	`string`	`children`
`disabled`	指定禁用状态的字段名	`string`	`disabled`
`leaf`	指定叶子节点状态的字段名	`string`	`leaf`
`hoverThreshold`	悬停展开的延迟，单位毫秒	`number`	`500`
`checkOnClickNode`	是否点击节点文本时选中节点	`boolean`	`false`
`checkOnClickLeaf`	是否点击叶子节点文本时选中节点	`boolean`	`true`

Cascader 事件

事件名	说明	类型
`change`	选中节点变化时触发	`(value) => void`
`expand-change`	展开节点变化时触发	`(value) => void`
`blur`	组件失去焦点时触发	`(event: FocusEvent) => void`
`focus`	组件获得焦点时触发	`(event: FocusEvent) => void`
`visible-change`	下拉框显示或隐藏时触发	`(visible: boolean) => void`
`remove-tag`	多选模式下移除标签时触发	`(value) => void`

Cascader 方法

方法名	说明	类型
`getCheckedNodes`	获取当前选中的节点	`(leafOnly: boolean) => Node[]`
`cascaderPanelRef`	级联面板实例	`object`
`togglePopperVisible`	切换下拉框显示状态	`(visible?: boolean) => void`

Cascader 插槽

插槽	说明
`default`	自定义节点内容，参数为 `{ node, data }`
`empty`	无匹配选项时的内容
`prefix`	输入框前缀内容
`tag`	多选模式下自定义标签内容

CascaderPanel 属性

属性	说明	类型	默认值
`model-value` / `v-model`	选中项绑定值	`string` / `number` / `array`	空
`options`	可选项数据源	`array`	`[]`
`props`	配置选项，同 CascaderProps	`object`	空

CascaderPanel 事件

事件名	说明	类型
`change`	选中节点变化时触发	`(value) => void`
`expand-change`	展开节点变化时触发	`(value) => void`
`close`	面板关闭时触发	`() => void`

CascaderPanel 方法

方法名	说明	类型
`getCheckedNodes`	获取当前选中的节点	`(leafOnly: boolean) => Node[]`
`clearCheckedNodes`	清空已选节点	`() => void`

Cascader 级联选择器 ​

基础用法 ​

禁用选项 ​

可清空 ​

仅显示最后一级 ​

多选 ​

选择任意一级 ​

动态加载 ​

可搜索 ​

自定义节点内容 ​

级联面板 ​

API ​

Cascader 属性 ​

CascaderProps ​

Cascader 事件 ​

Cascader 方法 ​

Cascader 插槽 ​

CascaderPanel 属性 ​

CascaderPanel 事件 ​

CascaderPanel 方法 ​