Cascader 级联选择器 ​

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

基础用法 ​

有两种触发子菜单的方式

只需为 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 设置输入框可清空

自定义清除图标2.11.0 ​

你可以通过clear-icon属性自定义清除图标

仅显示最后一级 ​

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

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

多选 ​

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

正确用法：

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

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

错误用法：

vue
<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 对象和当前节点的数据。

自定义建议项2.9.5 ​

你可以通过 suggestion-item 插槽自定义建议项。 你可以在作用域中访问 item，它代表建议项。

级联面板 ​

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

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

自定义标签 2.10.3 ​

您可以自定义标签。

将自定义的标签插入 el-cascader 的 slot 中即可。 collapse-tags, collapse-tags-tooltip, max-collapse-tags 在此模式下不生效.

Using slots allows for more flexible control over the display.

Display top-level tags only

已勾选项显示策略 2.10.5 ​

控制在多选模式下已选值的显示方式。

在多选模式下，你可以使用 show-checked-strategy 来控制已选值的显示方式。 默认策略为 child，即显示所有已选中的子节点。 parent 策略仅在其所有子节点都被选中时显示父节点。

Strategy: child (default, show all selected child nodes)

Strategy: parent (show only parent nodes when all children are selected)

点击选中节点 2.10.5 ​

只使用 multiple 或 checkStrictly 属性。

你可以添加 checkOnClickNode，使节点本身也能被点击（不仅限于前缀图标）。 通过 showPrefix 来切换前缀的显示与隐藏。 :::tip 添加 checkOnClickLeaf 属性可以仅勾选叶子节点（最末级子节点），该功能默认启用。 :::

show prefix

checkStrictly | Single mode

Multiple mode

自定义头部与底部 2.10.5 ​

你可以通过插槽来自定义下拉菜单的头部和底部。

使用插槽自定义内容。

Custom header content

Custom footer content

Cascader API ​

Cascader Attributes ​

属性名说明类型默认值
model-value / v-model选中项绑定值string / number /array—
options选项的数据源， value 和 label 可以通过 CascaderProps 自定义.array—
props配置选项, 请参阅下面 CascaderProps 表。object—
size尺寸enum—
placeholder输入框占位文本string—
disabled是否禁用boolean—
clearable是否支持清空选项boolean—
clear-icon 2.11.0自定义清除图标string / objectCircleClose
show-all-levels输入框中是否显示选中值的完整路径booleantrue
collapse-tags多选模式下是否折叠Tagboolean—
collapse-tags-tooltip当鼠标悬停于折叠标签的文本时，是否显示所有选中的标签。 要使用此属性，collapse-tags属性必须设定为 truebooleanfalse
max-collapse-tags-tooltip-height 2.10.2collapse tags 的最大高度string / number—
separator用于分隔选项的字符string' / '
filterable该选项是否可以被搜索boolean—
filter-method自定义搜索逻辑，第一个参数是node，第二个参数是keyword，返回的布尔值表示是否保留该选项Function—
debounce搜索关键词正在输入时的去抖延迟，单位为毫秒number300
before-filter过滤函数调用前，所要调用的钩子函数，该函数接收要过滤的值作为参数。 如果该函数的返回值是 false 或者是一个被拒绝的 Promise，那么接下来的过滤逻辑便不会执行。Function—
popper-classCascader 下拉菜单和标签提示的自定义类名string''
popper-styleCascader 下拉菜单和标签提示的自定义样式string / object—
teleported弹层是否使用 teleportbooleantrue
effect 2.10.5tooltip 主题，内置了 dark / light 两种enum / stringlight
tag-type标签类型enuminfo
tag-effect 2.7.8tag effectenumlight
validate-event输入时是否触发表单的校验booleantrue
max-collapse-tags 2.3.10需要显示的 Tag 的最大数量 要使用此功能，collapse-tags的值必须为truenumber1
empty-values 2.7.0组件的空值配置， 参考config-providerarray—
value-on-clear 2.7.0清空选项的值， 参考config-providerstring / number / boolean / Function—
persistent 2.7.8当下拉框未被激活并且persistent设置为false，下拉框容器会被删除。booleantrue
fallback-placements 2.8.1Tooltip 可用的 positions 请查看popper.js 文档array—
placement 2.8.1下拉框出现的位置enumbottom-start
popper-append-to-body deprecated是否将弹出的内容直接插入到 body 元素。 在弹出内容的边框定位出现问题时，可将该属性设置为 falsebooleantrue
show-checked-strategy 2.10.5多选模式下已选节点的展示策略。 当你想让显示更简洁时，使用 parent。 当你想显示每个子项时，使用 child。enumchild

Cascader Events ​

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

Cascader Slots ​

插槽名说明Type
default自定义备选项的节点内容，分别为当前节点的 Node 对象和数据object
empty无匹配选项时的内容—
prefix 2.9.4输入框头部内容—
suggestion-item 2.9.5搜索时自定义建议项内容object
tag 2.10.3自定义tag样式object
header 2.10.5下拉列表顶部的内容—
footer 2.10.5下拉列表底部的内容—

Cascader Exposes ​

方法名说明类型
getCheckedNodes获取一个当前选中节点的数组。(仅仅是传单) 是否只返回叶选中的节点，默认是 falseFunction
cascaderPanelRefcascader 面板的 refobject
togglePopperVisible 2.2.31切换 popper 可见状态Function
contentRefcascader 内容的 refobject
presentText 2.8.4选中的内容文本object
focus 2.11.8使 input 获取焦点Function
blur 2.11.8使 input 失去焦点Function

CascaderPanel API ​

CascaderPanel Attributes ​

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

CascaderPanel Events ​

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

CascaderPanel Slots ​

插槽名说明Type
default下级节点的自定义内容，它们分别是当前节点对象和节点数据。object
empty 2.8.3没有数据时面板的内容。—

CascaderPanel Exposes ​

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

CascaderProps ​

属性说明类型默认值
expandTrigger次级菜单的展开方式enumclick
multiple是否多选booleanfalse
checkStrictly是否严格的遵守父子节点不互相关联booleanfalse
emitPath在选中节点改变时，是否返回由该节点所在的各级菜单的值所组成的数组，若设置 false，则只返回该节点的值booleantrue
lazy是否动态加载子节点，需与 lazyLoad 方法结合使用booleanfalse
lazyLoad加载动态数据的方法，仅在 lazy 为 true 时有效 reject 参数在 2.11.5 版本及以上支持。Function—
value指定选项的值为选项对象的某个属性值stringvalue
label指定选项标签为选项对象的某个属性值stringlabel
children指定选项的子选项为选项对象的某个属性值stringchildren
disabled指定选项的禁用为选项对象的某个属性值stringdisabled
leaf指定选项的叶子节点的标志位为选项对象的某个属性值stringleaf
hoverThresholdhover 时展开菜单的灵敏度阈值number500
checkOnClickNode 2.10.5点击节点时是否选中或取消选中该节点booleanfalse
checkOnClickLeaf 2.10.5点击叶子节点（最后一级子节点）时，是否选中或取消选中该节点booleantrue
showPrefix 2.10.5是否显示单选框或复选框的前缀（图标）booleantrue

类型声明 ​

显示类型声明
ts
type CascaderNodeValue = string | number
type CascaderNodePathValue = CascaderNodeValue[]
type CascaderValue =
  | CascaderNodeValue
  | CascaderNodePathValue
  | (CascaderNodeValue | CascaderNodePathValue)[]

type Resolve = (data: any) => void

type ExpandTrigger = 'click' | 'hover'

type LazyLoad = (node: Node, resolve: Resolve, reject: () => void) => void

type isDisabled = (data: CascaderOption, node: Node) => boolean

type isLeaf = (data: CascaderOption, node: Node) => boolean

interface CascaderOption extends Record<string, unknown> {
  label?: string
  value?: CascaderNodeValue
  children?: CascaderOption[]
  disabled?: boolean
  leaf?: boolean
}

interface CascaderProps {
  expandTrigger?: ExpandTrigger
  multiple?: boolean
  checkStrictly?: boolean
  emitPath?: boolean
  lazy?: boolean
  lazyLoad?: LazyLoad
  value?: string
  label?: string
  children?: string
  disabled?: string | isDisabled
  leaf?: string | isLeaf
  hoverThreshold?: number
}

class Node {
  readonly uid: number
  readonly level: number
  readonly value: CascaderNodeValue
  readonly label: string
  readonly pathNodes: Node[]
  readonly pathValues: CascaderNodePathValue
  readonly pathLabels: string[]

  childrenData: ChildrenData
  children: Node[]
  text: string
  loaded: boolean
  /**
   * Is it checked
   *
   * @default false
   */
  checked: boolean
  /**
   * Used to indicate the intermediate state of unchecked and fully checked child nodes
   *
   * @default false
   */
  indeterminate: boolean
  /**
   * Loading Status
   *
   * @default false
   */
  loading: boolean

  // getter
  isDisabled: boolean
  isLeaf: boolean
  valueByOption: CascaderNodeValue | CascaderNodePathValue

  // method
  appendChild(childData: CascaderOption): Node
  calcText(allLevels: boolean, separator: string): string
  broadcast(): void
  emit(): void
  onParentCheck(checked: boolean): void
  onChildCheck(): void
  setCheckState(checked: boolean): void
  doCheck(checked: boolean): void
}

Node as CascaderNode

源代码 ​

组件 • 样式 • 文档

贡献者 ​