# 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：补充依赖或使用本框架的模块文档 | 如依赖本框架的功能模块 |