Cascader 级联选择器

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

TIP

在 SSR 场景下,您需要将组件包裹在 <client-only></client-only> 之中 (如: Nuxt) 和 SSG (e.g: VitePress).

基础用法

有两种触发子菜单的方式

有禁用选项

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

可清空

通过 clearable 设置输入框可清空

仅显示最后一级

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

多选

在标签中添加 :props="props" 并设置 props = { multiple: true } 来开启多选模式。

正确用法:

<template>
  <el-cascader :props="props" />
</template>
<script lang="ts" setup>
  const props = { multiple: true }
</script>

错误用法:

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

选择任意一级选项

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

动态加载

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

可搜索

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

自定义节点内容

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

级联面板

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

Cascader API

Cascader Attributes

属性名说明类型默认值
model-value / v-model选中项绑定值string/number/object
options选项的数据源, valuelabel 可以通过 CascaderProps 自定义.object
props配置选项, 请参阅下面 CascaderProps 表。object
size尺寸enum
placeholder输入框占位文本string
disabled是否禁用boolean
clearable是否支持清空选项boolean
show-all-levels输入框中是否显示选中值的完整路径booleantrue
collapse-tags多选模式下是否折叠Tagboolean
collapse-tags-tooltip当鼠标悬停于折叠标签的文本时,是否显示所有选中的标签。 要使用此属性,collapse-tags属性必须设定为 truebooleanfalse
separator用于分隔选项的字符string' / '
filterable该选项是否可以被搜索boolean
filter-method自定义搜索逻辑,第一个参数是node,第二个参数是keyword,返回的布尔值表示是否保留该选项Function
debounce搜索关键词正在输入时的去抖延迟,单位为毫秒number300
before-filter过滤函数调用前,所要调用的钩子函数,该函数接收要过滤的值作为参数。 如果该函数的返回值是 false 或者是一个被拒绝的 Promise,那么接下来的过滤逻辑便不会执行。Function
popper-class弹出内容的自定义类名string''
teleported弹层是否使用 teleportbooleantrue
popper-append-to-body deprecated是否将弹出的内容直接插入到 body 元素。 在弹出内容的边框定位出现问题时,可将该属性设置为 falsebooleantrue
tag-type标签类型enuminfo
validate-event输入时是否触发表单的校验booleantrue
max-collapse-tags 2.3.10需要显示的 Tag 的最大数量 只有当 collapse-tags 设置为 true 时才会生效。number1

Cascader Events

事件名说明类型
change当绑定值变化时触发的事件Function
expand-change当展开节点发生变化时触发Function
blur当失去焦点时触发Function
focus当获得焦点时触发Function
visible-change下拉框出现/隐藏时触发Function
remove-tag在多选模式下,移除Tag时触发Function

Cascader Slots

插槽名说明作用域
default自定义备选项的节点内容,分别为当前节点的 Node 对象和数据object
empty无匹配选项时的内容

Cascader Exposes

属性名说明类型
getCheckedNodes获取一个当前选中节点的数组。(仅仅是传单) 是否只返回叶选中的节点,默认是 falseFunction
cascaderPanelRefcascader 面板的 refobject
togglePopperVisible 2.2.31切换 popper 可见状态Function
contentRefcascader 内容的 refobject

CascaderPanel API

CascaderPanel Attributes

属性名说明类型默认值
model-value / v-model选中项绑定值string/number/object
options选项的数据源, valuelabel 可以通过 CascaderProps 自定义.object
props配置选项, 请参阅下面 CascaderProps 表。object

CascaderPanel Events

事件名说明Type
change当选中节点变化时触发Function
expand-change当展开节点发生变化时触发Function
close面板的关闭事件,提供给 Cascader 以便做更好的判断。Function

CascaderPanel Slots

插槽名说明Scope
default下级节点的自定义内容,它们分别是当前节点对象和节点数据。object

CascaderPanel Exposes

属性名说明Type
getCheckedNodes获取一个当前选中节点的数组。(仅仅是传单) 是否只返回叶选中的节点,默认是 falseFunction
clearCheckedNodes清空选中的节点Function

CascaderProps

属性说明类型默认值
expandTrigger次级菜单的展开方式enumclick
multiple是否多选booleanfalse
checkStrictly是否严格的遵守父子节点不互相关联booleanfalse
emitPath在选中节点改变时,是否返回由该节点所在的各级菜单的值所组成的数组,若设置 false,则只返回该节点的值booleantrue
lazy是否动态加载子节点,需与 lazyLoad 方法结合使用booleanfalse
lazyLoad加载动态数据的方法,仅在 lazy 为 true 时有效Function
value指定选项的值为选项对象的某个属性值stringvalue
label指定选项标签为选项对象的某个属性值stringlabel
children指定选项的子选项为选项对象的某个属性值stringchildren
disabled指定选项的禁用为选项对象的某个属性值stringdisabled
leaf指定选项的叶子节点的标志位为选项对象的某个属性值stringleaf
hoverThresholdhover 时展开菜单的灵敏度阈值number500

类型声明

显示类型声明
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(event: string, ...args: unknown[]): void
  emit(event: string, ...args: unknown[]): void
  onParentCheck(checked: boolean): void
  onChildCheck(): void
  setCheckState(checked: boolean): void
  doCheck(checked: boolean): void
}

Node as CascaderNode

源代码

组件文档

贡献者