Cascader 级联选择器

当一个数据集合有清晰的层级结构时,可通过级联选择器逐级查看并选择。

基础用法

有两种触发子菜单的方式

有禁用选项

通过在数据源中设置 disabled 字段来声明该选项是禁用的

可清空

通过 clearable 设置输入框可清空

仅显示最后一级

可以仅在输入框中显示选中项最后一级的标签,而不是选中项所在的完整路径。

多选

在标签中添加 :props="props" 并设置 props = { multiple: true } 来开启多选模式。

正确用法:

<template>
  <el-cascader :props="props" />
</template>
<script lang="ts">
  export default {
    setup() {
      return {
        props: {
          // props.
          multiple: true,
        },
      }
    },
  }
</script>

错误用法:

<template>
  <!--  Object literal binging here is invalid syntax for cascader  -->
  <el-cascader :props="{ multiple: true }" />
</template>

选择任意一级选项

在单选模式下,你只能选择叶子节点;而在多选模式下,勾选父节点真正选中的都是叶子节点。 启用该功能后,可让父子节点取消关联,选择任意一级选项。

动态加载

当选中某一级时,动态加载该级下的选项。

可搜索

可以快捷地搜索选项并选择。

自定义节点内容

可以自定义备选项的节点内容

级联面板

级联面板是级联选择器的核心组件,与级联选择器一样,有单选、多选、动态加载等多种功能。

Cascader 属性

属性说明类型可选值默认值
model-value / v-model选中项绑定值-
options可选项数据源,键名可通过 Props 属性配置array
props配置选项,具体见下表object
size尺寸stringlarge / default / small
placeholder输入框占位文本stringSelect
disabled是否禁用booleanfalse
clearable是否支持清空选项booleanfalse
show-all-levels输入框中是否显示选中值的完整路径booleantrue
collapse-tags多选模式下是否折叠Tagboolean-false
collapse-tags-tooltip当鼠标悬停于折叠标签的文本时,是否显示所有选中的标签。 要使用此属性,collapse-tags属性必须设定为 trueboolean-false
separator用于分隔选项的字符string' / '
filterable该选项是否可以被搜索boolean
filter-method自定义搜索逻辑,第一个参数是node,第二个参数是keyword,返回的布尔值表示是否保留该选项function(node, keyword)--
debounce搜索关键词正在输入时的去抖延迟,单位为毫秒number300
before-filter过滤函数调用前欲被调用的钩子函数,该函数接受一个参数。 如果该函数的返回值是 false 或者是一个被拒绝的 Promise,那么接下来的过滤逻辑便不会执行。function(value)
popper-class弹出内容的自定义类名string
teleported是否在弹出内容时启用动画booleantrue / falsetrue
popper-append-to-body(弃用)是否将弹出的内容直接插入到 body 元素。 在弹出内容的边框定位出现问题时,可将该属性设置为 falseboolean-true
tag-type标签类型stringsuccess/info/warning/dangerinfo

Cascader 事件

事件名说明回调参数
change当绑定值变化时触发的事件value
expand-change当展开节点发生变化时触发各父级选项值组成的数组
blur当失去焦点时触发(event: Event)
focus当获得焦点时触发(event: Event)
visible-change下拉框出现/隐藏时触发出现则为 true,隐藏则为 false
remove-tag在多选模式下,移除Tag时触发移除的Tag对应的节点的值

Cascader 方法

方法名说明参数
getCheckedNodes获取选中的节点(leafOnly) 是否只是叶子节点,默认值为 false

Cascader 插槽

插槽名说明
-自定义备选项的节点内容,参数为 { node, data },分别为当前节点的 Node 对象和数据
empty无匹配选项时的内容

CascaderPanel 属性

属性说明类型可选值默认值
model-value / v-model选中项绑定值-
options可选项数据源,键名可通过 Props 属性配置array
props配置选项,具体见下表object

CascaderPanel 事件

事件名称说明回调参数
change当选中节点变化时触发value
expand-change当展开节点发生变化时触发各父级选项值组成的数组

CascaderPanel 方法

方法名说明参数
getCheckedNodes获取选中的节点数组(leafOnly) 是否只是叶子节点,默认值为 false
clearCheckedNodes清空选中的节点-

CascaderPanel 插槽

插槽名说明
-自定义备选项的节点内容,参数为 { node, data },分别为当前节点的 Node 对象和数据

Props

属性说明类型可选值默认值
expandTrigger次级菜单的展开方式stringclick / hover'click'
multiple是否多选boolean-false
checkStrictly是否严格的遵守父子节点不互相关联boolean-false
emitPath在选中节点改变时,是否返回由该节点所在的各级菜单的值所组成的数组,若设置 false,则只返回该节点的值boolean-true
lazy是否动态加载子节点,需与 lazyLoad 方法结合使用boolean-false
lazyLoad加载动态数据的方法,仅在 lazy 为 true 时有效function(node, resolve),node为当前点击的节点,resolve为数据加载完成的回调(必须调用)--
value指定选项的值为选项对象的某个属性值string'value'
label指定选项标签为选项对象的某个属性值string'label'
children指定选项的子选项为选项对象的某个属性值string'children'
disabled指定选项的禁用为选项对象的某个属性值string'disabled'
leaf指定选项的叶子节点的标志位为选项对象的某个属性值string'leaf'

源代码

组件文档

贡献者