Cascader 级联选择器

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

基础用法

有两种触发子菜单的方式

只需为 Cascader 的options属性指定选项数组即可渲染出一个级联选择器。通过 props.expandTrigger 属性控制子节点的展开方式

Child options expand when clicked (default)

Child options expand when hovered

有禁用选项

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

本例中,options指定的数组中的第一个元素含有disabled: true键值对,因此是禁用的。在默认情况下,Cascader 会检查数据中每一项的disabled字段是否为true,如果你的数据中表示禁用含义的字段名不为disabled,可以通过props.disabled属性来指定(详见下方 API 表格)。当然,value、label和children这三个字段名也可以通过同样的方式指定。

可清空

通过 clearable 设置输入框可清空

自定义清除图标2.11.0

你可以通过clear-icon属性自定义清除图标

仅显示最后一级

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

属性show-all-levels定义了是否显示完整的路径,将其赋值为 false 则仅显示最后一级。

多选

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

使用多选时,所有选中的标签将默认显示。您可以设置 collapse = true 将选中的标签折叠。您可以设置 max-collapse-tags 来显示最大tag数量,默认1。您可以使用 collapse-tags-tooltip 属性来启用鼠标悬停折叠文字以显示具体所选值的行为。

Display all tags (default)

Collapse tags

Collapse tags tooltip

Max Collapse Tags

选择任意一级选项

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

可通过 props.checkStrictly = true 来设置父子节点取消选中关联,从而达到选择任意一级选项的目的。

Select any level of options (Single selection)

Select any level of options (Multiple selection)

动态加载

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

通过lazy开启动态加载,并通过lazyload来设置加载数据源的方法。 lazyload方法有两个参数,第一个参数node为当前点击的节点,第二个resolve为数据加载完成的回调(必须调用)。为了更准确的显示节点的状态,还可以对节点数据添加是否为叶子节点的标志位 (默认字段为leaf,可通过props.leaf修改)。否则,将以有无子节点来判断其是否为叶子节点。

可搜索

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

通过添加filterable来启用过滤。 Cascader 会匹配所有节点的标签和它们的亲节点的标签,是否包含有输入的关键字。你也可以用filter-method自定义搜索逻辑,接受一个函数,第一个参数是节点node,第二个参数是搜索关键词keyword,通过返回布尔值表示是否命中。

Filterable (Single selection)

Filterable (Multiple selection)

自定义节点内容

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

你可以通过 scoped slot 自定义节点的内容。您可以访问 scope 中的 node 和 data 属性,分别表示当前节点的 Node 对象和当前节点的数据。

自定义建议项2.9.5

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

级联面板

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

和级联选择器一样,通过 options 来指定选项,也可通过 props 来设置多选、动态加载等功能,具体详情见下方API表格。

自定义标签 2.10.3

您可以自定义标签。

将自定义的标签插入 el-cascader 的 slot 中即可。 collapse-tags, collapse-tags-tooltip, max-collapse-tags 在此模式下不生效.

Using slots allows for more flexible control over the display.

Display top-level tags only

已勾选项显示策略 2.10.5

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

在多选模式下,你可以使用 show-checked-strategy 来控制已选值的显示方式。默认策略为 child,即显示所有已选中的子节点。 parent 策略仅在其所有子节点都被选中时显示父节点。

Strategy: child (default, show all selected child nodes)

Strategy: parent (show only parent nodes when all children are selected)

点击选中节点 2.10.5

只使用 multiple 或 checkStrictly 属性。

你可以添加 checkOnClickNode,使节点本身也能被点击(不仅限于前缀图标)。 通过 showPrefix 来切换前缀的显示与隐藏。

TIP

添加 checkOnClickLeaf 属性可以仅勾选叶子节点(最末级子节点),该功能默认启用。

show prefix

checkStrictly | Single mode

Multiple mode

自定义头部与底部 2.10.5

你可以通过插槽来自定义下拉菜单的头部和底部。

使用插槽自定义内容。

Custom header content

Custom footer content

虚拟滚动 2.14.0

当处理大量数据时,您可以启用虚拟滚动以提高性能。

将 virtual-scroll 设置为 true 以启用虚拟滚动。 您还可以使用 height 自定义菜单高度,并使用 item-size 自定义节点高度。 默认高度为 204px,默认节点大小为 34px。

自定义建议面板宽度 2.14.0

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

TIP

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

Cascader API

Cascader Attributes

属性名说明类型默认值
value绑定值,对应官方 model-valuestring / number / array—
options选项数据,字段名可通过 props 自定义array—
props配置项,见下方 CascaderProps 表object—
size输入框尺寸enum—
placeholder输入框占位文本string—
disabled是否禁用boolean—
clearable是否可清空boolean—
clear-icon自定义清空图标ReactNodeCircleClose
show-all-levels输入框是否显示选中值的完整路径booleantrue
collapse-tags多选时是否折叠标签boolean—
collapse-tags-tooltip折叠标签时,悬停是否显示全部标签(需开启 collapse-tags)booleanfalse
max-collapse-tags-tooltip-height折叠标签提示框的最大高度string / number—
separator选项文案分隔符string' / '
filterable是否可搜索boolean—
filter-method自定义搜索逻辑,返回是否命中Function—
debounce搜索防抖延迟(毫秒)number300
before-filter过滤前钩子,返回 false 或 reject 时中止过滤Function—
popper-class下拉与标签提示框的自定义类名string''
popper-style下拉与标签提示框的自定义样式string / object—
teleported下拉是否挂载到 bodybooleantrue
effect下拉主题enumlight
tag-type标签类型enuminfo
tag-effect标签主题enumlight
validate-event是否触发表单校验booleantrue
max-collapse-tags折叠时最多显示的标签数(需开启 collapse-tags)number1
empty-values组件的空值配置array—
value-on-clear清空后的返回值string / number / boolean / Function—
persistent下拉不活跃时是否保留 DOMbooleantrue
fallback-placements下拉翻转时的兜底方位array—
placement下拉位置enumbottom-start
show-checked-strategy多选时标签显示的节点层级enumchild
virtual-scroll是否开启虚拟滚动booleanfalse
fit-input-width搜索建议面板是否与输入框等宽;数字表示固定宽度boolean / numberfalse
item-size虚拟滚动时节点高度(px)number34
height虚拟滚动时菜单高度(px)number204
id输入框 idstring—
className根节点类名string—
style根节点样式object—

Cascader Events

事件名说明参数
onChange绑定值变化时触发Function
onExpandChange展开项变化时触发Function
onFocus获得焦点时触发Function
onBlur失去焦点时触发Function
onClear点击清空图标时触发Function
onVisibleChange下拉显示状态变化时触发Function
onRemoveTag多选模式移除标签时触发Function

Cascader Slots(React Render Props)

名称说明类型
renderLabel自定义节点内容,对应官方 default 插槽Function
empty无匹配选项时的内容ReactNode
prefix输入框前缀内容ReactNode
renderSuggestionItem自定义搜索建议项,对应官方 suggestion-item 插槽Function
renderTag自定义标签样式,对应官方 tag 插槽Function
header下拉顶部内容ReactNode
footer下拉底部内容ReactNode

Cascader Exposes

名称说明类型
getCheckedNodes获取当前选中的节点,leafOnly 表示是否只返回叶子节点Function
panelRef级联面板实例object
togglePopperVisible切换下拉显隐Function
contentRef下拉内容节点object
presentText当前显示的文本string
focus聚焦输入框Function
blur输入框失焦Function

CascaderPanel API

CascaderPanel Attributes

属性名说明类型默认值
value绑定值,对应官方 model-valuestring / number / array—
options选项数据array—
props配置项,见下方 CascaderProps 表object—
virtual-scroll是否开启虚拟滚动booleanfalse
item-size虚拟滚动时节点高度(px)number34
height虚拟滚动时菜单高度(px)number204

CascaderPanel Events

事件名说明参数
onChange绑定值变化时触发Function
onExpandChange展开项变化时触发Function
onClose关闭面板时触发,供 Cascader 收起下拉Function
onCheckedNodesChange选中节点快照变化时触发Function

CascaderPanel Slots(React Render Props)

名称说明类型
renderLabel自定义节点内容,对应官方 default 插槽Function
empty无数据时的内容ReactNode

CascaderPanel Exposes

名称说明类型
getCheckedNodes获取当前选中的节点,leafOnly 表示是否只返回叶子节点Function
clearCheckedNodes清空选中节点Function

CascaderProps

属性说明类型默认值
expandTrigger展开子选项的触发方式enumclick
multiple是否开启多选booleanfalse
checkStrictly选中状态是否不与父子节点关联booleanfalse
emitPath选中变化时是否返回节点路径数组;为 false 时只返回值booleantrue
lazy是否动态加载子节点,需配合 lazyLoadbooleanfalse
lazyLoad加载子节点数据的方法,仅在 lazy 为 true 时生效Function—
value指定节点对象中作为值的字段名stringvalue
label指定节点对象中作为标签的字段名stringlabel
children指定节点对象中作为子节点的字段名stringchildren
disabled指定节点对象中作为禁用状态的字段名或判断函数string / Functiondisabled
leaf指定节点对象中作为叶子标识的字段名或判断函数string / Functionleaf
hoverThreshold悬停展开的阈值(毫秒)number500
checkOnClickNode点击节点时是否切换选中状态booleanfalse
checkOnClickLeaf点击叶子节点时是否切换选中状态booleantrue
showPrefix是否显示单选按钮或复选框前缀booleantrue

Type Declarations

type CascaderNodeValue = string | number
type CascaderNodePathValue = CascaderNodeValue[]
type CascaderValue =
  | CascaderNodeValue
  | CascaderNodePathValue
  | (CascaderNodeValue | CascaderNodePathValue)[]

type ExpandTrigger = 'click' | 'hover'
type Resolve = (data: CascaderOption[]) => void
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
  checkOnClickNode?: boolean
  checkOnClickLeaf?: boolean
  showPrefix?: boolean
}