subnvue 是 uni-app 的原生子窗体机制，适用于全屏视频悬浮窗、高频率拖拽菜单等需原生性能的场景；误用为普通弹窗会导致性能浪费。

subnvue 是什么，什么时候该用它

SubNVue 是 uni-app 提供的原生子窗体机制，本质是独立于 WebView 的原生视图层，能直接渲染原生控件、响应系统级手势、避免 WebView 渲染卡顿。但它不是“万能弹窗”，只适合需要原生性能或系统级交互的场景：比如全屏视频悬浮窗、高频率拖拽的抽屉菜单、需要穿透点击的蒙层、或要绕过 WebView 滚动截断的下拉刷新容器。

常见误用是拿它当普通 v-if 弹窗——这时候用 uni.showModal 或自定义 view 更轻量、更可控。

创建 SubNVue 窗体的三步硬性操作

• 必须在 pages.json 的对应页面配置中显式声明 subNVues 数组，不能靠 JS 动态注册
• 每个子窗体需指定 id（字符串，全局唯一）、path（指向一个 .nvue 文件路径，如 "subNVue/video-dock.nvue"）、style（宽高、位置、层级等，不支持百分比，必须用 px）
• .nvue 文件本身不能有 <template></template> 外的逻辑，不支持 onLoad 等生命周期，通信只能靠 uni.$emit/uni.$on 或 uni.postMessage

漏掉任一环节都会导致窗体不显示，且控制台无报错——这是最常踩的坑。

show 和 hide 不生效？检查这四个点

SubNVue 的显隐不是靠 Vue 响应式驱动，而是调用原生 API：uni.showSubNVue 和 uni.hideSubNVue。失效通常因为：

• id 字符串和 pages.json 里声明的不完全一致（大小写、空格、下划线差异都会失败）
• 调用时机太早：必须等所属页面的 onReady 触发后才能调用，onLoad 阶段调用大概率静默失败
• Android 上若未设置 style.maskClick 为 false，点击遮罩会自动隐藏窗体，掩盖了你手动控制的逻辑
• iOS 上若 style.zIndex 设得太低，可能被其他原生组件（如状态栏、键盘）盖住，看起来像“没显示”

与主页面通信时，别碰 this 和 ref

SubNVue 是独立上下文，this 不指向主页面实例，ref 无法跨窗体访问。所有数据传递必须走事件总线或消息通道：

• 主页面发消息给 SubNVue：uni.postMessage({ data: { action: 'update', value: 100 } })，SubNVue 内监听 plus.webview.currentWebview().addEventListener('postmessage', ...)
• SubNVue 回传数据到主页面：uni.$emit('subnvue-event', { payload: 'done' })，主页面用 uni.$on('subnvue-event', ...) 接收
• 禁止在 SubNVue 里调用 uni.navigateBack 或修改主页面 data，这类操作不会生效

原生子窗体的边界很清晰：它只负责渲染和轻量交互，状态管理、路由跳转、网络请求这些，一律留在主页面做。

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！