# StrayFog 框架 UI开发指南

## 一、窗口开发

### 1.1 创建模板
```csharp
[HFAssetBundlePath(enHFLanguageRootFolder.ASSETS_GAME_GAMEHFRESOURCE, "UIWindows/MyWindow/MyWindow.prefab")]
[HFUIWindowLayer(enHFUICanvasLayer.UIWindow, enHFUIWindowLayer.Dynamic)]
public class MyWindow : AbsHFUIWindow
{
    private SFUI_Button BtnClose;

    protected override void OnRunAwake()
    {
        base.OnRunAwake();
        BtnClose = FindUICtrlByName<SFUI_Button>("BtnClose");
        BtnClose.OnAddClickListener += OnBtnClose;
    }

    protected override void OnOpen(Action _onOpenComplete)
    {
        base.OnOpen(_onOpenComplete);
        RefreshUI();
    }

    private void OnBtnClose(GameObject go) => CloseWindow();
    private void RefreshUI() { }
}
```

### 1.2 生命周期

| 方法 | 调用时机 | 推荐操作 |
|-----|---------|---------|
| `OnRunAwake` | 创建时一次 | 绑定UI事件 |
| `OnOpen` | 每次打开 | 注册TC事件、刷新数据 |
| `OnClose` | 每次关闭 | 取消TC事件 |

### 1.3 窗口操作
```csharp
// 打开
HFFunCatalogue.UIManager.OpenWindow<MyWindow>();
// 关闭
HFFunCatalogue.UIManager.CloseWindow<MyWindow>();
```

---

## 二、事件绑定

| 事件类型 | 绑定位置 | 是否需要 `-=` |
|---------|---------|--------------|
| UI按钮/拖拽 | `OnRunAwake` | 不需要 |
| 全局TC事件 | `OnOpen`/`OnClose` | 需要 |

---

## 三、常用组件

### 3.1 按钮
```csharp
SFUI_Button btn = GetComponent<SFUI_Button>();
btn.OnAddClickListener += OnBtnClick;
btn.SetSelfGray(true);
```

### 3.2 文本
```csharp
SFUI_TextMeshProUGUI txt = GetComponent<SFUI_TextMeshProUGUI>();
txt.text = "Hello";
```

### 3.3 图片
```csharp
SFUI_Image img = GetComponent<SFUI_Image>();
img.HFSetSprite(/* atlasName */, "Icon_Player", /* languageRoot */);
```

### 3.4 滚动列表（核心）
```csharp
SFUI_ScrollRect scroll = GetComponent<SFUI_ScrollRect>();
scroll.BindEvent(
    () => itemList.Count,
    (idx) => itemPrefab.gameObject,
    OnUpdateItem,
    (item) => item.gameObject.HFGetOrAddSimulateBehaviour<ItemSlot>()
);
scroll.ShowView();
```

---

## 四、对象池

| 场景 | 推荐方式 |
|-----|---------|
| 滚动列表 | `SFUI_ScrollRect.BindEvent`（内置池） |
| 固定栏（装备/技能） | `HFSimulateBehaviourPool<T>` |

---

## 五、子组件

### 5.1 多态基类
```csharp
public abstract class AbsListItem<T> : AbsHFUIWindow
{
    protected SFUI_Button m_BtnItem;
    protected Action<T> m_OnSelect;

    protected override void OnRunAwake()
    {
        base.OnRunAwake();
        m_BtnItem = gameObject.GetComponent<SFUI_Button>();
        m_BtnItem.OnAddClickListener += OnBtnClick;
    }

    public virtual void SetData(T data, Action<T> onSelect = null)
    {
        m_OnSelect = onSelect;
        OnDataChanged(data);
    }

    protected abstract void OnDataChanged(T data);
    private void OnBtnClick(GameObject go) => m_OnSelect?.Invoke(m_CurrentData);
}

// 子类
public class CardItem : AbsListItem<CardData>
{
    protected override void OnDataChanged(CardData data) { }
}
```

---

## 六、开发规范

### 6.1 文件路径

#### 6.1.1 核心资源路径

| 类型 | 路径 | 说明 |
|-----|------|------|
| **窗口脚本** | `Assets/Game/GameHFScripte/GameFunction/UIWindows/{WindowName}/` | 窗口逻辑脚本存放目录 |
| **窗口预制体** | `Assets/Game/GameHFResource/CN/UIWindows/{WindowName}/` | UI窗口预制体存放目录 |
| **图标图集** | `Assets/Game/GameHFResource/CN/SpriteAtlas/{AtlasName}/` | SpriteAtlas图集资源 |
| **字体资源** | `Assets/Game/GameHFResource/CN/Fonts/` | 字体文件存放目录 |

#### 6.1.2 工具脚本路径

| 工具名称 | 路径 | 职责 |
|---------|------|------|
| **UIPrefabGenerator** | `Assets/Editor/Command/UIPrefabGenerator.cs` | JSON转UI预制体 |
| **UIPrefabToJson** | `Assets/Editor/Command/UIPrefabToJson.cs` | 预制体转JSON |
| **RemoteCommand** | `Assets/Editor/Command/RemoteCommand.cs` | 外部命令接口 |
| **ExternalCommandListener** | `Assets/Editor/Command/ExternalCommandListener.cs` | 外部命令监听器 |

#### 6.1.3 文档路径

| 文档名称 | 路径 |
|---------|------|
| UI开发指南 | `UnityAI/03_核心功能/UI/UI开发指南.md` |
| UI界面拼接设计指南 | `UnityAI/03_核心功能/UI/UI界面拼接设计指南.md` |

#### 6.1.4 命令触发路径

- **触发文件**: `{ProjectRoot}/Trigger_Command.txt`
- **JSON配置**: `Assets/Editor/UI/{WindowName}.json`

### 6.2 性能优化
- 使用对象池复用UI元素
- 将图标打包到SpriteAtlas
- 滚动列表用 `SFUI_ScrollRect.BindEvent`

---

**版本**: v1.0  
**适用**: StrayFog框架开发人员