Cascader 级联选择器

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

基础用法

有两种方式可以展开子选项。

禁用选项

通过在选项数据中设置 disabled 字段来禁用某个选项。

可清空

为 el-cascader 设置 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>

Don't do

vue

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

选择任意一级选项

在单选模式下，默认只能选择叶子节点，而在多选模式下，勾选父节点会自动选择其所有叶子节点。启用该功能后，父子节点将不再关联，您可以选择任意一级的选项。

动态加载

当选中一个节点时，动态加载其子节点。

可筛选

通过关键字搜索和选择选项。

自定义选项内容

您可以自定义级联选择器节点的内容。

自定义搜索结果列表项 2.9.5

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

级联选择器面板

CascaderPanel 是 Cascader 的核心组件，它具有单选、多选、动态加载等多种功能。

自定义标签 2.10.3

您可以自定义标签。

选中项展示策略 2.10.5

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

点击节点即可选中 2.10.5

仅在使用 multiple 或 checkStrictly 属性时。

您可以添加 checkOnClickNode 属性，以便除了前缀图标外，点击节点也可以选中。
使用 showPrefix 切换前缀的可见性。

添加 checkOnClickLeaf 属性只选中叶子节点（最后一个子节点），默认启用。

自定义页眉和页脚 2.10.5

您可以使用插槽来自定义下拉框的页眉和页脚。

Cascader API

Cascader 属性

名称	描述	类型	默认值
model-value / v-model	绑定值	`string` / `number` /`object`	—
options	选项数据，其中 `value` 和 `label` 的键名可以通过 `CascaderProps` 自定义。	`object`	—
props	配置选项，详见下方的 `CascaderProps` 表格。	`object`	—
size	输入框尺寸	`枚举`	—
占位符	输入框占位文本	`string`	—
disabled	级联选择器是否被禁用	`boolean`	—
可清空	选中值是否可以被清除	`boolean`	—
清除图标 2.11.0	自定义清除图标组件	`string` / `object`	CircleClose
show-all-levels	输入框中是否显示选中值的完整路径	`boolean`	true
collapse-tags	多选模式下是否折叠标签	`boolean`	—
collapse-tags-tooltip	当鼠标悬停于折叠标签的文本时，是否显示所有选中的标签。要使用此属性，`collapse-tags` 属性必须设定为 true	`boolean`	false
max-collapse-tags-tooltip-height 2.10.2	折叠标签的工具提示的最大高度。	`string` / `number`	—
separator	选项标签的分隔符	`string`	' / '
filterable	选项是否可以被搜索	`boolean`	—
filter-method	自定义搜索逻辑，第一个参数是 `node`，第二个是 `keyword`，需要返回一个布尔值表示是否命中。	`Function`	—
防抖	输入筛选关键词时的防抖延迟，单位为毫秒	`number`	300
before-filter	筛选之前的钩子函数，参数为将要被筛选的值。如果返回 `false` 或一个被拒绝的 `Promise`，则筛选将被终止。	`Function`	—
popper-class	级联选择器下拉框和标签工具提示的自定义类名	`string`	''
popper-style	级联选择器下拉框和标签工具提示的自定义样式	`string` / `object`	—
teleported	级联选择器弹窗是否被 teleport	`boolean`	true
effect 2.10.5	tooltip 主题，内置主题：`dark` / `light`	`enum` / `string`	light
tag-type	标签类型	`枚举`	信息
tag-effect 2.7.8	标签效果	`枚举`	light
validate-event	是否触发表单验证	`boolean`	true
max-collapse-tags 2.3.10	要显示的最大标签数。要使用此属性，`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 的可能位置列表 popper.js	`array`	—
placement 2.8.1	下拉框出现的位置	`枚举`	下左
popper-append-to-body 已弃用	是否将 popper 菜单附加到 body。如果 popper 的定位错误，可以尝试将此属性设置为 false	`boolean`	true
show-checked-strategy 2.10.5	多选模式下显示选中节点的策略。当您希望整洁时使用 `parent`。当每个单独的项目都很重要时使用 `child`	`枚举`	child

Cascader 事件

名称	描述	类型
change	当绑定值变化时触发	`Function`
expand-change	当展开选项变化时触发	`Function`
blur	当级联选择器失焦时触发	`Function`
focus	当级联选择器聚焦时触发	`Function`
clear 2.7.7	在可清空的 Select 组件上点击清除图标时触发	`Function`
visible-change	下拉框出现/隐藏时触发	`Function`
remove-tag	多选模式下移除标签时触发	`Function`

Cascader 插槽

名称	描述	类型
default	级联选择器节点的自定义内容，参数分别为当前节点对象和节点数据。	`object`
empty	没有匹配选项时的内容。	—
prefix 2.9.4	作为输入框前缀的内容	—
suggestion-item 2.9.5	搜索时建议项的自定义内容	`object`
tag 2.10.3	自定义标签样式	`object`
header 2.10.5	下拉列表顶部的内容	—
footer 2.10.5	下拉列表底部的内容	—

Cascader Exposes

名称	描述	类型
getCheckedNodes	获取当前选中节点的数组，(leafOnly) 是否只返回叶子选中节点，默认为 `false`	`Function`
cascaderPanelRef	级联选择器面板引用	`object`
togglePopperVisible 2.2.31	切换 popper 的可见类型	`Function`
contentRef	级联选择器内容引用	`object`
presentText 2.8.4	选中内容的文本	`object`
focus 2.11.8	使输入框元素聚焦	`Function`
blur 2.11.8	使输入框元素失焦	`Function`

CascaderPanel API

CascaderPanel 属性

名称	描述	类型	默认值
model-value / v-model	绑定值	`string`/`number`/`object`	—
options	选项数据，其中 `value` 和 `label` 的键名可以通过 `CascaderProps` 自定义。	`object`	—
props	配置选项，详见下方的 `CascaderProps` 表格。	`object`	—

CascaderPanel 事件

名称	描述	类型
change	当绑定值变化时触发	`Function`
update:modelValue	当绑定值变化时触发	`Function`
expand-change	当展开选项变化时触发	`Function`
关闭	关闭面板事件，提供给 Cascader 用于收起面板的判断。	`Function`

CascaderPanel 插槽

名称	描述	类型
default	级联选择器节点的自定义内容，参数分别为当前节点对象和节点数据。	`object`
empty 2.8.3	没有数据时面板的内容。	—

CascaderPanel Exposes

名称	描述	类型
getCheckedNodes	获取当前选中节点的数组，(leafOnly) 是否只返回叶子选中节点，默认为 `false`	`Function`
clearCheckedNodes	清除选中的节点	`Function`

CascaderProps

属性	描述	类型	默认值
expandTrigger	展开选项的触发方式	`枚举`	click
multiple	是否启用多选	`boolean`	false
checkStrictly	节点的选中状态是否不影响其父子节点	`boolean`	false
emitPath	当选中节点变化时，是否发出一个节点路径数组，如果为 false，则只发出节点的值。	`boolean`	true
lazy	是否动态加载子节点，与 `lazyload` 属性一起使用	`boolean`	false
lazyLoad	加载子节点数据的方法，仅在 `lazy` 为 true 时有效。版本 2.11.5 后支持 reject 参数。	`Function`	—
value	指定节点对象的哪个键用作节点的值	`string`	value
label	指定节点对象的哪个键用作节点的标签	`string`	label
children	指定节点对象的哪个键用作节点的子节点	`string`	children
disabled	指定节点对象的哪个键用作节点的禁用	`string`	disabled
leaf	指定节点对象的哪个键用作节点的叶子字段	`string`	leaf
hoverThreshold	展开选项的悬停阈值	`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