UnityAI/03_核心功能/UI窗口开发指南.md

# StrayFog 框架 UI窗口开发指南

## 一、UI窗口基础

### 1.1 窗口创建流程

```csharp
[HFAssetBundlePath(enHFLanguageRootFolder.ASSETS_GAME_GAMEHFRESOURCE, "UIWindows/Login/LoginWindow.prefab")]
[HFUIWindowLayer(enHFUICanvasLayer.UIWindow, enHFUIWindowLayer.Dynamic, isIgnoreCloseByESC = false)]
public class LoginWindow : AbsHFUIWindow
{
    // ========== UI组件 ==========
    private SFUI_Button BtnLogin;
    private SFUI_InputField InputName;
    private SFUI_InputField InputPassword;
    private SFUI_TextMeshProUGUI TxtTitle;

    protected override void OnRunAwake()
    {
        base.OnRunAwake();
        // 初始化UI组件引用（变量名与组件名保持一致）
        BtnLogin = FindUICtrlByName<SFUI_Button>("BtnLogin");
        InputName = FindUICtrlByName<SFUI_InputField>("InputName");
        InputPassword = FindUICtrlByName<SFUI_InputField>("InputPassword");
        TxtTitle = FindUICtrlByName<SFUI_TextMeshProUGUI>("TxtTitle");

        // 绑定按钮事件
        if (BtnLogin != null)
        {
            BtnLogin.OnAddClickListener += OnBtnLoginClick;
        }
    }

    protected override void OnOpen(Action _onOpenComplete)
    {
        base.OnOpen(_onOpenComplete);
        // 注册事件监听
    }

    protected override void OnClose(Action _onCloseComplete)
    {
        // 取消事件监听
        if (BtnLogin != null)
        {
            BtnLogin.OnAddClickListener -= OnBtnLoginClick;
        }
        base.OnClose(_onCloseComplete);
    }

    private void OnBtnLoginClick(GameObject go)
    {
        // 处理登录逻辑
    }
}
```

### 1.2 窗口打开方式

```csharp
// 方式1：直接打开（无回调）
HFFunCatalogue.UIManager.OpenWindow<LoginWindow>();

// 方式2：打开并获取窗口实例（推荐）
HFFunCatalogue.UIManager.OpenWindow<LoginWindow>((win, args) => {
    // win: 打开的窗口实例
    // args: 传入的额外参数
    Debug.Log("窗口打开完成");
});

// 方式3：带额外参数打开
object[] extraArgs = new object[] { "param1", 123 };
HFFunCatalogue.UIManager.OpenWindow<LoginWindow>((win, args) => {
    // 使用窗口实例
}, extraArgs);
```

---

## 二、窗口生命周期

### 2.1 生命周期方法

| 方法 | 调用时机 | 说明 |
|-----|---------|------|
| `OnRunAwake` | 窗口创建时调用一次 | 初始化组件引用 |
| `OnOpen` | 每次打开窗口时调用 | 注册事件、刷新数据 |
| `OnClose` | 每次关闭窗口时调用 | 取消事件、清理资源 |
| `OnDestroy` | 窗口销毁时调用 | 释放资源 |

---

## 三、窗口配置属性

### 3.1 常用属性

| 属性 | 说明 | 默认值 |
|-----|------|-------|
| `isIgnoreCloseByESC` | 是否忽略ESC关闭 | false |
| `isCloseOtherWindow` | 是否关闭其他窗口 | false |
| `isNeedMask` | 是否需要遮罩 | true |
| `maskType` | 遮罩类型 | 半透明 |

---

**版本**: v1.0  
**适用范围**: GiftGameX项目业务开发人员