Cascader 级联选择器

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

import { createApp } from 'vue'
import { ElCascader, ElCascaderPanel } from '@szhn/dh-design-pc'

const app = createApp()
app.use(ElCascader)
app.use(ElCascaderPanel)

基础用法

有两种触发子菜单的方式

有禁用选项

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

可清空

通过 clearable 设置输入框可清空

自定义清除图标

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

仅显示最后一级

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

多选

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

选择任意一级选项

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

动态加载

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

可搜索

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

自定义节点内容

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

自定义建议项

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

级联面板

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

自定义标签

您可以自定义标签。

已勾选项显示策略

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

点击选中节点

只使用 multiple 或 checkStrictly 属性。

你可以添加 checkOnClickNode，使节点本身也能被点击（不仅限于前缀图标）。通过 showPrefix 来切换前缀的显示与隐藏。 :::tip 添加 checkOnClickLeaf 属性可以仅勾选叶子节点（最末级子节点），该功能默认启用。 :::

自定义头部与底部

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

CascaderProps

属性	说明	类型	默认值
expandTrigger	次级菜单的展开方式	enum `'click' \| 'hover'`	click
multiple	是否多选	boolean	false
checkStrictly	是否严格的遵守父子节点不互相关联	boolean	false
emitPath	在选中节点改变时，是否返回由该节点所在的各级菜单的值所组成的数组，若设置 false，则只返回该节点的值	boolean	true
lazy	是否动态加载子节点，需与 lazyLoad 方法结合使用	boolean	false
lazyLoad	加载动态数据的方法，仅在 lazy 为 true 时有效	Function	—
value	指定选项的值为选项对象的某个属性值	string	value
label	指定选项标签为选项对象的某个属性值	string	label
children	指定选项的子选项为选项对象的某个属性值	string	children
disabled	指定选项的禁用为选项对象的某个属性值	string	disabled
leaf	指定选项的叶子节点的标志位为选项对象的某个属性值	string	leaf
hoverThreshold	hover 时展开菜单的灵敏度阈值	number	500
checkOnClickNode	点击节点时是否选中或取消选中该节点	boolean	false
checkOnClickLeaf	点击叶子节点（最后一级子节点）时，是否选中或取消选中该节点	boolean	true
showPrefix	是否显示单选框或复选框的前缀（图标）	boolean	true

Cascader API

Cascader Attributes

属性名	说明	类型	默认值
model-value / v-model	选中项绑定值	string / number / array	—
options	选项的数据源， `value` 和 `label` 可以通过 `CascaderProps` 自定义.	array	—
props	配置选项, 请参阅下面 `CascaderProps` 表。	object	—
size	尺寸	enum	—
placeholder	输入框占位文本	string	—
disabled	是否禁用	boolean	—
clearable	是否支持清空选项	boolean	—
clear-icon	自定义清除图标	string / object	CircleClose
show-all-levels	输入框中是否显示选中值的完整路径	boolean	true
collapse-tags	多选模式下是否折叠Tag	boolean	—
collapse-tags-tooltip	当鼠标悬停于折叠标签的文本时，是否显示所有选中的标签。要使用此属性，`collapse-tags`属性必须设定为 true	boolean	false
max-collapse-tags-tooltip-height	collapse tags 的最大高度	string / number	—
separator	用于分隔选项的字符	string	' / '
filterable	该选项是否可以被搜索	boolean	—
filter-method	自定义搜索逻辑，第一个参数是`node`，第二个参数是`keyword`，返回的布尔值表示是否保留该选项	Function	—
debounce	搜索关键词正在输入时的去抖延迟，单位为毫秒	number	300
before-filter	过滤函数调用前，所要调用的钩子函数，该函数接收要过滤的值作为参数。如果该函数的返回值是 `false` 或者是一个被拒绝的 `Promise`，那么接下来的过滤逻辑便不会执行。	Function	—
popper-class	Cascader 下拉菜单和标签提示的自定义类名	string	''
popper-style	Cascader 下拉菜单和标签提示的自定义样式	string / object	—
teleported	弹层是否使用 teleport	boolean	true
effect	tooltip 主题，内置了 `dark` / `light` 两种	enum / string	light
tag-type	标签类型	enum	info
tag-effect	tag effect	enum	light
validate-event	输入时是否触发表单的校验	boolean	true
max-collapse-tags	需要显示的 Tag 的最大数量要使用此功能，`collapse-tags`的值必须为true	number	1
empty-values	组件的空值配置，参考config-provider	array	—
value-on-clear	清空选项的值，参考config-provider	string / number / boolean / Function	—
persistent	当下拉框未被激活并且`persistent`设置为`false`，下拉框容器会被删除。	boolean	true
fallback-placements	Tooltip 可用的 positions 请查看popper.js 文档	array	—
placement	下拉框出现的位置	enum	bottom-start
popper-append-to-body deprecated	是否将弹出的内容直接插入到 body 元素。在弹出内容的边框定位出现问题时，可将该属性设置为 false	boolean	true
show-checked-strategy	多选模式下已选节点的展示策略。当你想让显示更简洁时，使用 `parent`。当你想显示每个子项时，使用 `child`。	enum	child

Cascader Events

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

Cascader Slots

插槽名	说明	Type
default	自定义备选项的节点内容，分别为当前节点的 Node 对象和数据	object
empty	无匹配选项时的内容	—
prefix	输入框头部内容	—
suggestion-item	搜索时自定义建议项内容	object
tag	自定义tag样式	object
header	下拉列表顶部的内容	—
footer	下拉列表底部的内容	—

Cascader Exposes

方法名	说明	类型
getCheckedNodes	获取一个当前选中节点的数组。(仅仅是传单) 是否只返回叶选中的节点，默认是 `false`	Function
cascaderPanelRef	cascader 面板的 ref	object
togglePopperVisible	切换 popper 可见状态	Function
contentRef	cascader 内容的 ref	object
presentText	选中的内容文本	object
focus	使 input 获取焦点	Function
blur	使 input 失去焦点	Function

CascaderPanel API

CascaderPanel Attributes

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

CascaderPanel Events

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

CascaderPanel Slots

插槽名	说明	Type
default	下级节点的自定义内容，它们分别是当前节点对象和节点数据。	object
empty	没有数据时面板的内容。	—

CascaderPanel Exposes

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

Cascader 级联选择器 ​

基础用法 ​

有禁用选项 ​

可清空 ​

自定义清除图标 ​

仅显示最后一级 ​

多选 ​

选择任意一级选项 ​

动态加载 ​

可搜索 ​

自定义节点内容 ​

自定义建议项 ​

级联面板 ​

自定义标签 ​

已勾选项显示策略 ​

点击选中节点 ​

自定义头部与底部 ​

CascaderProps ​

Cascader API ​

Cascader Attributes ​

Cascader Events ​

Cascader Slots ​

Cascader Exposes ​

CascaderPanel API ​

CascaderPanel Attributes ​

CascaderPanel Events ​

CascaderPanel Slots ​

CascaderPanel Exposes ​