UnityAI/03_核心功能/UI事件绑定指南.md

# StrayFog 框架 UI事件绑定指南

## 一、事件绑定位置规范

### 1.1 事件绑定位置总览

| 事件类型 | 推荐位置 | 原因 |
|---------|---------|------|
| **UI按钮事件** | `OnRunAwake` | 静态稳定，只需注册一次 |
| **列表拖拽事件** | `OnRunAwake` | 窗口生命周期内持续响应 |
| **全局CTC事件** | `OnOpen`/`OnClose` | 窗口关闭后不应响应 |
| **数据刷新逻辑** | `OnOpen` | 每次打开窗口需刷新 |

### 1.2 推荐绑定模式（防重复注册保护）

```csharp
public class BagWindow : AbsHFUIWindow
{
    private SFUI_Button BtnClose;
    private SFUI_ScrollRect BagListView;

    protected override void OnRunAwake()
    {
        base.OnRunAwake();
        BtnClose = FindUICtrlByName<SFUI_Button>("BtnClose");
        BagListView = FindUICtrlByName<SFUI_ScrollRect>("BagListView");

        // ✅ 按钮事件放在 OnRunAwake（先取消再注册防止重复）
        BtnClose.OnAddClickListener -= OnBtnClose;
        BtnClose.OnAddClickListener += OnBtnClose;

        // ✅ 列表事件也放在 OnRunAwake
        BagListView.OnAddBeginDragListener -= OnBeginDrag;
        BagListView.OnAddBeginDragListener += OnBeginDrag;
    }

    protected override void OnOpen(Action _onOpenComplete)
    {
        base.OnOpen(_onOpenComplete);
        // ✅ 全局CTC事件放在 OnOpen
        HFFunCatalogue.Event.TCEvent.AddListener<HFEvent_BagItemUpdate>(
            enHFCTCEvent.BagItemUpdate, OnBagItemUpdate);
    }

    protected override void OnClose(Action _onCloseComplete)
    {
        // ✅ 全局CTC事件在 OnClose 取消
        HFFunCatalogue.Event.TCEvent.RemoveListener<HFEvent_BagItemUpdate>(
            enHFCTCEvent.BagItemUpdate, OnBagItemUpdate);
        base.OnClose(_onCloseComplete);
    }

    private void OnBtnClose(GameObject go) { /* 按钮点击处理 */ }
    private void OnBeginDrag(GameObject go) { /* 拖拽处理 */ }
    private void OnBagItemUpdate(IHFEventArg<enHFCTCEvent> arg) { /* 数据更新处理 */ }
}
```

### 1.3 防重复注册原理

```csharp
// 先取消注册，再添加注册
BtnLogin.OnAddClickListener -= OnBtnLoginClick;  // 防止重复注册
BtnLogin.OnAddClickListener += OnBtnLoginClick;  // 安全注册
```

**作用**：即使`OnRunAwake`被多次调用（如对象池复用），也不会导致事件重复触发。

---

## 二、SFUI_ScrollRect 绑定模式

### 2.1 列表绑定（推荐）

```csharp
protected override void OnRunAwake()
{
    base.OnRunAwake();
    
    var itemPrefab = FindUICtrlByName<SFUI_Behaviour>("Item");
    BagListView = FindUICtrlByName<SFUI_ScrollRect>("BagListView");
    
    BagListView.BindEvent(
        () => { return m_items.Count; },                    // 数据源数量
        (idx) => { return itemPrefab.gameObject; },         // 实例化模板
        OnUpdateItem,                                       // 更新回调
        (item) => {                                         // 组件获取
            return item.gameObject.HFGetOrAddSimulateBehaviour<BagItemSlot>();
        }
    );
}

private void OnUpdateItem(SFUI_ScrollRectItem item)
{
    var bagItem = item.simulateBehaviour as BagItemSlot;
    bagItem.SetData(m_items[item.dataIdx], m_select, item.dataIdx, OnSelect);
}
```

### 2.2 列表刷新

```csharp
// 刷新整个列表
BagListView.ShowView();

// 刷新指定项
BagListView.RefreshView(null);

// 滚动到指定位置
BagListView.ScrollToIndex(0);
```

---

## 三、事件系统分类

### 3.1 TCEvent（客户端事件）

```csharp
// 注册监听（在 OnOpen 中）
HFFunCatalogue.Event.TCEvent.AddListener<HFEvent_BagItemUpdate>(
    enHFCTCEvent.BagItemUpdate, OnBagItemUpdate);

// 取消监听（在 OnClose 中）
HFFunCatalogue.Event.TCEvent.RemoveListener<HFEvent_BagItemUpdate>(
    enHFCTCEvent.BagItemUpdate, OnBagItemUpdate);
```

### 3.2 STCEvent（服务器事件）

```csharp
// 在 Manager 层注册（UI窗口不直接监听）
HFFunCatalogue.Event.STCEvent.AddListener<HFEvent_STC_GetBagS2C>(
    enHFSTCEvent.GetBag, OnPushBagItem);
```

> **注意**：UI窗口中不直接监听STCEvent，应在Logic层Manager中监听，然后通过TCEvent通知UI。

---

## 四、按钮事件委托

### 4.1 SFUI_Button 事件列表

| 事件 | 委托签名 | 说明 |
|-----|---------|------|
| `OnAddClickListener` | `Click(GameObject go)` | 点击事件 |
| `OnAddEnterListener` | `Enter(GameObject go)` | 鼠标进入 |
| `OnAddExitListener` | `Exit(GameObject go)` | 鼠标退出 |
| `OnAddPointerUpListener` | `PointerUp(GameObject go)` | 指针抬起 |
| `OnAddBeginDragListener` | `BeginDrag(GameObject go)` | 开始拖拽 |
| `OnAddEndDragListener` | `EndDrag(GameObject go)` | 结束拖拽 |

---

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