本文系统讲解 cocos creator 中 canvas 组件的核心作用、渲染模式（rendermode）、优先级（priority）及 clearflag 等关键属性的协同逻辑，帮助开发者正确混合 2d ui 与 3d 场景，避免遮挡、清屏异常或 z 轴失效等问题。
本文系统讲解 cocos creator 中 canvas 组件的核心作用、渲染模式（rendermode）、优先级（priority）及 clearflag 等关键属性的协同逻辑，帮助开发者正确混合 2d ui 与 3d 场景，避免遮挡、清屏异常或 z 轴失效等问题。
在 Cocos Creator 中，Canvas 不仅是 UI 渲染的根节点，更是连接 2D 与 3D 渲染管线的枢纽。所有 UI 元素（如 Label、Button、Image）必须挂载在某个 Canvas 节点下才能被正确渲染；而一个场景中可存在多个 Canvas，它们通过 priority 和 RenderMode 共同决定最终的绘制顺序与视觉层级。
✅ 核心机制解析
1. RenderMode：决定 UI 与 3D 的混合方式
-
OVERLAY（默认）：UI 始终渲染在最上层，完全覆盖 3D 内容（适用于 HUD、菜单等）； -
CAMERA：UI 由指定相机渲染，可与 3D 场景共用同一相机（需手动配置 Camera 引用）； -
INTERSPERSE：关键模式——UI 可按priority插入到 3D 相机渲染序列中，实现真正意义上的“3D 场景中嵌入 UI”（例如：3D 角色头顶血条、2D 地图叠加 3D 单位）。
⚠️ 注意：当使用
INTERSPERSE模式时，若多个Canvas或Camera共存，仅最低 priority 的渲染器（Canvas 或 Camera）可设置ClearFlag = SOLID_COLOR；其余必须设为DEPTH_ONLY或DONT_CLEAR，否则前置内容将被清屏擦除。
2. Z 轴限制：UI 元素不可见的常见原因
Canvas 内置 UI 相机的默认裁剪范围为 z ∈ [-1000, 998)（不包含 998）。若 UI 节点的本地 z 值超出此区间（如 z = 1000 或 z = -1500），将直接被剔除，不参与任何渲染。务必检查 UI 节点的 Transform.z 值是否合规。
3. Priority：分层排序的权威依据
- 在
OVERLAY模式下，priority仅控制多个Canvas之间的叠放顺序（数值越大越靠前）； - 在
INTERSPERSE模式下，priority与Camera.priority同属全局渲染队列排序键：值越小，越早渲染（即更“靠后”）；值越大，越晚渲染（即更“靠前”）。
4. ClearFlag 与 Color：清屏行为的精准控制
| ClearFlag | 行为说明 |
|---|---|
DONT_CLEAR |
不清空帧缓冲区，保留上一帧残留（慎用） |
DEPTH_ONLY |
仅清除深度缓冲，适合多 Pass 渲染 |
SOLID_COLOR |
清空颜色+深度缓冲，填入 Color 指定色 |
✅ 最佳实践：主 3D 相机设
SOLID_COLOR（初始化画面），其余Canvas/Camera设DEPTH_ONLY，确保内容叠加而非覆盖。
? 示例：实现「3D 场景中浮动的 UI 面板」
// 假设已创建：
// - 主相机（Camera）priority = 0，ClearFlag = SOLID_COLOR
// - Canvas_A（UI 面板）RenderMode = INTERSPERSE，priority = 1，ClearFlag = DEPTH_ONLY
// 此时 Canvas_A 将在主相机之后、其他高 priority 相机之前渲染
// 其子节点（如 Image、Label）的 z 值应设为 -999 ~ 997 之间，例如：
const uiPanel = this.node.getChildByName('panel');
uiPanel.setPosition(0, 0, -500); // ✅ 合法 Z 值
? 调试建议
- 打开 Game View → Render Statistics，观察
Canvas是否出现在渲染队列中； - 检查 Console 是否报错
z is out of range或Canvas not rendered due to priority conflict； - 使用 Profiler → Rendering 查看各
Canvas的实际渲染耗时与调用次数； - 多
Canvas场景下，临时给每个Canvas设置不同Color（配合SOLID_COLOR），直观验证清屏区域。
掌握 Canvas 的渲染本质，不是简单“拖控件”，而是主动设计渲染管线的协作契约。合理组合 RenderMode、priority 与 ClearFlag，才能让 UI 与 3D 内容真正融为一体，而非彼此割裂。
