2.14.0

Cascader 级联选择器 ​

当选项有较好的层级结构时，可以使用 Cascader 级联选择器进行查看和选择。

基础用法 ​

有两种触发子级的方式。

通过 options 属性指定选项数组即可渲染出一个级联选择器。 通过 props.expandTrigger 可以定义展开子级菜单的触发方式。

点击触发（默认）

悬停触发

禁用选项 ​

通过在选项对象中设置 disabled 字段来禁用该选项。

在本例中，options 数组的第一个元素包含 disabled: true 字段，因此它被禁用。 默认情况下，Cascader 会检查每个选项对象中的 disabled 字段；如果您使用其他字段名来表示选项是否禁用，可以在 props.disabled 属性中指定（详情请参阅下面的 API 表）。 当然，value、label 和 children 的字段名也可以用同样的方式自定义。

可清空 ​

为 el-cascader 设置 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-tags = true 来折叠已选标签。 您可以设置 max-collapse-tags 来显示最大标签数量，默认为 1。 当鼠标悬停在折叠文本上时，可以使用 collapse-tags-tooltip 属性查看它们。

显示所有标签（默认）

折叠标签

折叠标签提示

最大折叠标签数

选择任意一级选项 ​

在单选模式下，只能选择叶子节点，而在多选模式下，选择父节点最终会导致选择叶子节点。 开启该功能后，可以使父子节点解耦，从而选择任意一级的选项。

设置 props.checkStrictly = true 可使节点的选中状态不影响其父节点和子节点，从而可以选择任意一级的选项。

选择任意一级选项（单选）

选择任意一级选项（多选）

动态加载 ​

选中节点时动态加载其子节点。

设置 lazy = true 来开启动态加载，您需要通过 lazyload 来指定如何加载数据源。 lazyload 有两个参数，第一个参数 node 是当前点击的节点，resolve 是一个必须调用的回调函数，表示加载已完成。 为了更准确地显示节点状态，您可以添加 leaf 字段（可通过 props.leaf 修改）来指示它是否为叶子节点。 否则，将通过是否具有子节点来推断。

可筛选 ​

使用关键字搜索并选择选项。

在 el-cascader 中添加 filterable 即可开启过滤。 Cascader 会匹配标签或父级标签（根据 show-all-levels）包含输入关键字的节点。 当然，您可以通过 filter-method 自定义搜索逻辑，它接受一个函数，第一个参数是 node，第二个参数是 keyword，需要返回一个布尔值指示是否匹配。

可搜索（单选）

可搜索（多选）

自定义节点内容 ​

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

您可以通过 scoped slot 自定义级联选择器节点的内容。 您可以在作用域中访问 node 和 data，分别代表当前节点的 Node 对象和节点数据。

自定义搜索建议内容 2.9.5 ​

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

级联面板 ​

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

与 el-cascader 一样，您可以通过 options 设置备选项，并通过 props 开启其他功能，详情请参阅下方的 API 表。

自定义标签 2.10.3 ​

您可以自定义标签。

在 el-cascader 的插槽中插入自定义标签。 collapse-tags、collapse-tags-tooltip、max-collapse-tags 将不再起作用。

使用插槽可以实现更灵活的显示控制。

仅显示顶级标签

选中值显示策略 2.10.5 ​

控制在多选模式下如何显示选中值。

在多选模式下，您可以使用 show-checked-strategy 来控制如何显示选中值。 默认策略是 child，显示所有选中的子节点。 parent 策略则在选中所有子节点时仅显示父节点。

策略：child（默认，显示所有选中的子节点）

策略：parent（当所有子节点都被选中时仅显示父节点）

点击节点即选中 2.10.5 ​

仅在使用 multiple 或 checkStrictly 属性时有效。

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

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

显示前缀

严格检查 | 单选模式

多选模式

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

使用插槽来自定义内容。

自定义页眉内容

自定义页脚内容

虚拟滚动 2.14.0 ​

处理大量数据时，可以开启虚拟滚动以提高性能。

将 virtual-scroll 设置为 true 以开启虚拟滚动。 您还可以通过 height 自定义菜单高度，通过 item-size 自定义节点高度。 默认高度为 204px，默认项目大小为 34px。

自定义搜索建议宽度 2.14.0 ​

默认情况下，建议面板（过滤时）的宽度是根据匹配选项的最大宽度计算的。 如果您通过 suggestion-item 插槽自定义了建议选项，选项中显示的文本很可能不等于 label 的值，从而导致计算错误。 在这种情况下，您可以使用 fit-input-width 属性来固定其宽度。 当值为 number 时，宽度为特定的固定像素值。

提示

fit-input-width 属性仅控制搜索期间建议面板的宽度，不会影响默认的级联面板。

Cascader API ​

Cascader 属性 ​

名称描述类型默认值
model-value / v-model绑定值string / number /array—
options可选项的数据源，value 和 label 的键名可以通过 CascaderProps 自定义。array—
props配置选项，请参阅下方的 CascaderProps 表。object—
size输入框尺寸枚举—
占位符输入框占位文本string—
disabled级联选择器是否禁用boolean—
可清空是否可以清空已选项boolean—
清除图标 2.11.0自定义清除图标组件string / objectCircleClose
显示完整路径输入框中是否显示选中值的完整路径booleantrue
collapse-tags多选模式下是否折叠标签boolean—
折叠标签提示当鼠标悬停于折叠标签的文本时，是否显示所有选中的标签。 要使用此属性，`collapse-tags` 属性必须设定为 truebooleanfalse
折叠标签提示的最大高度 2.10.2折叠标签提示的最大高度。string / number—
separator选项标签分隔符string' / '
filterable是否可搜索选项boolean—
filter-method自定义搜索逻辑，第一个参数是 node，第二个参数是 keyword，需要返回一个布尔值指示是否匹配。Function—
防抖输入过滤关键字时的去抖延迟，单位为毫秒number300
筛选前钩子筛选前的钩子函数，参数为搜索关键词。 若返回 false 或者返回 Promise 且被 reject，则停止筛选Function—
popper-class级联选择器下拉菜单和标签提示的自定义类名string''
popper-style级联选择器下拉菜单和标签提示的自定义样式string / object—
teleported级联选择器弹窗是否使用 teleportbooleantrue
效应/主题 2.10.5tooltip 主题，内置主题：`dark` / `light`enum / stringlight
tag-type标签类型枚举信息
标签效应/主题 2.7.8标签效果枚举light
validate-event是否触发表单验证booleantrue
最大折叠标签数 2.3.10显示的最大标签数。 必须设置 collapse-tags 为 true 才能使用number1
empty-values 2.7.0组件的空值，请参阅 config-providerarray—
value-on-clear 2.7.0清空时的返回值，请参阅 config-providerstring / number / boolean / Function—
持久化 2.7.8当下拉菜单不活动且 persistent 为 false 时，下拉菜单将被销毁booleantrue
备用位置 2.8.1文字提示可能出现的位置列表 popper.jsarray—
位置 2.8.1下拉框出现的位置枚举下左
popper-append-to-body 已弃用是否将弹出菜单附加到 body。 如果弹出框定位错误，可以尝试将此属性设置为 falsebooleantrue
选中项显示策略 2.10.5多选模式下显示选中节点的策略。 需要整洁时使用 parent。 当每一项都很重要时，使用 child枚举子节点
虚拟滚动 2.14.0是否针对大数据开启虚拟滚动booleanfalse
适应输入框宽度 2.14.0建议面板的宽度是否与输入框一致，如果值为 number，则宽度固定boolean / numberfalse
项目大小 2.14.0虚拟滚动时的节点高度 (px)number34
高度 2.14.0虚拟滚动时的菜单高度 (px)number204

Cascader 事件 ​

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

Cascader 插槽 ​

名称描述类型
default自定义级联节点的内容，参数分别为当前的 Node 对象和节点数据。object
empty无匹配选项时的内容。—
前缀 2.9.4作为输入框前缀的内容—
建议项 2.9.5搜索时建议项的自定义内容object
标签 2.10.3自定义标签样式object
页眉 2.10.5下拉列表顶部的内容—
页脚 2.10.5下拉列表底部的内容—

Cascader 暴露的属性和方法 ​

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

CascaderPanel API ​

CascaderPanel 属性 ​

名称描述类型默认值
model-value / v-model绑定值string/number/array—
options可选项的数据源，value 和 label 的键名可以通过 CascaderProps 自定义。array—
props配置选项，请参阅下方的 CascaderProps 表。object—
虚拟滚动 2.14.0是否针对大数据开启虚拟滚动booleanfalse
项目大小 2.14.0虚拟滚动时的节点高度 (px)number34
高度 2.14.0虚拟滚动时的菜单高度 (px)number204

CascaderPanel 事件 ​

名称描述类型
change当绑定值变化时触发Function
更新绑定的值当绑定值变化时触发Function
expand-change当展开节点发生变化时触发Function
关闭关闭面板事件，提供给 Cascader 用于收起面板的判断。Function

CascaderPanel 插槽 ​

名称描述类型
default自定义级联节点的内容，参数分别为当前的 Node 对象和节点数据。object
空状态 2.8.3无数据时面板的内容。—

CascaderPanel 暴露的属性和方法 ​

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

CascaderProps ​

属性描述类型默认值
次级菜单的展开方式次级菜单的展开方式触发模式枚举click
multiple是否开启多选booleanfalse
任意一级选中是否严格遵守父子节点不互相关联，从而可以选择任意一级booleanfalse
是否返回完整路径在选中节点改变时，是否返回由该节点所有父节点组成的数组，若为 false，则只返回该节点的值booleantrue
lazy是否动态加载子节点，需与 lazyload 属性结合使用booleanfalse
加载子节点的方法加载子节点数据的方法，仅在 lazy 为 true 时有效。 自版本 2.11.5 起支持 reject 参数。Function—
value指定节点对象的哪个键用作节点的值stringvalue
label指定节点对象的哪个键用作节点的标签stringlabel
children指定节点对象的哪个键用作节点的子节点stringchildren
disabled指定节点对象的哪个键用作节点的禁用stringdisabled
叶子节点标识指定哪个键名作为节点的叶子节点标识string叶子节点标识
悬停阈值展开选项的悬停阈值number500
点击节点即选中 2.10.5是否在点击节点时选中或取消选中该节点booleanfalse
点击叶子节点即选中 2.10.5是否在点击叶子节点（最后的子节点）时选中或取消选中节点。booleantrue
显示前缀 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

来源 ​

组件 • 样式 • 文档

贡献者 ​