【整合】框架使用规则

2026-07-10 17:50:20 +08:00
parent db0143be83
commit 001d9e5ef5
45 changed files with 1716 additions and 4062 deletions
--- a/modules/frameworks/UI窗口系统/README.md
+++ b/modules/frameworks/UI窗口系统/README.md
@@ -1,129 +1,66 @@
-# UI 框架
-
-## 分类
-
- 项目框架
+# UI 窗口系统

 ## 目的

-记录 UIWindow 管理、窗口基类、UIMono 桥接、窗口资源加载和 UI 生命周期。
+记录 StrayFog 窗口管理、资源加载、生命周期、UIMono 绑定和虚拟列表的稳定使用规则。

-## 已知线索
+## 主要路径

- 管理路径：`Assets/Game/GameHFScripte/CopyToHF/UIWindowMgr/`
- 窗口实现：`Assets/Game/GameHFScripte/GameFunction/UIWindows/`
- Mono 桥接：`Assets/Game/GameMono/Scripts/UIMono/`
- 资源路径：`Assets/Game/GameHFResource/CN/UIWindows/`
+| 类型 | 路径 | 说明 |
+|---|---|---|
+| ESF 源码 | `Assets/StrayFog/Editor/CopyToX/CopyToHF/UIWindowMgr/` | 窗口框架真实源码 |
+| HF 生成代码 | `Assets/Game/GameHFScripte/CopyToHF/UIWindowMgr/` | CopyToX 结果，禁止手改 |
+| 业务窗口 | `Assets/Game/GameHFScripte/GameFunction/UIWindows/` | 窗口与子组件业务逻辑 |
+| Mono 组件 | `Assets/Game/GameMono/Scripts/UIMono/` | SFUI/UIMono 和列表包装 |
+| UI 资源 | `Assets/Game/GameHFResource/<语言>/UIWindows/` | Prefab 与窗口资源 |

-## 已确认链路
-
-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()
+  -> HFUIWindowMgr 创建窗口任务
+  -> 读取 HFAssetBundlePath / HFUIWindowLayer
+  -> 复用缓存或创建窗口逻辑
+  -> LoadInMemory 加载 Prefab
+  -> BindGameObject / OnAttachWindow
+  -> OnRunAwake（实例首次绑定）
+  -> OnOpen（每次打开）
 ```

-关闭窗口：
+关闭窗口会执行 `OnClose`、隐藏实例并放入窗口缓存。需要释放窗口与资源时使用 UI 管理器公开卸载入口，不直接 Destroy 窗口 Prefab 或绕过管理器修改父节点和 siblingIndex。

-```text
-CloseWindow<T>() / AbsHFUIWindow.CloseWindow()
-  -> HFUIWindowMgr.OnCloseWindow()
-  -> siblingIndexLayer.ToggleWindowActive(false)
-  -> 放入 mCacheWindowInstanceMaping
-  -> 处理 backtrack 自动恢复窗口
-  -> win.SyncWindowState()
-  -> AbsHFUIWindow.OnClose()
-```
+## 生命周期

-窗口资源绑定：
+| 生命周期 | 用途 |
+|---|---|
+| `OnRunAwake` | 查找控件、绑定按钮、配置并初始化虚拟列表，只执行一次 |
+| `OnOpen` | 注册本次打开所需事件、刷新数据与显示状态 |
+| `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 组件和编辑器转换工具。
- 异步加载或动画结束后再调用完成回调时，必须保证失败/取消路径不会卡住窗口状态。
+- 窗口继承 `AbsHFUIWindow`，配置 `HFAssetBundlePath` 和 `HFUIWindowLayer`。
+- 打开和关闭统一通过 `HFFunCatalogue.UIManager`。
+- `OnOpen` 与 `OnClose` 中的事件注册和释放保持对称。
+- 引用绑定优先使用项目 UIMono/SFUI 流程，不堆叠 `transform.Find`。
+- 单列虚拟列表使用 LoopListView2 包装接口，多列布局使用 LoopGridView 包装接口。
+- 模板节点在 Prefab 中保持禁用，由虚拟列表创建实例。
+- UI 修改必须验证脚本、Prefab 层级、RectTransform、组件状态和运行时效果。

-## 新增 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#编辑器工具)
-
---
+- [UI 开发指南](开发指南.md)
+- [界面拼接](界面拼接.md)
+- [UI 拼接工具](../编辑器工具/UI拼接工具.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：补充依赖或使用本框架的模块文档 | 如依赖本框架的功能模块 |
+| [模块索引](../../模块索引.md) | 模块入口和状态 |
+| [资源管理](../资源管理/README.md) | UI Prefab 加载与卸载 |
+| [事件系统](../事件系统/README.md) | 窗口事件生命周期 |
+| [架构说明](../../../rules/10-架构说明.md) | ESF/HF 源码边界 |
+| [开发规则](../../../rules/20-开发规则.md) | UI 与 Prefab 通用约束 |