UI 系统 · 使用说明

〇它是干什么的

先花 30 秒建立直觉，再动手写。

// ① 声明一个面板：特性写"预制体在哪个目录、哪个名字"
[RevUIPanel("UI/Bag", RevUILayer.Normal, "BagPanel")]
public class BagPanel : RevUIPanel
{
    protected override void OnBindView() { }        // ② 唯一必须实现的方法：这里做绑定
    protected override void OnClick(string nodeName) // ③ 点哪个按钮就走这里（不用手动挂监听）
    {
        if (nodeName == "BtnClose") RequestClose();
    }
}

// 打开 / 关闭（业务里就这两行）
RevUI.Open<BagPanel>();
RevUI.Close<BagPanel>();

一3 分钟写出第一个面板

准备：一个预制体放在资源根目录的 UI/Bag/BagPanel.prefab。

// ① 新建脚本 BagPanel.cs —— 就这么短，能跑
using UnityEngine;

[RevUIPanel("UI/Bag", RevUILayer.Normal, "BagPanel")]
public class BagPanel : RevUIPanel
{
    // RevUIPanel 是抽象类，这个方法必须实现 —— 做"拿组件、填初始内容"的事
    protected override void OnBindView()
    {
        // 例：拿到预制体里名为 Title 的文本并设置
        // (按你项目的绑定方式：RevBind 特性 / 自己 GetComponentInChildren)
    }

    protected override void OnOpen()
    {
        // 每次打开都会走这里：刷新数据、播开场动画
    }

    // 点了预制体里名为 BtnClose 的按钮（名字对得上就会进来）
    protected override void OnClick(string nodeName)
    {
        switch (nodeName)
        {
            case "BtnClose": RequestClose(); break;
            case "BtnSort":  SortBag();      break;
        }
    }
}

// ② 业务里打开它（哪都能调，不用挂物体）
RevUI.Open<BagPanel>();

// ③ 打开后拿到实例做点事
RevUI.Open<BagPanel>(panel => panel.RefreshView());

// ④ 关闭（面板内部也可以 RequestClose()）
RevUI.Close<BagPanel>();

控件事件的三种接法（挑一种就用，能混用）

同一个控件的事件，框架给三条路 —— 都可用、可混用，按场景挑：

方法特性一共九个（标在面板 / Part 的任意方法上），覆盖全部控件事件：

// 控件名 = 节点名（区分大小写）；写多级路径时只取最后一段（"Top/btnStart" 等价于 "btnStart"）
[RevButtonClick("btnStart")]       void OnStart()      => StartGame();      // 点击
[RevButtonLongPress("btnSkill")]   void OnSkillHold()  => ShowSkillTip();   // 长按（按住 ≥ 0.5s 后松开）
[RevButtonLoosen("btnMove")]       void OnMoveUp()     => StopMove();       // 松开（指针在控件上抬起）
[RevToggleChanged("tglSound")]     void OnSound(bool on)              => SetSound(on);
[RevSliderChanged("sldVolume")]    void OnVolume(float v)             => SetVolume(v);
[RevInputChanged("inpName")]       void OnName(string text)           => Preview(text);   // 单参数 = 文本
[RevInputEndEdit("inpName")]       void OnNameDone(string text)       => Submit(text);
[RevDropdownChanged("ddlQuality")] void OnQuality(int index)          => SetQuality(index);
[RevScrollChanged("scrollList")]   void OnScrolled(float x, float y)  => LoadMore(y);

// 同一个控件可以挂多个方法（都会被调用）；想同时要"节点名 + 值"就用两参数 / 三参数的形状
[RevButtonClick("btnBuy")]         void OnBuy(string nodeName)              => Buy(nodeName);
[RevToggleChanged("tglSound")]     void OnSound2(string nodeName, bool on)  => Log(nodeName, on);

二面板的生命周期（谁先谁后）

只要记住"创建一次、打开很多次"这一点，其余照着图用。

protected override void PlayOpenTransition(Action onDone)  { /* 播动画，结束后 */ onDone?.Invoke(); }
protected override void PlayCloseTransition(Action onDone) { onDone?.Invoke(); }

三"我要做 X" 对照表（全部 API）

入口统一是 RevUI（动画入口是 RevUIAnim，见第五节"动画"一节）。所有泛型参数都要求 T : RevUIPanel。

四带数据的面板（一个面板多处复用）

同一个界面既要显示"英雄详情"又要显示"道具详情"时，用泛型面板传数据。

// ① 数据类随便定义（class / struct 都行）
public class DetailData { public int Id; public string Title; }

// ② 面板继承 RevUIPanel<TData>：重写 OnDataChanged 收数据
[RevUIPanel("UI/Common", RevUILayer.Normal, "DetailPanel")]
public class DetailPanel : RevUIPanel<DetailData>
{
    protected override void OnBindView() { }                 // 仍需实现（做绑定）
    protected override void OnRefreshView() { }               // 用 _data 刷新显示
    protected override void OnDataChanged(DetailData oldData, DetailData newData)
    {
        // 数据换了：刷新界面（最常写的地方）
    }
}

// ③ 打开时传进去
RevUI.Open<DetailPanel, DetailData>(new DetailData { Id = 1001, Title = "亚瑟" });

// ④ 已经开着时再传一份新数据（不会重开面板）
RevUI.Get<DetailPanel>()?.SetData(new DetailData { Id = 1002, Title = "妲己" });

五层级 / 遮罩 / 返回栈

都在特性上声明，不用写代码。

[RevUIPanel("UI/Common", RevUILayer.Popup, "ConfirmDialog",
            CacheMode   = RevUICacheMode.Unspecified,   // 缓存策略（默认按框架规则）
            Mask        = RevUIMaskMode.Auto,          // 遮罩：弹窗默认自动加
            ExclusiveGroup = "Dialog",               // 互斥组：同组只留一个
            InBackStack = true)]                       // 是否进返回栈（Back() 能关它）

UI 根 Canvas 从哪来（默认：加载框架自带预制体）

• 默认渲染模式是 ScreenSpaceOverlay ✓（不需要相机、UI 永远最上层）—— 要改就设 RevUISetting.CanvasMode；
• 框架默认加载 Resources/RevUIPrefab/RevUICanvas.prefab 来渲染 ✓（Overlay / 1920×1080 / match 0.5 / sortingOrder 100）；
• 载不到就代码兜底 ✓：预制体缺失或路径写错时，框架自己建 Canvas + CanvasScaler + GraphicRaycaster，并打一条 Warning 说明原因 —— 不会出现"整屏 UI 起不来"；
• 想改用相机模式（UI 可被 3D 遮挡 / 能进 RenderTexture）：

RevUISetting.CanvasMode          = RevUICanvasMode.ScreenSpaceCamera;
RevUISetting.UICameraPrefabPath  = "RevUIPrefab/RevUICamera";   // 默认就是这个；也可直接 RevUISetting.UICamera = cam
RevUISetting.CanvasPlaneDistance = 100f;

什么时候才切换到三 Canvas？

1. 在目标机型的典型场景中用 Profiler 测量 UI 合批（Canvas.BuildBatch）、重建 / 布局（Canvas.SendWillRenderCanvases）与总帧时间，记录帧率、Draw Call 和项目自己的帧预算。
2. 若超预算，先解决无意义的逐帧文本 / 布局更新、过多的射线检测、持续运行的动画以及长列表没有虚拟化等问题，按同一测试条件复测。若达到目标，继续使用单 Canvas。
3. 只有确定 Canvas 合批仍是主要瓶颈，且单 Canvas 优化后仍不达标，才在第一次打开面板之前启用三 Canvas：

RevUISetting.CanvasArchitecture = RevUICanvasArchitecture.Split;

[RevUIPanel("UI/Main", RevUILayer.Scene, CanvasType = RevUICanvasType.Static)]
public sealed class MainBackgroundPanel : RevUIPanel
{
    protected override void OnBindView() { }
}

[RevUIPanel("UI/Main", RevUILayer.Scene, CanvasType = RevUICanvasType.Dynamic)]
public sealed class MainHudPanel : RevUIPanel
{
    protected override void OnBindView() { }
}

Static 放常驻且基本不变的 Scene 内容，Dynamic 放常驻且频繁变化的 Scene 内容；Common（默认）放其余所有面板。 现有混合静态/动态内容的预制体若要分到两个画布，需要拆成两个 Scene 面板，只配置一个属性不会自动把面板内部控件分离。 Normal / Popup / Toast / Guide / Top 声明成 Static 或 Dynamic 会被放回 Common 并告警，以保证弹窗和引导遮罩位于最上层。 切换后继续测 CPU 合批和 Draw Call；没有改善就退回单 Canvas。详见《架构解析》第五章 · 决策 11。

面板 / Part / 控件的动画（一行加动效，不依赖 DOTween）

框架自带一套 UI 专用的轻量动画库（代码在 Runtime\RevUISystem\Animation\，入口 RevUIAnim）：零第三方依赖 ✓、每帧零 GC ✓、掉帧不改变动画总时长 ✓（采样模型 + 帧余量结转）。

面板：一行预设属性（显示动画播完才算"打开完成" ✓，隐藏动画播完才真正回收 ✓）：

[RevUIPanel("UI/Panel")]
public sealed class BagPanel : RevUIPanel<BagData>
{
    protected override RevUIAnimPreset ShowAnimation => RevUIAnimPreset.PopIn;    // 打开时自动播
    protected override RevUIAnimPreset HideAnimation => RevUIAnimPreset.PopOut;   // 关闭时自动播（播完才关）

    // 想自己掌控节奏（与预设并存；★ 结束时必须调 onDone）
    protected override void PlayOpenTransition(Action onDone)
        => RevUIAnim.SlideIn(this, RevUISlideDirection.Top, 0.25f, onDone, owner: this);
}

Part 同理（重写 ShowAnimation ✓）。任意控件直接用门面（面板自己 / Image / Text / Button / RectTransform / CanvasGroup 都能传 ✓）：

RevUIAnim.FadeIn(icon);                                        // 淡入
RevUIAnim.SlideIn(this, RevUISlideDirection.Top);              // 从上滑入
RevUIAnim.ScaleTo(icon, 1.2f, 0.12f);                          // 缩放到 1.2 倍（相对基准缩放）
RevUIAnim.FadeTo(icon, 0.5f);                                  // 淡到半透明
RevUIAnim.Breathe(tipIcon);                                    // 呼吸（透明度 0.45 ↔ 1 来回）
RevUIAnim.Breathe(tipIcon, useScale: true);                    // 换成缩放呼吸
RevUIAnim.AddHoverFeedback(btnClose);                          // 按钮：悬停放大 + 按下缩小
RevUIAnim.Play(icon, RevUIAnimPreset.PopIn, 0.3f, () => Tip("播完"), owner: this);
RevUIAnim.ApplyEnd(panel, RevUIAnimPreset.PopIn);              // 跳过动画：直接落到终态
RevUIAnim.StopAllOf(this);                                     // 停掉这个对象的全部动画

门面 API 一览（真实签名，可直接抄）：

六新手最容易踩的 6 个坑

进阶：另外 6 条（多数和"复用 / 生命周期"有关）

七相关文档

• 《UI 系统 · 架构解析》 —— 设计论证：面板池策略、绑定机制、层级与遮罩的实现、为什么会复用
• 《资源加载系统 · 使用说明》 —— 面板里加载图标的正确姿势（记得 Release）
• 《公共 Mono 模块 · 使用说明》 —— 面板里要每帧跑的逻辑怎么写
• 文档总入口 · 在线文档站