basil
/
geometry-tower-defense
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
geometry-tower-defense/docs/UI-5层架构设计规范.md

6.4 KiB
Raw Blame History

UI 五层架构设计规范（RawData / Controller / View / Context / UseCase）

1. 适用范围

  • 适用目录：Assets/GameMain/Scripts/UI/*
  • 重点对象：采用五层拆分的 UI 模块（MenuScene、GameScene、General 下的分层 UI）
  • 本文不展开 Unity GameFramework 底层实现细节，仅约束项目内 UI 代码组织与协作方式

2. 架构总览

UI 模块采用“输入数据 -> 业务编排 -> 展示数据 -> 渲染表现”的分层方式，核心链路如下：

  1. 外部流程（Procedure/GameState）创建并绑定 UseCase
  2. 通过 GameEntry.UIRouter 打开指定 UI
  3. Controller 从 UseCase 取 RawData，并转换为 Context
  4. View 使用 Context 渲染
  5. View 通过事件回传交互，Controller 处理后驱动 UseCase 更新，再刷新 View

简化关系图：

Procedure/GameState
   -> UIRouter
      -> Controller <-> UseCase
      -> Context -> View
View --(CustomEvent)--> Controller

3. 五层职责定义

3.1 RawData 层

职责：承载“业务原始数据”，作为 UseCase 到 Controller 的传输模型。

约束：

  • 命名：XXXFormRawData
  • 只描述数据，不包含 UI 渲染行为
  • 可保留领域对象或数据表对象（例如 DRLevelUpReward、WeaponBase）
  • 不依赖具体 View 组件

参考：

  • Assets/GameMain/Scripts/UI/Template/GameScene/RawData/ShopFormRawData.cs
  • Assets/GameMain/Scripts/UI/Template/GameScene/RawData/LevelUpFormRawData.cs
  • Assets/GameMain/Scripts/UI/Template/MenuScene/RawData/SelectRoleFormRawData.cs

3.2 UseCase 层

职责：封装 UI 对应业务用例，负责业务规则、状态推进、数据生成。

约束：

  • 实现 IUIUseCase
  • 命名：XXXFormUseCase
  • 对外提供 CreateInitialModel / TryRefresh / Select / Confirm 等语义化方法
  • 返回 RawData（或结果对象），不直接操作具体 View

参考：

  • Assets/GameMain/Scripts/UI/Template/GameScene/UseCase/ShopFormUseCase.cs
  • Assets/GameMain/Scripts/UI/Template/GameScene/UseCase/LevelUpFormUseCase.cs
  • Assets/GameMain/Scripts/UI/Template/MenuScene/UseCase/SelectRoleFormUseCase.cs

3.3 Controller 层

职责：UI 编排层，连接 UseCase 与 View，管理 UI 生命周期、事件订阅、数据转换。

约束：

  • 继承 UIFormControllerCommonBase<TContext, TForm>
  • 命名：XXXFormController
  • 通过 BindUseCase(IUIUseCase) 注入用例并做类型校验
  • OpenUI(object userData = null) 支持：Context、RawData、null
  • 负责 RawData -> Context 的转换（常见 BuildContext）
  • 在 SubscribeCustomEvents / UnsubscribeCustomEvents 成对管理事件
  • 可做局部刷新（避免整窗重建）

参考：

  • Assets/GameMain/Scripts/UI/Template/GameScene/Controller/ShopFormController.cs
  • Assets/GameMain/Scripts/UI/Template/GameScene/Controller/LevelUpFormController.cs
  • Assets/GameMain/Scripts/UI/Template/MenuScene/Controller/SelectRoleFormController.cs

3.4 Context 层

职责：承载“可直接驱动 UI 展示”的上下文数据。

约束：

  • 继承 UIContext
  • 命名：XXXFormContext 或 XXXItemContext
  • 字段以展示友好为目标（标题、描述、图标、稀有度、列表等）
  • 允许组合子 Context（例如列表区 + 条目）

参考：

  • Assets/GameMain/Scripts/UI/Template/GameScene/Context/ShopFormContext.cs
  • Assets/GameMain/Scripts/UI/Template/GameScene/Context/DisplayListAreaContext.cs
  • Assets/GameMain/Scripts/UI/Template/MenuScene/Context/SelectRoleFormContext.cs

3.5 View 层

职责：纯表现层，负责控件绑定、显示刷新、交互事件抛出。

约束：

  • Form 类继承 UGuiForm，子组件通常继承 MonoBehaviour
  • 命名：XXXForm / XXXItem / XXXArea
  • 提供 RefreshUI(Context)、OnInit(Context)、OnReset() 等渲染入口
  • 用户交互通过 GameEntry.Event.Fire(...) 通知 Controller
  • 不承载业务规则（计算、流程推进、数据筛选应在 UseCase）

参考：

  • Assets/GameMain/Scripts/UI/Template/GameScene/View/ShopForm.cs
  • Assets/GameMain/Scripts/UI/Template/GameScene/View/DisplayListArea.cs
  • Assets/GameMain/Scripts/UI/Template/MenuScene/View/SelectRoleForm.cs

4. 标准交互流程

4.1 初始化与绑定

  1. Procedure/GameState 创建 UseCase
  2. 调用 GameEntry.UIRouter.BindUIUseCase(UIFormType.X, useCase)

4.2 打开 UI

  1. 调用 GameEntry.UIRouter.OpenUI(UIFormType.X)
  2. Controller 从 UseCase 取 RawData（或接收外部 RawData/Context）
  3. Controller 构建 Context 后打开/刷新 Form
  4. View 在 OnOpen 中校验 Context 类型并执行 RefreshUI

4.3 用户交互到刷新

  1. View 触发事件（如购买、刷新、选择）
  2. Controller 监听事件并调用 UseCase
  3. UseCase 返回新数据或操作结果
  4. Controller 更新 Context 并刷新全部或局部 UI

4.4 关闭 UI

  1. 调用 GameEntry.UIRouter.CloseUI(UIFormType.X)
  2. Controller 解除事件订阅并关闭窗体
  3. View OnClose 清理本地状态

5. 目录与命名规范

  • 目录：UI/<SceneDomain>/RawData|UseCase|Controller|Context|View
  • 五层同名前缀保持一致：ShopForm*、LevelUpForm*、SelectRoleForm*
  • 子组件上下文命名：RoleItemContext、DisplayItemContext、LevelUpRewardItemContext
  • 新增 UI Form 时优先建立完整五层；仅纯静态展示可降级为 View-only

6. 依赖方向约束

允许依赖：

  • UseCase -> RawData / 领域对象
  • Controller -> UseCase + RawData + Context + View + Event
  • View -> Context + Event

禁止依赖：

  • View -> UseCase
  • View -> 领域状态修改
  • Context/RawData -> View

7. 新增一个五层 UI 的落地步骤

  1. 在目标场景目录创建 RawData / UseCase / Context / Controller / View 对应类型
  2. 在 UseCase 中实现模型创建与交互方法
  3. 在 Controller 中实现 BindUseCase、OpenUI、BuildContext、事件订阅
  4. 在 View 中实现 RefreshUI 和交互事件抛出
  5. 在对应 Procedure/GameState 里完成 UseCase 绑定与 Open/Close 调用
  6. 自测三条主链路：首次打开、交互刷新、关闭重开

8. 项目当前实践说明

  • ShopForm、LevelUpForm、SelectRoleForm 是当前五层模式的主要样板
  • DialogForm 也有 Controller/Context/RawData，但 UseCase 为可选
  • HudForm、StartMenuForm 当前为轻用例场景，可不强制 UseCase
  • SettingForm、AboutForm 属于历史直连型 UI，不属于五层完整样板