n-cascader 级联面板

内嵌面板形态的多级联动选择器：层级 tab 头 + 当前层选项列表。点击含子级的选项逐级下钻，末级选项选中即完成一次选择（finish）；点层级 tab 回到该层重选，已选项以对勾回显。数据是一棵 label/value 树（options），选中值用"从根到叶的完整 value 路径"表达（model-value 为各级 value 组成的数组），路径即结果——回显、提交、换数据源都只认路径。

1. 受控模式：组件支持 v-model，也可使用显式绑定：@update:model-value 里把路径回填给 model-value
2. children 缺省或空数组即叶子节点，选中即完成；数据为空时列表区显示空态文案
3. 传入无法完整匹配的路径时按可匹配的前缀解析（截断不报错），面板停在解析到的层级
4. 本组件无弹层：需要弹窗承载时用 n-cascader-picker（触发器 + 底部弹层内置本面板的完整级联能力），或用使用者自己的弹层包裹本面板，面板高度用 height 控制
5. 层级 tab 占位文案与空态文案内置多语言，placeholder 传入非空值则优先用传入值

平台兼容性

App	H5	微信小程序	支付宝小程序	百度小程序	头条小程序	QQ小程序
√	√	√	×	×	×	×

API

属性

参数	说明	类型	默认值	可选值
model-value	选中值 = 从根到叶的完整 value 路径；配合 @update:model-value 手动双向绑定。传入无法完整匹配的路径时按可匹配前缀解析	Array<string>	[]	-
options	树形选项数据，按层级嵌套；label 显示文本、value 同级唯一、children 缺省或空数组即叶子	Array<NCascaderOption>	[]	-
title	面板标题，显示在层级 tab 头上方；空串不渲染标题行	String	""	-
placeholder	待选层级的 tab 文案；留空用内置多语言文案	String	""	-
height	选项列表区高度（px），超出纵向滚动	Number	240	-
disabled	禁用：保色降透明，拦截选项与层级 tab 点击	Boolean	false	-
custom-class	挂到根节点的额外 class（类需定义在组件样式表内）	String	""	-
custom-style	根节点行内样式	String	""	与 css 相同
title-style	微调标题文字的行内样式	String	""	与 css 相同
item-style	微调选项行的行内样式（如补分割线）	String	""	与 css 相同
item-text-style	微调选项文字的行内样式；选中态颜色由组件按状态给出，不建议在此覆盖 color	String	""	与 css 相同

事件

事件名	说明	回调参数
update:model-value	选中路径变化时触发；配合 :model-value 手动双向绑定	最新值路径数组（string[]）
change	选中路径变化时触发；下钻与末级选中都会触发，点层级 tab 是纯导航不触发	NCascaderPathItem[]：路径节点数组（{ value, label }），可直接用于结果回显
finish	末级选项选中时触发；一次完整选择以本事件收口	NCascaderPathItem[]，同 change

插槽

组件无插槽。标题、层级 tab 与选项列表均由数据驱动，定制走主题令牌（--n-cascader-*）与 custom-class / custom-style / *-style 行内样式通道。

数据结构

// 级联选项：末级不传 children（或传空数组）
type NCascaderOption = {
	label: string;   // 选项文字
	value: string;   // 选项值，同级内需唯一
	children?: NCascaderOption[];
};

// change / finish 事件载荷项：值 + 文字，可直接用于选中结果回显
type NCascaderPathItem = {
	value: string;
	label: string;
};

实现说明

• 单一数据流：已选节点路径（按值沿树解析，外部传错值时截断、不报错）为唯一源，当前浏览层级由路径长度派生；点层级 tab 只做导航（路径与事件都不动），点选项在当前层截断叠加并发事件，从中间层改选自然丢弃更深层的旧值
• 列表 scroll-view 随层级整体销毁重建、层级 tab 头滚动锚定激活项；右侧指示符只有对勾（本层已选）与箭头（可下钻）两种，均纯 CSS 形，无字体依赖
• 面板高度用 height 控制（默认 240px），超出纵向滚动；作为区块内嵌在页面流中使用，不遮盖页面其它内容

新窗口 ↗

演示加载中…

示例代码加载中…