UI 系统 · 架构解析

0三句话速览

三句话速览

① 对外只有一个入口：RevUI（门面）      // 业务只跟它打交道
② 状态只有一个主人：RevUIManager（管理器） // 谁开着、谁在池里、谁盖着谁，全由它记账
③ 需要 Unity 的事只有一处：RevUIRoot（常驻根节点） // 建 Canvas、摆六层、挡点击、每帧重排

本篇怎么读

1它要解决什么问题

1.1 起点：写一个界面要写五个脚本

作者在项目组里用的那套 UI 框架极其复杂 —— 写一个 UI 功能要写好几个脚本，各管一段：

写一个界面，就要在五个文件之间来回跳。太复杂了。 而且这套东西是用 TypeScript（puerts）写的 —— 在 Unity 工程里用 TS 写 UI 很别扭、很丑陋：编译链、类型、调试、和 C# 侧的边界，全是额外的心智负担。

更关键的矛盾：分这么多层只是为了热更，而热更本身又只是"半套"

把界面切成这么多层，唯一的正当理由是热更新 —— 界面逻辑放进 TS，就能不发版改界面。但项目里的实际情况是：

• 只有大版本之内的小更新才走热更；
• 一整个大版本更新，必须重新打包发版。

那这笔账就不划算了：为了"偶尔一次小更新"，长期付出"每个界面五个脚本 + 一整套 TS 工具链"的成本。既然大版本反正要重新发版，还不如全量上 HybridCLR 这类 C# 热更方案 —— 语言统一在 C#，分层也可以顺着 C# 的习惯重新设计，不必为了 TS 的边界把界面切得那么碎。

于是想到：留下真正值得复用的部分，其余按自己的方式重写

1. 留下真正有复用价值的东西 —— 比如 ViewData（数据与界面分离）、Part（可复用的界面单元）这类"结构上就对"的设计；
2. 融合作者跟唐老师学到的 UI 框架里的做法（面板 + 钩子 + 声明式绑定这一路）；
3. 目标就三个词：高复用、易用、傻瓜式 —— 写一个界面 = 一个脚本 + 一个预制体，不该先学会一套分层学说才能动手。

1.2 三条目标：后面每个决策都是它们的展开

1.3 具体盯的是哪几件事

1.4 比早期版本多出来的不是"功能"，是"保证"

这套系统的前身是 BasePanel（219 行）+ UIMgr（335 行），只做"开 / 关 / 隐藏"。新版文件多了，但它补的每一条都是给业务的保证：

2整体骨架：四个角色、两圈分层

2.1 一张图看懂依赖方向

先看全景。箭头是"调用/依赖"方向，箭头是单向的 —— 这一点很重要，它保证了"业务不碰实现、实现不反向依赖业务"：

业务代码
  │  只调这一个入口
  ▼
RevUI（门面 · 静态类 · 无状态）                   // Facade\RevUI.cs
  │  Open / Close / Back / Preload / DumpStats …
  ▼
RevUIManager（管理器 · 单例 · 非 MonoBehaviour）  // Implementation\RevUIManager.cs
  ├─ 索引：打开中 / 加载中 / 打开顺序 / 互斥组 / 实例池
  ├─ 找资源：RevResManager（资源系统，见《资源加载系统》）
  ├─ 解析声明：RevUIPanelMeta（读特性，一次）→ RevUIBindPlan（算绑定计划，一次）
  ├─ 存 / 取实例：RevUIPanelPool（私有持有）
  └─ 首用时创建 ▼
RevUIRoot（常驻场景 · MonoBehaviour）             // Implementation\RevUIRoot.cs
  ├─ 建 Canvas + 六层挂点（Scene/Normal/Popup/Toast/Guide/Top）
  ├─ RevUIPopupMask（每层一块挡板，私有持有）
  ├─ EventSystem 兜底 / UI 相机
  ├─ Update      → 处理"延迟一帧的销毁"
  └─ LateUpdate  → 回调管理器：层内排序 + 遮罩摆位 + 被盖住通知

面板侧（业务继承它，框架驱动它）
RevUIPanel  ──用──▶ RevUIBinder（装配）· RevUIAnim（动画）· RevEvent（事件）
RevUIPart   ──只认──▶ IRevUIPartHost（宿主接口，因此能跨面板复用）

2.2 四个角色：各自为什么存在、为什么不能合并

2.3 两圈分层：哪些文件是"纯 C#"，为什么

26 个文件里有一圈完全不引用 UnityEngine 的纯 C# 文件。这不是洁癖，而是为了能被验证：

2.4 26 个文件怎么归类

按"它是哪一类角色"分，一眼就能看全（详细职责见第九章）：

3跟着一次"打开面板"走完全程

架构图看着抽象，跟着一次打开走一遍就具体了。下面这一步一步，就是源码里真实发生的顺序（行号见第九章的文件表）。

3.1 第一件事：先看"有没有现成的" —— 五级查找

打开面板时，框架不会傻乎乎地"每次都加载 + 实例化"，而是按从便宜到昂贵的顺序找五遍。这个顺序本身就是性能设计：

3.2 实例化之后：先"装配"，再"打开"

拿到实例不是就完了 —— 控件还是空的、数据还没画。框架把这段拆成两件不同性质的事：

• 装配（只做一次）：按绑定计划把字段填上控件、按需挂上 UGUI 监听，然后依次调用 OnBindView()（你的装配代码）与 OnInit()。它跟"打开几次"无关，所以池化复用不会重来。
• 进入打开流程：置为 Opening → 激活物体 → 播放转场 → 转场结束置为 Opened → 调 OnOpen() → 调 OnRefreshView() 画数据 → 通知所有 Part 打开 → 播放显示动画 → 最后调业务传进来的回调。

为什么要分这么清？因为二者的"频率"不同：装配一辈子一次，打开可以很多次。混在一起写，复用就会变成"重新绑一遍"（白花性能）或"忘了重画"（数据是旧的）——这两种 bug 都很常见。

3.3 挂到哪、盖住谁：重排为什么放到"渲染前一刻"

打开/关闭面板时，框架不会立刻去调兄弟节点顺序、也不会立刻挪挡板，而只是挂一个"待重排"的脏标记；真正干活的是根节点的 LateUpdate（本帧画面渲染之前）：

// 一帧里可能开了 3 个、关了 2 个面板 —— 每次开关都立刻重排 = 同一帧排 5 次
开关面板  →  只打脏标记  // O(1)，很便宜
   …
LateUpdate（渲染前） →  一次做完：
     ① 各层内部按打开顺序排兄弟节点
     ② 找出"谁提供本层遮罩" → 把挡板插到它正下方
     ③ 通知"被盖住 / 恢复"变化的面板（OnCovered）

这样做的三个附带好处：① 同一帧开关多次只排一次；② 排序发生在渲染前，所以"本帧开的面板本帧就看到正确层级"，不会闪一下；③ 排序只有一个地方做，不会出现"这里排了、那里又设了 sortingOrder"的打架。

3.4 关闭：为什么"关"是异步的

关闭不是一句 SetActive(false)，而是一条有始有终的流程：

Closing → 通知 Part 关闭 → 播关闭转场 → OnClose() → 摘掉本面板所有事件
        → 播隐藏动画 → 置 Closed → 管理器收尾
                                                    ├─ 可复用（KeepAlive）→ 失活后放回池
                                                    └─ 否则 → 挂进"待销毁"队列，下一帧才真正销毁 + 还资源引用

因为中间有转场和动画，所以"关闭"必然跨帧 —— 这才需要 Closing 这个状态（见第四章）。延迟一帧销毁则是因为：关闭请求很可能发生在"正在遍历某个列表/正在派发事件"的过程中，边遍历边删对象是经典崩法，所以统一推到下一帧的 Update 里做。

3.5 一次打开里的五个"异步边界"

读完上面，就能理解为什么这套框架里"打开"不是一个瞬时动作。源码里一共有五处会让时序"跨帧"：

4生命周期：四个状态 + 一组钩子

4.1 四个状态：为什么不是"开 / 关"两个

不存在 ──创建──▶ Opening ──转场结束──▶ Opened ──调 Close──▶ Closing ──转场+动画结束──▶ Closed
                    ▲                                                          │
                    └──────────── 复用再打开（走池，装配不重来）◀──────────────┤
                                                                               └─▶（KeepAlive 回池 / 否则下帧销毁）

4.2 钩子清单：谁在什么时候被调、调几次

钩子指的是"框架在固定时机回头调用你的方法"。下面这张表是完整清单（按真实调用顺序）：

4.3 四条容易被误解的规则

5关键设计决策（源码为什么这样写）

这一章是全篇的重点：挑出这套框架里"看起来怪、其实有理由"的十个写法，每个都说清不这么做会怎样、源码里怎么体现、代价是什么。行号对应 Assets\Revolution\Runtime\RevUISystem\。

决策 1：用"特性 + 反射"声明，而不是代码生成

问题：UI 绑定天然有个两难 —— 手写 Find("Panel/Panel/Btn") 是硬编码，改名就悄悄变 null；而"代码生成"（王者的 UI_BINDING 那套）虽然编译期就能报错，但要多一整套生成流程：改预制体要重新生成、生成物要入库、生成器和手写代码要分工。

做法：把"意图"写成声明（[RevUIPanel] 说清资源在哪、放哪层；[RevBind] 说清字段绑哪个节点），运行时读一次、缓存起来。这条路把"多一道流程"换成了"第一次运行就报错"。

源码里长这样：Core\RevUIAttributes.cs:105-108 明写了"为什么不学那套代码生成"；Support\RevUIPanelMeta.cs:84-86、:104-117 规定解析失败必须报错而不是静默猜路径；Support\RevUIBinder.cs:107-111、:200-215 在找不到节点时把"根节点下真实存在的节点名"全列出来，直接告诉你该改成什么。

代价：① 错误从"编译期"推迟到"运行期第一次"，所以框架必须把这句错误写得足够好（这就是决策 1 里花最多代码的部分）；② 反射本身有开销 —— 所以有了决策 2。

决策 2：绑定计划 —— 每个类型只反射一次

问题：反射慢，但 UI 实例化很频繁（同一个面板可能开开关关几十次）。如果每次实例化都去"扫字段、读特性、按名字找节点"，开销会翻倍；如果每次都全量扫一遍所有子控件（早期版本那样），更浪费。

做法：把"这个类型该怎么绑"算成一份计划（RevUIBindPlan）：字段表、规范化后的节点名、以及需要哪些控件事件（WantsClick / WantsScroll…）。计划按业务类型缓存，运行时只做"字符串 → 找节点 → 取组件 → 赋值"。

源码里长这样：Support\RevUIBindPlan.cs:90 的缓存表以 Type 为键，:100-109 是"命中就用、没有才算"，:116-143 是唯一的计算点；Support\RevUIBinder.cs:13-19 说明它相对旧做法改了三处（全量扫 → 按需扫、每按钮闭包 → 继电器、每次重挂 → 挂一次）。

代价：缓存是按类型算的，所以"某个具体实例的字段要不要绑"不能靠计划决定 —— 这没问题，因为绑什么本来就由类型决定。真正的代价在决策 2 的诚实版：走方法特性（如 [RevButtonClick]）派发时，每次触发会有一点点小分配（反射调用 + 参数数组），所以高频事件（滚动、输入）建议用重写回调 —— 这句代价明写在 Core\RevUIWidgetEvents.cs:40-44。

决策 3：一个面板只有一个脚本 —— 分层靠"钩子职责"，不靠拆类

问题：参考实现把界面拆成 View / Logic / System / BusinessLogic 四层，干净但一个界面要写好几个文件、还要跨语言。要不要照抄？

做法：不拆类，改成"一个类，但每个钩子只许干一件事"：OnBindView 只装配、OnRefreshView 只落屏、OnClick 等交互回调只做业务转发。用结构约束，而不是靠注释约定 —— 带数据的界面里 OnRefreshView 是抽象方法，不写就编译不过。

源码里长这样：Core\RevUIPanel.cs:6-18 是这段取舍的原文；:93-98 与 :110-114 用注释把三个钩子的边界钉死；Core\RevUIPanel.Generic.cs:28-30、:51 把"有数据就必须写清数据怎么落屏"变成编译期强制。

代价：逻辑量大的面板会变胖。这是刻意接受的：补救办法不是提前拆类，而是"什么时候该抽出去"有明确信号（见第七章）。

决策 4：Part 只认"宿主接口" —— 可复用单元的解耦

问题：一个界面里经常有"能整块搬去别处"的东西（背包格子、奖励条目、页签组）。如果它就是面板里的一个节点，搬不走；如果做成"小面板"，又会牵扯层级、遮罩、独立开关一堆它不需要的东西。

做法：引入 RevUIPart：依附于宿主的可复用单元，生命周期完全跟随宿主（宿主开它就开、宿主关它就关），并且只通过一个四成员接口与宿主沟通，所以能跨面板复用。它有两种形态：摆在宿主预制体里的节点级（零加载），和独立预制体的预制体级（可跨面板复用）。

源码里长这样：Core\RevUIPart.cs:6-11 定义"Panel 与 Part 的区别"；Interfaces\IRevUIPartHost.cs:6-15、:22-38 是那四个成员（拿挂点 / 宿主开着吗 / 请求关闭 / 通知宿主）；Support\RevUIPanelMeta.cs:161 用"有没有写 root"来判定是哪种形态；Part 与 Part 之间不直接通信，必须经宿主中转。

代价：宿主侧要负责"刷新哪些 Part"（框架不自动刷全部 Part，否则一次页签变化会带出整屏重绘）；另外 Part 的关闭是同步的，所以给它配"隐藏动画"通常没意义。

决策 5：层级靠"结构"决定，遮罩由框架自动铺

问题：弹窗要挡住下面的点击，这是 UI 最常见的需求，也是最容易做乱的地方：每个弹窗自己摆一块遮罩、自己设 sortingOrder，最后没人说得清"现在谁在最上面"。

做法：把"位置"变成结构：六个层从下到上固定；层内顺序 = 打开顺序；"谁提供本层遮罩"由层级规则推断（例如 Popup / Guide / Top 层默认挡），挡板由框架自动插到那个面板正下方。

源码里长这样：Core\RevUIDefine.cs:20-41 明确要求"枚举值必须是从下到上的连续序号"，管理器按它建挂点、推遮罩、排序；Implementation\RevUIRoot.cs:29-30 点明"层间关系靠子节点顺序，不让每个面板自己设 sortingOrder"；Implementation\RevUIPopupMask.cs:36 是"一层一块挡板"（不是每面板一块、也不是全局唯一），:64 把它插到对应面板正下方。

代价：想让某个浮层"看一眼但不打断操作"，必须显式声明（Mask = None）；不然它会按层级默认规则挡住下面。

决策 6：UI 专用实例池 + 清理契约（不套通用对象池）

问题：界面关掉就销毁 → 下次打开要重新加载 + 实例化，明显卡顿；关掉不销毁、下次直接用 → 快，但"上次的东西还在"。更微妙的是：能不能用框架里现成的通用对象池？

做法：做专用的 RevUIPanelPool。理由很实在：界面复用需要重置的东西远多于普通对象（控件引用、监听、数据、滚动位置、选中态、输入内容、倒计时…），通用池只懂"失活 / 激活"，管不了这些。所以复用必须是"有契约的路径"：池只负责存取，清理由必被调用的 OnReuse() 负责，而框架先替你把数据清掉。

源码里长这样：Implementation\RevUIPanelPool.cs:6-12 明确写了"不要用通用 GameObjectPool"的结论；:44-48 说明为什么 OnReuse 放在"取出时"调；Support\RevUISetting.cs:41-45 的 MaxCachedPanels 默认是 1 —— 一个面板同时只会开一份，多出来的回收掉，避免"池变成内存黑洞"。

代价：每个面板都要写清"复用时哪些残留要清"。框架把能替你做的都做了（清数据、兜底摘事件），但界面上的残留只有你懂。

决策 7：异步安全 —— 状态守卫、在途合并、延迟一帧销毁

问题：UI 的时序是"异步 + 并发"的高发区：连点两次打开、加载还没回来就被关掉、关闭动画播到一半又被打开、遍历列表时删对象……每一种都会变成偶发 bug。

做法：四条具体的防线：

代价：代码里到处能看到"先判断再做事"的守卫（读起来啰嗦一点，但每条守卫都对应一个曾经会偶发的事故）。另外业务必须接受"打开完成要用回调"这件事（见 3.5）。

决策 8：动画自己写 —— 采样模型 + 余量结转 + 不受暂停影响

问题：界面动效通常第一反应是引一个缓动库（早期版本就是硬依赖 DOTween，扩展写了 1000+ 行）。但依赖会带来三个约束：包体与版本、暂停时的行为、以及"每帧零分配"这个性能底线能不能保证。

做法：自研一个小内核，三条铁律：①采样模型（用"已过时长 / 总时长"算缓动系数，不是每帧累加，掉帧不改变总时长、不累积误差）；②帧余量结转（延迟、循环、往返时把超出部分带进下一段，不丢时间）；③零 GC 热路径（运行时对象池 + 句柄带版本号，防止"停错动画"）。时间源用不受时间缩放影响的 unscaledDeltaTime。

源码里长这样：Animation\RevUIAnimEngine.cs:11-17 就是这三条铁律的原文；Animation\RevUIAnimDriver.cs:6-13 说明"复用 RevMono 驱动、不新起隐藏宿主"和"用 unscaledDeltaTime 所以暂停时 UI 照样能播"；Animation\RevUIAnim.cs:264-265 规定"同一控件只留一个动画"（新动画顶掉旧的），避免两个动画抢同一个属性。

代价：自己维护一套缓动与内核（约 7 个文件）；能力上也刻意收窄（不做"缓动强度混合"那类进阶参数）—— 换来的是零依赖、暂停时行为可控、以及全局关掉动画时业务一行都不用改。

决策 9：事件防泄漏做成"机制"，而不是"纪律"

问题：面板注册了全局事件，面板关了却忘了退订 —— 这是 UI 最常见的内存/空引用来源，而且"靠人记得"必然会在某个赶工的下午失守。

做法：注册事件时带上 owner: this，面板关闭/释放时框架一行代码把"登记在它名下的事件"全部摘掉。复用时再兜一次。

源码里长这样：Core\RevUIPanel.cs:27-29 就是这条设计的注释（"机制而非纪律"）；关闭流程里 RevEvent.RemoveAllByOwner(this) 是固定步骤；OnDestroy 里还有一次兜底。

代价：只有"登记在面板名下"的事件才摘得掉 —— 用别的 owner 注册的监听（例如挂在某个长期服务上）仍需自己按生命周期管。

决策 10：Canvas / EventSystem / 图层由框架自建，但不抢项目的

问题：接进任何一个工程，第一道坎都是"UI 根在哪"。让业务自己建 → 每个项目一套摆法、升级框架要重摆；框架强行接管 → 和项目已有的 Canvas / EventSystem 打架。

做法：折中：优先用可替换的预制体（设了路径就加载），载不到就用代码建并给一句警告；EventSystem 只在场景里一个都没有时才兜底创建；图层名统一成一个（默认 UI），框架自己建的东西都归到这一层。

源码里长这样：Implementation\RevUIRoot.cs:96-137（预制体优先、代码兜底）、:229-237 与 :239-254（EventSystem 只兜底、不抢）、Support\RevUISetting.cs:93-99（默认预制体路径）、:114-120（图层名）。

代价：配置项变多（渲染模式、画布架构、相机、图层、EventSystem 开关…），但你可以在不改代码的前提下适配自己的工程。

决策 11：默认单 Canvas，只有必要时才"动静分离"

问题：Unity 的 UI 有一个绕不开的性能特性：同一块 Canvas 上只要有一个元素发生变化，整块 Canvas 的网格就会重建。于是"界面一多就卡"的常见对策是把 Canvas 拆开 —— 常驻不变的放一块、频繁变化的放另一块，让变化不要波及静态内容。要不要默认就这么拆？

做法：默认单 Canvas（简单、少一层心智负担；绝大多数界面根本到不了这个瓶颈），同时提供"三 Canvas 动静分离"作为可选架构：常用（根画布）/ 静态 / 动态三块，面板可以用属性声明自己进哪块。并且明确一条纪律：拆分要靠 Profiler 实测决定，不达标就退回单 Canvas。

源码里长这样：Core\RevUIDefine.cs:129-147 是画布架构与画布类型的定义；:204-221 规定"动静分离时，静态 / 动态子画布只收 Scene 层，其余层一律放回常用画布" —— 否则弹窗会被常用画布里的界面盖住；Implementation\RevUIRoot.cs:199-218 给每个子画布都挂上射线组件（不挂就点不到）；Implementation\RevUIRoot.cs:73、:178 说明这个配置只在根节点创建时读一次，之后不再变。

代价：① 拆分不是免费的：弹窗 / 引导层必须留在最上层画布，混合了静态与动态内容的预制体要自己拆成两个面板才会真的分离；② 收益完全取决于具体界面，必须用 Profiler 对比验收；③ 配置只在第一次打开面板前有效，运行中改没用。

6刻意的取舍与边界

一个框架的成熟度，往往体现在它明确不做什么上。下面这些"故意不这么做"，每一条都能在源码注释里找到原文：

7System / BusinessLogic 要不要做

7.1 为什么不需要（那三条约束都不在）

7.2 那两个"落点"是什么

7.3 什么时候必须重新拆（诚实的边界）

7.4 代价对照（"不做两层"不是偷懒）

8验证结果

这套框架的验证分两层：纯逻辑内核在工程外跑真断言（不开 Unity），整个程序集用 Unity 真实引用编译。

断言跑在"要提交的那份源码"上（工程直接链接真实文件，不是复制品）。它验的都是"写的时候看不错、跑起来才知道"的规则，例如：

• 特性里写 "UI/Panel/"、"\\UI\\Panel\\"、" UI/Panel " → 都得到 UI/Panel（不会拼出双斜杠）；
• 省略资源名 → 取类名；显式写了 → 以显式为准；资源键 = 根目录 + 资源名；
• Popup 层默认挡、Toast 层默认不挡；显式声明永远优先；
• _btnClose / m_title / __x → 节点名 btnClose / title / x（全是下划线时原样返回，不会给出空名字）；
• 只重写了 OnScrollChanged → 只挂滚动监听；一个都没重写 → 连扫子节点都省了；
• 基类与派生类里的 [RevBind] 字段都会被收集，且不重复。

9附：关键文件索引

路径均在 Assets\Revolution\Runtime\RevUISystem\ 下。标注"纯 C#"的文件不引用 UnityEngine，可脱机验证。

10本期没做的（可后续扩展）