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

StrayFog 框架 UI事件绑定指南

一、事件绑定位置规范

1.1 事件绑定位置总览

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

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

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 防重复注册原理

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

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

---

二、SFUI_ScrollRect 绑定模式

2.1 列表绑定（推荐）

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 列表刷新

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

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

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

---

三、事件系统分类

3.1 TCEvent（客户端事件）

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

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

3.2 STCEvent（服务器事件）

// 在 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项目业务开发人员