2.11.1

Cascader 级联选择器 ​

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

基础用法 ​

这里我们提供了两种触发方式

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

点击时展开子级菜单 (默认)

鼠标悬浮时展开子级菜单

禁用选项 ​

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

在本例中，`options` 数组的第一个项目有一个 `disabled: true` 字段，因此它是禁用的。默认情况下，级联选择器会检查每个选项对象中的 `disabled` 字段；如果您正在使用另一个字段名来指示选项是否被禁用，您可以在 `props.disabled` 属性中指定它（详情请参见下面的API表）。当然，字段名 `value`、`label` 和 `children` 也可以以同样的方式进行自定义。

可清空 ​

为 `el-cascader` 设置 `clearable` 属性，则当选中并悬浮时会出现一个清除图标。

自定义清除图标 2.11.0 ​

您可以通过设置 `clear-icon` 属性来自定义清除图标。

仅显示最后一级 ​

可以仅在输入框中显示选中值的最后一级，而不是显示所有级别。

`show-all-levels` 属性定义是否显示所有级别。如果为 `false`，则只显示最后一级。

多选 ​

在标签中添加 `:props="props"` 并设置数据 `props = { multiple: true }` 来使用多选。

Do

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>

在使用多选时，默认会显示所有选中的标签。您可以设置 `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` 即可启用过滤功能。级联选择器将匹配标签或父级标签（根据 `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` 仅选中叶子节点（最后的子节点），默认启用。

显示前缀

checkStrictly | 单选模式

多选模式

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

使用插槽来自定义内容。

自定义页眉内容

自定义页脚内容

Cascader API ​

Cascader 属性 ​

名称描述类型默认值
model-value / v-model绑定值string / number—
options选项的数据，`value` 和 `label` 的键可以通过 `CascaderProps` 自定义。object—
props配置选项，请参见下面的 `CascaderProps` 表。object—
size输入框尺寸枚举—
占位符输入框占位文本string—
disabledCascader 是否禁用boolean—
可清空选中值是否可以清除boolean—
清除图标 2.11.0自定义清除图标组件string / objectCircleClose
show-all-levels是否在输入框中显示选中值的所有级别booleantrue
collapse-tags在多选模式下是否折叠标签boolean—
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—
防抖输入过滤关键词时的防抖延迟，单位为毫秒number300
before-filter过滤前的钩子函数，参数为要过滤的值。如果返回 `false` 或返回一个被拒绝的 `Promise`，则过滤将被中止。Function—
popper-classCascader 下拉菜单的自定义类名string''
popper-styleCascader 下拉菜单的自定义样式string / object—
teleportedcascader 弹出框是否被传送booleantrue
effect 2.10.5tooltip 主题，内置主题：`dark` / `light`enum / stringlight
tag-type标签类型枚举信息
tag-effect 2.7.8标签效果枚举light
validate-event是否触发表单验证booleantrue
max-collapse-tags 2.3.10要显示的最大标签数。要使用此项，`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 可能的位置列表 popper.jsarray—
placement 2.8.1下拉框出现的位置枚举下左
popper-append-to-body 已弃用是否将 popper 菜单附加到 body。如果 popper 的定位错误，可以尝试将此属性设置为 false。booleantrue
show-checked-strategy 2.10.5多选模式下显示已选中节点的策略。当你希望整洁时使用`parent`。当每个项目都很重要时，使用`child`。枚举child

Cascader 事件 ​

名称描述类型
change当绑定值改变时触发Function
expand-change当展开选项改变时触发Function
blur当 Cascader 失去焦点时触发Function
focus当 Cascader 获得焦点时触发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
cascaderPanelRefcascader 面板 refobject
togglePopperVisible 2.2.31切换 popper 的可见类型Function
contentRefcascader 内容 refobject
presentText 2.8.4选中的内容文本object

CascaderPanel API ​

CascaderPanel 属性 ​

名称描述类型默认值
model-value / v-model绑定值string/number—
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是否启用多选booleanfalse
checkStrictly节点的选中状态是否不影响其父节点和子节点booleanfalse
emitPath当选中节点改变时，是否发出一个节点路径的数组，如果为 false，只发出节点的值。booleantrue
lazy是否动态加载子节点，与`lazyload`属性一起使用booleanfalse
lazyLoad加载子节点数据的方法，仅当`lazy`为 true 时有效Function—
value指定节点对象的哪个键用作节点的值stringvalue
label指定节点对象的哪个键用作节点的标签stringlabel
children指定节点对象的哪个键用作节点的子节点stringchildren
disabled指定节点对象的哪个键用作节点的禁用stringdisabled
leaf指定节点对象的哪个键用作节点的叶子字段stringleaf
hoverThreshold展开选项的悬停阈值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) => 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

来源 ​

组件 • 样式 • 文档

贡献者 ​