UnityAI/modules/frameworks/UI窗口系统/README.md

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 初始化：

HFUIWindowMgr.OnAfterCreateInstance()
  -> OnInitializeCanvasAndCamera()
  -> 为 enHFUICanvasLayer 创建 Canvas
  -> 为 ScreenSpaceCamera Canvas 创建 UI Camera
  -> 创建 CacheSiblingIndex Canvas
  -> 创建或接管 EventSystem / StandaloneInputModule

打开窗口：

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()

关闭窗口：

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 架构，更新相关模块文档。

梳理任务

• 梳理窗口基类和打开/关闭 API。
• 梳理窗口 prefab 路径绑定方式。
• 梳理 UIMono 自动绑定和 partial 生成关系。
• 梳理窗口生命周期：Open/Close/状态同步。
• 梳理 UI 事件订阅和释放规范。
• 梳理功能 UI 和框架 UI 的边界。

待确认

• 常规入口已确认是 HFFunCatalogue.UIManager / HFUIWindowMgr，是否存在绕过路径待继续扫描。
• UI 资源会经过 HFAssetBundlePathAttribute 和语言路径规则，哪些 UI 真正有 CN/EN 差异待确认。
• UIMono 是否由编辑器工具生成。
• OnOpen/OnClose 外是否还有业务窗口统一订阅/释放规范待确认。

相关模块

• 资源框架
• 事件框架
• ZYUGUI Tools

---

文档关联

当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。

文档	关联原因
modules/模块索引.md	ZYUGUI Tools
modules/frameworks/事件系统/README.md	事件框架
modules/frameworks/资源管理/README.md	资源框架
rules/10-架构说明.md	架构说明定义总体分层和依赖方向
rules/20-开发规则.md	开发规则与框架/生成规则互相引用
rules/30-模块登记规则.md	模块登记规则定义分类和状态口径
TODO：补充依赖或使用本框架的模块文档	如依赖本框架的功能模块