Cascader 级联选择器

当一个数据集合有清晰的层级结构（如行政区划、部门架构、商品分类）时，可通过级联选择器逐级选择。

基础用法

适用广泛的基础单选。

Value: []

基础用法

初始化回显

通过为 v-model 绑定初始数组，可以实现级联选择器的初始回显功能。

浙江省 / 杭州市 / 西湖区

浙江省 / 杭州市 / 滨江区江苏省 / 南京市 / 玄武区

Value (Single): [ "zhejiang", "hangzhou", "xihu" ]

Value (Multiple): [ [ "zhejiang", "hangzhou", "binjiang" ], [ "jiangsu", "nanjing", "xuanwu" ] ]

初始化回显

禁用状态

可以禁用整个组件，或在数据中指定某些选项不可选。

浙江省 / 杭州市 / 西湖区

Value: []

禁用状态

多选与折叠

设置 multiple 开启多选；使用 collapse-tags 折叠显示标签。

Value: []

多选模式

选择任意一级

启用 check-strictly 属性后，用户可以选中分级中的任何一级节点。

Value: []

任意级选择

返回模式 (emit-path)

默认返回完整路径数组。设置 emit-path="false" 后，将仅返回选中节点的 value。

浙江省 / 杭州市 / 西湖区

Value: xihu

非路径模式

搜索过滤

开启 filterable 支持快速搜索建议。支持匹配完整路径中的任何一段名称。

Value: []

可搜索

自定义内容

使用 #default 插槽可以完全自定义菜单项的渲染样式。

自定义插槽

自定义字段

通过 props 属性可以指定选项对象中的字段名，如 value、label、children 等。

Value: []

自定义字段

大数据优化

开启 virtual 启用虚拟滚动。应对上万级节点时，依然能保持极其流畅的交互体验。

虚拟滚动

在 Nuxt 中使用

Cascader 组件完全支持 Nuxt 3/4 的 SSR 渲染。在 Nuxt 项目中使用时，组件会自动导入，无需手动注册。

Nuxt 中使用

SSR 注意事项：

• ✅ 基础级联等级展示完全支持
• ✅ 多选（multiple）及折叠标签支持
• ✅ 任意级选择（check-strictly）在 SSR 中有效
• ✅ 搜索过滤功能在客户端激活后自动开启
• ✅ 虚拟滚动（virtual）支持首屏基础渲染
• 💡 下拉菜单通过 Teleport 渲染，不会干扰服务端生成的 HTML 结构

SSR 安全性

Cascader 的递归节点系统已针对 SSR 进行了深度优化，确保了在复杂的深层嵌套数据下，服务端 and 客户端生成的节点 ID 和结构保持强一致性，有效防止水合冲突。

API

Props

属性名	说明	类型	默认值
model-value / v-model	绑定值	string | number | (string | number)[] | (string | number)[][]	—
options	可选项数据源	CascaderOption[]	[]
props	配置选项，具体见下表	object	—
placeholder	输入框占位文本	string	—
disabled	是否禁用	boolean	false
clearable	是否支持清空	boolean	false
size	尺寸	'large' | 'default' | 'small'	'default'
filterable	是否支持搜索过滤	boolean	false
filter-method	自定义过滤方法	(node: CascaderOption, keyword: string) => boolean	—
separator	选项路径分隔符	string	' / '
show-all-levels	是否显示完整路径标签	boolean	true
multiple	是否启用多选	boolean	false
check-strictly	是否允许选择任意一级节点	boolean	false
expand-trigger	次级菜单展开方式	'click' | 'hover'	'click'
emit-path	在选中节点改变时，是否返回由该节点所在各级菜单的值所组成的数组	boolean	true
collapse-tags	多选时是否折叠标签	boolean	false
collapse-tags-tooltip	是否在折叠标签时显示 tooltip	boolean	false
max-collapse-tags	标签折叠前的最大展示数量	number	1
virtual	是否开启虚拟滚动	boolean	false
virtual-item-height	虚拟滚动项高度	number	34
popper-class	下拉框自定义类名	string	—
teleported	是否将下拉层挂载至 body	boolean	true
tag-type	多选标签的类型	'success' | 'info' | 'warning' | 'danger' | ''	''
validate-event	输入时是否触发表单验证	boolean	true

CascaderOption

属性名	说明	类型	默认值
value	选项的值	string | number	—
label	选项的标签名	string	—
children	子选项数组	CascaderOption[]	—
disabled	是否禁用该选项	boolean	false
leaf	是否是叶子节点	boolean	—

Cascader Config (props)

属性名	说明	类型	默认值
expandTrigger	次级菜单的展开方式	'click' | 'hover'	'click'
multiple	是否多选	boolean	false
checkStrictly	是否允许选择任意一级节点	boolean	false
emitPath	是否返回路径数组	boolean	true
value	指定选项的值为选项对象的某个属性值	string	'value'
label	指定选项标签为选项对象的某个属性值	string	'label'
children	指定选项的子选项为选项对象的某个属性值	string	'children'
disabled	指定选项的禁用为选项对象的某个属性值	string	'disabled'
leaf	指定选项的叶子节点为选项对象的某个属性值	string	'leaf'

Events

事件名	说明	回调参数
change	选中值发生变化时触发	(value: any) => void
expand-change	展开节点发生变化时触发	(value: any[]) => void
visible-change	下拉框显示/隐藏时触发	(visible: boolean) => void
focus	获取焦点时触发	(event: FocusEvent) => void
blur	失去焦点时触发	(event: FocusEvent) => void
clear	点击清空按钮时触发	—

Slots

插槽名	说明	参数
default	自定义节点内容	{ node: CascaderOption, data: CascaderOption }
empty	无匹配数据时的显示内容	—

Expose

属性/方法名	说明	类型
focus	使输入框获取焦点	() => void
blur	使输入框失去焦点	() => void
getCheckedNodes	获取当前选中的节点对象数组	(leafOnly?: boolean) => CascaderOption[]
inputRef	输入框的 DOM 引用	HTMLInputElement

主题变量

变量名	说明	默认值
--yh-cascader-height	级联选择器高度	32px
--yh-cascader-bg-color	背景颜色	var(--yh-fill-color-blank)
--yh-cascader-border-color	边框颜色	var(--yh-border-color)
--yh-cascader-border-color-hover	悬停时边框颜色	var(--yh-border-color-hover)
--yh-cascader-border-color-focus	聚焦时边框颜色	var(--yh-color-primary)
--yh-cascader-text-color	文字颜色	var(--yh-text-color-regular)
--yh-cascader-placeholder-color	占位文字颜色	var(--yh-text-color-placeholder)
--yh-cascader-node-height	选项节点高度	34px
--yh-cascader-node-bg-color-hover	选项悬停背景色	var(--yh-fill-color-light)
--yh-cascader-node-bg-color-active	选项激活背景色	var(--yh-fill-color-light)
--yh-cascader-node-text-color-active	选项激活文字颜色	var(--yh-color-primary)
--yh-cascader-menu-min-width	菜单最小宽度	180px
--yh-cascader-menu-max-height	菜单最大高度	274px