129 lines
5.2 KiB
Markdown
129 lines
5.2 KiB
Markdown
|
# UI 框架
|
|||
|
|
|
|||
|
|
## 分类
|
|||
|
|
|
|||
|
|
- 项目框架
|
|||
|
|
|
|||
|
|
## 目的
|
|||
|
|
|
|||
|
|
记录 UIWindow 管理、窗口基类、UIMono 桥接、窗口资源加载和 UI 生命周期。
|
|||
|
|
|
|||
|
|
## 已知线索
|
|||
|
|
|
|||
|
|
- 管理路径：`Assets/Game/GameHFScripte/CopyToHF/UIWindowMgr/`
|
|||
|
|
- 窗口实现：`Assets/Game/GameHFScripte/GameFunction/UIWindows/`
|
|||
|
|
- Mono 桥接：`Assets/Game/GameMono/Scripts/UIMono/`
|
|||
|
|
- 资源路径：`Assets/Game/GameHFResource/CN/UIWindows/`
|
|||
|
|
|
|||
|
|
## 已确认链路
|
|||
|
|
|
|||
|
|
UI manager 初始化：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
HFUIWindowMgr.OnAfterCreateInstance()
|
|||
|
|
-> OnInitializeCanvasAndCamera()
|
|||
|
|
-> 为 enHFUICanvasLayer 创建 Canvas
|
|||
|
|
-> 为 ScreenSpaceCamera Canvas 创建 UI Camera
|
|||
|
|
-> 创建 CacheSiblingIndex Canvas
|
|||
|
|
-> 创建或接管 EventSystem / StandaloneInputModule
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
打开窗口：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
HFFunCatalogue.UIManager.OpenWindow<T>()
|
|||
|
|
-> HFUIWindowMgr.OnOpenWindow<HFUIWindowSetting>()
|
|||
|
|
-> 创建 HFDefaultTask / HFUIWindow_RespondTask
|
|||
|
|
-> 读取窗口类型上的 HFAssetBundlePathAttribute 和 HFUIWindowLayerAttribute
|
|||
|
|
-> OnSettingWindowSiblingIndex()
|
|||
|
|
-> 从缓存队列复用窗口实例，或 Activator.CreateInstance 创建窗口逻辑实例
|
|||
|
|
-> OnPreloadWindowInMemory()
|
|||
|
|
-> HFABMgr.Instance.LoadInMemory(windowPrefabPath)
|
|||
|
|
-> win.BindGameObject(prefab)
|
|||
|
|
-> OnAttachWindow(win)
|
|||
|
|
-> win.SyncWindowState()
|
|||
|
|
-> AbsHFUIWindow.OnOpen()
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
关闭窗口：
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
CloseWindow<T>() / AbsHFUIWindow.CloseWindow()
|
|||
|
|
-> HFUIWindowMgr.OnCloseWindow()
|
|||
|
|
-> siblingIndexLayer.ToggleWindowActive(false)
|
|||
|
|
-> 放入 mCacheWindowInstanceMaping
|
|||
|
|
-> 处理 backtrack 自动恢复窗口
|
|||
|
|
-> win.SyncWindowState()
|
|||
|
|
-> AbsHFUIWindow.OnClose()
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
窗口资源绑定：
|
|||
|
|
|
|||
|
|
- 窗口类通过 `[HFAssetBundlePath(...)]` 标记 prefab 路径。
|
|||
|
|
- 窗口类通过 `[HFUIWindowLayer(...)]` 标记 Canvas/Layer 和是否允许多开。
|
|||
|
|
- `AbsHFUIWindowSetting.SetWindowType` 会读取上述 attribute，生成 `winId`、`winTypeId` 和资源路径。
|
|||
|
|
|
|||
|
|
## 使用规则
|
|||
|
|
|
|||
|
|
- 新窗口必须继承 `AbsHFUIWindow`。
|
|||
|
|
- 新窗口必须配置 `HFAssetBundlePath` 和 `HFUIWindowLayer`。
|
|||
|
|
- 打开窗口统一走 `HFFunCatalogue.UIManager.OpenWindow<T>()`。
|
|||
|
|
- 关闭窗口统一走 `CloseWindow()` 或 `HFFunCatalogue.UIManager.CloseWindow<T>()`。
|
|||
|
|
- 在 `OnOpen` 中注册的事件必须在 `OnClose` 中移除。
|
|||
|
|
- 不直接 `Instantiate` / `Destroy` UI 窗口 prefab。
|
|||
|
|
- 不绕过 `HFUIWindowMgr` 手动修改窗口 active、父节点或 siblingIndex。
|
|||
|
|
- 普通业务窗口默认使用 `Dynamic`，提示类优先使用 `Tooltip`，强交互弹窗优先使用 `Popup`，`Highest` 仅用于明确的顶层兜底。
|
|||
|
|
- UI prefab 放在 `Assets/Game/GameHFResource/<语言>/UIWindows/<模块>/`，代码中的 `HFAssetBundlePath` 使用相对 `UIWindows/...` 的路径。
|
|||
|
|
- 优先使用项目已有 UIMono / ZYUGUI 绑定流程，不手写大量 `transform.Find`。
|
|||
|
|
- 列表、循环列表、网格优先使用已有 ZYUGUI / SuperScrollView 组件和编辑器转换工具。
|
|||
|
|
- 异步加载或动画结束后再调用完成回调时，必须保证失败/取消路径不会卡住窗口状态。
|
|||
|
|
|
|||
|
|
## 新增 UI 窗口清单
|
|||
|
|
|
|||
|
|
1. 确认窗口所属功能模块。
|
|||
|
|
2. 创建窗口类，继承 `AbsHFUIWindow`。
|
|||
|
|
3. 添加 `HFAssetBundlePath` 和 `HFUIWindowLayer`。
|
|||
|
|
4. 创建或更新 prefab。
|
|||
|
|
5. 使用 UIMono / ZYUGUI 生成或绑定 UI 引用。
|
|||
|
|
6. 用 `HFFunCatalogue.UIManager.OpenWindow<T>()` 接入入口。
|
|||
|
|
7. 在 `OnOpen` / `OnClose` 对称处理事件、计时器、临时数据。
|
|||
|
|
8. 验证打开、关闭、重复打开、切场景或语言变化时的表现。
|
|||
|
|
9. 如果新增模块或改变 UI 架构，更新相关模块文档。
|
|||
|
|
|
|||
|
|
## 梳理任务
|
|||
|
|
|
|||
|
|
- [x] 梳理窗口基类和打开/关闭 API。
|
|||
|
|
- [x] 梳理窗口 prefab 路径绑定方式。
|
|||
|
|
- [ ] 梳理 UIMono 自动绑定和 partial 生成关系。
|
|||
|
|
- [x] 梳理窗口生命周期：Open/Close/状态同步。
|
|||
|
|
- [x] 梳理 UI 事件订阅和释放规范。
|
|||
|
|
- [x] 梳理功能 UI 和框架 UI 的边界。
|
|||
|
|
|
|||
|
|
## 待确认
|
|||
|
|
|
|||
|
|
- 常规入口已确认是 `HFFunCatalogue.UIManager` / `HFUIWindowMgr`，是否存在绕过路径待继续扫描。
|
|||
|
|
- UI 资源会经过 `HFAssetBundlePathAttribute` 和语言路径规则，哪些 UI 真正有 CN/EN 差异待确认。
|
|||
|
|
- UIMono 是否由编辑器工具生成。
|
|||
|
|
- `OnOpen`/`OnClose` 外是否还有业务窗口统一订阅/释放规范待确认。
|
|||
|
|
|
|||
|
|
## 相关模块
|
|||
|
|
|
|||
|
|
- [资源框架](../资源管理/README.md)
|
|||
|
|
- [事件框架](../事件系统/README.md)
|
|||
|
|
- [ZYUGUI Tools](../../模块索引.md#编辑器工具)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 文档关联
|
|||
|
|
|
|||
|
|
> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
|
|||
|
|
|
|||
|
|
| 文档 | 关联原因 |
|
|||
|
|
|---|---|
|
|||
|
|
| [modules/模块索引.md](../../模块索引.md) | ZYUGUI Tools |
|
|||
|
|
| [modules/frameworks/事件系统/README.md](../事件系统/README.md) | 事件框架 |
|
|||
|
|
| [modules/frameworks/资源管理/README.md](../资源管理/README.md) | 资源框架 |
|
|||
|
|
| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
|
|||
|
|
| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | 开发规则与框架/生成规则互相引用 |
|
|||
|
|
| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
|
|||
|
|
| TODO：补充依赖或使用本框架的模块文档 | 如依赖本框架的功能模块 |
|