n-cascader-picker 级联选择器

触发器 + 底部弹层的多级联动选择控件：点击触发器弹出底部面板，逐级下钻，选中叶子节点即完成并关闭。数据是一棵 label/value 树（options），选中结果用"从根到叶的完整 value 路径"表达（model-value 为各级 value 组成的数组），路径即结果——回显、提交、换数据源都只认路径。

1. 受控模式：在 change 回调里把 e.valuePath 回填给 model-value，即完成闭环；触发器回显只认已回填的选中值，面板里未完成的操作不影响触发器文字
2. children 缺省或空数组即叶子节点，选中即完成；数据为空时面板显示空态文案
3. 打开面板按 model-value 可匹配的前缀展开；传入不完整或不存在的路径不会报错
4. 弹层（遮罩 + 面板 + 级联列）由本组件内置，无需引入任何其他组件即可工作
5. 弹层文案（标题 / 占位 / 取消 / 空态）内置多语言，placeholder / title / cancelText 传入非空值则优先用传入值

平台兼容性

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

API

属性

参数	说明	类型	默认值	可选值
model-value	选中值 = 从根到叶的完整 value 路径；确认后经 @update:model-value 回传新路径。传入无法完整匹配的路径时，打开面板按可匹配的前缀展开	Array<string>	[]	-
options	级联数据树，根数组为第一级选项；label 显示文本、value 同层唯一、children 缺省或空数组即叶子	Array<NCascaderPickerOption>	[]	-
placeholder	触发器未选中时的占位文字；留空用内置多语言文案	String	""	-
title	弹层标题；留空用内置多语言文案	String	""	-
cancelText	弹层取消按钮文字；留空用内置多语言文案	String	""	-
disabled	禁用：触发器保色降透明并拦截点击（拦截的是打开动作，不影响已打开弹层的手动关闭）	Boolean	false	-
custom-class	挂到根节点的额外 class（类需定义在组件样式表内）	String	""	-
custom-style	根节点行内样式	String	""	与 css 相同

事件

事件名	说明	回调参数
update:model-value	选中叶子节点完成选择时触发；配合 :model-value 手动双向绑定（库内受控组件统一双事件通道）	从根到叶的完整 value 路径（Array<string>，可直接回写 model-value）
change	选中叶子节点完成选择时触发（语义化入口，与 update:model-value 同时发出）	NCascaderPickerResult：
cancel	关闭弹层且未完成选择时触发（点取消按钮或遮罩）	-

插槽

组件无插槽。触发器文字与弹层内容均由数据驱动，定制走主题令牌（--n-cascader-picker-*）与 custom-class / custom-style。

数据结构

// 级联节点
type NCascaderPickerOption = {
	label: string;   // 显示文本
	value: string;   // 同层内需唯一
	children?: NCascaderPickerOption[]; // 缺省或空数组 = 叶子，选中即完成
};

// change 事件载荷
type NCascaderPickerResult = {
	value: string;      // 选中叶子的 value
	label: string;      // 选中叶子的 label
	valuePath: string[]; // 从根到叶的完整 value 路径（与 model-value 同构）
	labelPath: string[]; // 从根到叶的完整 label 路径
};

实现说明

• 弹层骨架内嵌 n-popup（遮罩 / 钉底面板 / 滑入滑出过渡 / 底部安全区 / 遮罩取消由容器统一承担，弹层行为与库内其它弹层组件一致）；面板内的级联列能力（逐级下钻、页签切层、横滑切换）内聚在本组件中，未拆独立面板组件——保证单组件即插即用
• 触发器回显只认已回填的 model-value（面板内逐级选择的过程不实时改触发器文字），避免"未完成选择就污染表单回显"
• 弹层随打开/关闭整体重建、面板随选中路径变化整体重建，规避原生渲染层动态插拔节点不即时重绘的问题

新窗口 ↗

演示加载中…

示例代码加载中…