级联 ​

如果选项具有清晰的层次结构,可以使用Cascader来查看和选择它们。

基本用法 ​

子选项统一通过点按展开。

将 options 属性分配给选项数组会呈现 Cascader。el-cascader 会固定使用点按展开,并保持当前激活的菜单列可见。

服务路径逐级轻触展开选项

展开后会自动滚动到当前的最新一列。

禁用选项 ​

通过在选项对象中设置 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。

显示全部标签,默认模式

折叠标签

折叠标签并展示提示

最大折叠标签数

选择任意级别的选项 ​

单选时只能检查叶子节点,多选时检查父节点最终会导致检查叶子节点。启用此功能后,可以使父子节点解除链接,并且可以选择任意级别的选项。

设置 props.checkStrictly = true 使节点的选中状态不影响其父节点和子节点,然后可以选择任意级别的选项。

任意层级可选,单选模式

任意层级可选,多选模式

动态加载 ​

当检查节点时动态加载其子节点。

设置lazy = true使用动态加载,并且您必须通过lazyload指定如何加载数据源。 lazyload有两个参数,第一个参数node是当前点击的节点,resolve是加载完成的回调,必须调用。为了更准确地显示节点的状态,可以添加leaf字段(可通过props.leaf修改)来指示是否为叶子节点。否则,将通过是否有子节点来推断。

可过滤 ​

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

将 filterable 添加到 el-cascader 即可启用过滤。 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 以仅检查叶节点(最后一个子节点),默认启用。

显示前缀

`checkStrictly` 单选模式

多选模式

自定义页眉和页脚 2.10.5 ​

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

使用插槽自定义内容。

级联 API ​

级联属性 ​

名称描述类型默认
模型值 / v 模型绑定值字符串 / 数字 /数组—
选项选项数据,value 和 label 的密钥可以由 CascaderProps 自定义。数组—
道具配置选项见下面CascaderProps表。对象—
尺寸输入大小枚举—
占位符输入的占位符字符串—
已禁用Cascader 是否被禁用布尔值—
可清除是否可以清除所选值布尔值—
清除图标 2.11.0自定义透明图标组件字符串 / 对象圆圈关闭
显示所有级别是否显示输入中所选值的所有级别布尔值真实
折叠标签多选模式下是否折叠标签布尔值—
折叠标签工具提示是否在折叠标签摘要中显示所有已选标签。要使用此功能,collapse-tags 必须为 true布尔值假
最大折叠标签工具提示高度 2.10.2折叠标签工具提示的最大高度。字符串 / 数字—
分隔符选项标签分隔符字符串' / '
可过滤是否可以搜索选项布尔值—
过滤方法自定义搜索逻辑,第一个参数是node,第二个参数是keyword,需要返回一个布尔值表示是否命中。功能—
去抖输入过滤器关键字时的去抖延迟(以毫秒为单位) 数字300300
过滤前过滤前的钩子函数,以要过滤的值作为参数。如果返回false或者返回Promise然后被拒绝,过滤将被中止功能—
波普尔级Cascader 下拉菜单和标签工具提示的自定义类名字符串''
波普风格Cascader 下拉菜单和标签工具提示的自定义样式字符串 / 对象—
标签类型标签类型枚举信息
标签效果 2.7.8标签效果枚举光
验证事件是否触发表单验证布尔值真实
最大折叠标签 2.3.10要显示的最大标签数。要使用此功能,collapse-tags 必须为 true数字1
空值 2.7.0组件的空值,参见配置提供程序数组—
清除值 2.7.0清除返回值,参见配置提供程序字符串 / 数字 / 布尔值 / 函数—
持久 2.7.8当下拉列表处于非活动状态且 persistent 为 false 时,下拉列表将被销毁布尔值真实
显示检查策略 2.10.5在多选模式下显示选中节点的策略。当您想要整洁时,请使用 parent。当每一项都很重要时,请使用 child枚举孩子

级联事件 ​

名称描述类型
改变绑定值改变时触发功能
扩展-更改展开选项更改时触发功能
模糊Cascader 模糊时触发功能
焦点Cascader 聚焦时触发功能
清除 2.7.7在可清除的 Select中单击清除图标时触发功能
可见变化当下拉菜单出现/消失时触发功能
删除标签多选模式下删除标签时触发功能

级联插槽 ​

名称描述类型
默认Cascader节点的自定义内容,分别是当前Node对象和节点数据。对象
空没有匹配选项时的内容。—
前缀 2.9.4内容作为输入前缀—
建议项 2.9.5搜索时建议项目的自定义内容对象
标签 2.10.3自定义标签样式对象
标头 2.10.5下拉菜单顶部的内容—
页脚 2.10.5下拉菜单底部的内容—

级联暴露 ​

名称描述类型
获取已检查节点获取当前选中节点的数组,(leafOnly) 是否只返回叶子选中的节点,默认为 false功能
级联面板参考级联面板参考对象
切换波普可见 2.2.31切换 popper 的可见类型功能
内容参考级联内容参考对象
当前文本 2.8.4选定的内容文本对象
焦点 2.11.8聚焦输入元素功能
模糊 2.11.8模糊输入元素功能

CascaderPanel API ​

CascaderPanel 属性 ​

名称描述类型默认
模型值 / v 模型绑定值字符串/数字/数组—
选项选项数据,value 和 label 的密钥可以由 CascaderProps 自定义。数组—
道具配置选项见下面CascaderProps表。对象—

CascaderPanel 事件 ​

名称描述类型
改变绑定值改变时触发功能
更新:模型值绑定值改变时触发功能
扩展-更改展开选项更改时触发功能
关闭close panel事件,提供给Cascader收起panel的判断。功能

CascaderPanel 插槽 ​

名称描述类型
默认Cascader节点的自定义内容,分别是当前Node对象和节点数据。对象
空 2.8.3没有数据时面板的内容。—

CascaderPanel 暴露 ​

名称描述类型
获取已检查节点获取当前选中节点的数组,(leafOnly) 是否只返回叶子选中的节点,默认为 false功能
清除已检查节点清除选中的节点功能

CascaderProps ​

| 属性 | 描述 | 类型 | 默认 | | -------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------ | --- | | 展开触发 | 扩展选项触发方式。el-cascader 始终使用 click;直接使用 CascaderPanel 时该选项仍可生效。 | 枚举 | 点击 | | 多个 | 是否启用多选 | 布尔值 | 假 | | 严格检查 | 节点的检查状态是否不影响其父节点和子节点 | 布尔值 | 假 | | 发出路径 | 当检查的节点发生变化时,是否发出节点路径数组,如果为 false,则仅发出节点的值。 | 布尔值 | 真实 | | 懒惰 | 是否动态加载子节点,与lazyload属性一起使用 | 布尔值 | 假 | | 延迟加载 | 加载子节点数据的方法,仅在 lazy 为 true 时有效。 2.11.5版本之后支持reject参数。 | 功能 | — | | 价值 | 指定节点对象的哪个键用作节点的值 | 字符串 | 价值 | | 标签 | 指定节点对象的哪个键用作节点的标签 | 字符串 | 标签 | | 儿童 | 指定节点对象的哪个键用作节点的子节点 | 字符串 | 儿童 | | 已禁用 | 指定节点对象的哪个键用作节点的禁用 | 字符串 | 已禁用 | | 叶 | 指定节点对象的哪个键用作节点的叶字段 | 字符串 | 叶 | | 悬停阈值 | 当 CascaderPanel 配置为悬停展开时使用的阈值 | 数字 | 500 | 500 | | checkOnClickNode 2.10.5 | 单击节点时是否选中或取消选中节点 | 布尔值 | 假 | | checkOnClickLeaf 2.10.5 | 单击叶节点(最后一个子节点)时是否选中或取消选中节点。 | 布尔值 | 真实 | | 显示前缀 2.10.5 | 是否显示单选或复选框前缀 | 布尔值 | 真实 |

类型声明 ​

显示声明
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