vue element plus Cascader 级联选择器

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

TIP

在 SSR 场景下，您需要将组件包裹在 <client-only></client-only> 之中 (如: Nuxt) 和 SSG (e.g: VitePress).

基础用法#

有两种触发子菜单的方式

只需为 Cascader 的options属性指定选项数组即可渲染出一个级联选择器。 通过 props.expandTrigger 属性控制子节点的展开方式

Child options expand when clicked (default)

Child options expand when hovered

有禁用选项#

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

本例中，options指定的数组中的第一个元素含有disabled: true键值对，因此是禁用的。 在默认情况下，Cascader 会检查数据中每一项的disabled字段是否为true，如果你的数据中表示禁用含义的字段名不为disabled，可以通过props.disabled属性来指定（详见下方 API 表格）。 当然，value、label和children这三个字段名也可以通过同样的方式指定。

可清空#

通过 clearable 设置输入框可清空

仅显示最后一级#

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

属性show-all-levels定义了是否显示完整的路径，将其赋值为false则仅显示最后一级 将其赋值为 false 则仅显示最后一级。

多选#

在标签中添加 :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>

使用多选时，所有选中的标签将默认显示。 您可以设置 collapse = true 将选中的标签折叠。 您可以设置 max-collapse-tags 来显示最大tag数量，默认1。 您可以使用 collapse-tags-tooltip 属性来启用鼠标悬停折叠文字以显示具体所选值的行为。

Display all tags (default)

Collapse tags

Collapse tags tooltip

Max Collapse Tags

选择任意一级选项#

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

可通过 props.checkStrictly = true 来设置父子节点取消选中关联，从而达到选择任意一级选项的目的。

Select any level of options (Single selection)

Select any level of options (Multiple selection)

动态加载#

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

通过lazy开启动态加载，并通过lazyload来设置加载数据源的方法。 lazyload方法有两个参数，第一个参数node为当前点击的节点，第二个resolve为数据加载完成的回调(必须调用)。 为了更准确的显示节点的状态，还可以对节点数据添加是否为叶子节点的标志位 (默认字段为leaf，可通过props.leaf修改)。 否则，将以有无子节点来判断其是否为叶子节点。

可搜索#

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

通过添加filterable来启用过滤。 Cascader 会匹配所有节点的标签和它们的亲节点的标签，是否包含有输入的关键字。 你也可以用filter-method自定义搜索逻辑，接受一个函数，第一个参数是节点node，第二个参数是搜索关键词keyword，通过返回布尔值表示是否命中。

Filterable (Single selection)

Filterable (Multiple selection)

自定义节点内容#

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

你可以通过 scoped slot 自定义节点的内容。 您可以访问 scope 中的 node 和 data 属性，分别表示当前节点的 Node 对象和当前节点的数据。

级联面板#

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

和级联选择器一样，通过 options 来指定选项，也可通过 props 来设置多选、动态加载等功能，具体详情见下方API表格。

• Guide
• Component
• Resource

Cascader API#

Cascader Attributes#

属性名	说明	类型	默认值
model-value / v-model	选中项绑定值	string/number/object	—
options	选项的数据源， value 和 label 可以通过 CascaderProps 自定义.	object	—
props	配置选项, 请参阅下面 CascaderProps 表。	object	—
size	尺寸	enum	—
placeholder	输入框占位文本	string	—
disabled	是否禁用	boolean	—
clearable	是否支持清空选项	boolean	—
show-all-levels	输入框中是否显示选中值的完整路径	boolean	true
collapse-tags	多选模式下是否折叠Tag	boolean	—
collapse-tags-tooltip	当鼠标悬停于折叠标签的文本时，是否显示所有选中的标签。 要使用此属性，collapse-tags属性必须设定为 true	boolean	false
separator	用于分隔选项的字符	string	' / '
filterable	该选项是否可以被搜索	boolean	—
filter-method	自定义搜索逻辑，第一个参数是node，第二个参数是keyword，返回的布尔值表示是否保留该选项	Function	—
debounce	搜索关键词正在输入时的去抖延迟，单位为毫秒	number	300
before-filter	过滤函数调用前，所要调用的钩子函数，该函数接收要过滤的值作为参数。 如果该函数的返回值是 false 或者是一个被拒绝的 Promise，那么接下来的过滤逻辑便不会执行。	Function	—
popper-class	弹出内容的自定义类名	string	''
teleported	弹层是否使用 teleport	boolean	true
popper-append-to-body deprecated	是否将弹出的内容直接插入到 body 元素。 在弹出内容的边框定位出现问题时，可将该属性设置为 false	boolean	true
tag-type	标签类型	enum	info
validate-event	输入时是否触发表单的校验	boolean	true
max-collapse-tags 2.3.10	需要显示的 Tag 的最大数量 只有当 collapse-tags 设置为 true 时才会生效。	number	1

Cascader Events#

事件名	说明	类型
change	当绑定值变化时触发的事件	Function
expand-change	当展开节点发生变化时触发	Function
blur	当失去焦点时触发	Function
focus	当获得焦点时触发	Function
visible-change	下拉框出现/隐藏时触发	Function
remove-tag	在多选模式下，移除Tag时触发	Function

Cascader Slots#

插槽名	说明	作用域
default	自定义备选项的节点内容，分别为当前节点的 Node 对象和数据	object
empty	无匹配选项时的内容	—

Cascader Exposes#

属性名	说明	类型
getCheckedNodes	获取一个当前选中节点的数组。(仅仅是传单) 是否只返回叶选中的节点，默认是 false	Function
cascaderPanelRef	cascader 面板的 ref	object
togglePopperVisible 2.2.31	切换 popper 可见状态	Function
contentRef	cascader 内容的 ref	object

CascaderPanel API#

CascaderPanel Attributes#

属性名	说明	类型	默认值
model-value / v-model	选中项绑定值	string/number/object	—
options	选项的数据源， value 和 label 可以通过 CascaderProps 自定义.	object	—
props	配置选项, 请参阅下面 CascaderProps 表。	object	—

CascaderPanel Events#

事件名	说明	Type
change	当选中节点变化时触发	Function
expand-change	当展开节点发生变化时触发	Function
close	面板的关闭事件，提供给 Cascader 以便做更好的判断。	Function

CascaderPanel Slots#

插槽名	说明	Scope
default	下级节点的自定义内容，它们分别是当前节点对象和节点数据。	object

CascaderPanel Exposes#

属性名	说明	Type
getCheckedNodes	获取一个当前选中节点的数组。(仅仅是传单) 是否只返回叶选中的节点，默认是 false	Function
clearCheckedNodes	清空选中的节点	Function

CascaderProps#

属性	说明	类型	默认值
expandTrigger	次级菜单的展开方式	enum	click
multiple	是否多选	boolean	false
checkStrictly	是否严格的遵守父子节点不互相关联	boolean	false
emitPath	在选中节点改变时，是否返回由该节点所在的各级菜单的值所组成的数组，若设置 false，则只返回该节点的值	boolean	true
lazy	是否动态加载子节点，需与 lazyLoad 方法结合使用	boolean	false
lazyLoad	加载动态数据的方法，仅在 lazy 为 true 时有效	Function	—
value	指定选项的值为选项对象的某个属性值	string	value
label	指定选项标签为选项对象的某个属性值	string	label
children	指定选项的子选项为选项对象的某个属性值	string	children
disabled	指定选项的禁用为选项对象的某个属性值	string	disabled
leaf	指定选项的叶子节点的标志位为选项对象的某个属性值	string	leaf
hoverThreshold	hover 时展开菜单的灵敏度阈值	number	500

类型声明#

显示类型声明

源代码#

组件 • 文档