Cascader 级联选择器

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

基础用法

有两种触发子菜单的方式

有禁用选项

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

可清空

通过 clearable 设置输入框可清空

自定义清除图标2.11.0

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

仅显示最后一级

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

多选

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

选择任意一级选项

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

动态加载

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

可搜索

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

自定义节点内容

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

自定义建议项2.9.5

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

级联面板

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

自定义标签 2.10.3

您可以自定义标签。

已勾选项显示策略 2.10.5

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

点击选中节点 2.10.5

只使用 multiple 或 checkStrictly 属性。

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

自定义头部与底部 2.10.5

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

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

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	获取一个当前选中节点的数组。(仅仅是传单) 是否只返回叶选中的节点，默认是 `false`	`Function`
cascaderPanelRef	cascader 面板的 ref	`object`
togglePopperVisible 2.2.31	切换 popper 可见状态	`Function`
contentRef	cascader 内容的 ref	`object`
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`/`object`	—
options	选项的数据源， `value` 和 `label` 可以通过 `CascaderProps` 自定义.	`object`	—
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	获取一个当前选中节点的数组。(仅仅是传单) 是否只返回叶选中的节点，默认是 `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 时有效 reject 参数在 2.11.5 版本及以上支持。	`Function`	—
value	指定选项的值为选项对象的某个属性值	`string`	value
label	指定选项标签为选项对象的某个属性值	`string`	label
children	指定选项的子选项为选项对象的某个属性值	`string`	children
disabled	指定选项的禁用为选项对象的某个属性值	`string`	disabled
leaf	指定选项的叶子节点的标志位为选项对象的某个属性值	`string`	leaf
hoverThreshold	hover 时展开菜单的灵敏度阈值	`number`	500
checkOnClickNode 2.10.5	点击节点时是否选中或取消选中该节点	`boolean`	false
checkOnClickLeaf 2.10.5	点击叶子节点（最后一级子节点）时，是否选中或取消选中该节点	`boolean`	true
showPrefix 2.10.5	是否显示单选框或复选框的前缀（图标）	`boolean`	true

类型声明

显示类型声明

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