094ae2eedb
修改内容： 1. UI事件绑定指南：新增事件绑定位置规范，强调防重复注册保护，新增SFUI_ScrollRect绑定模式 2. UI窗口开发指南：更新窗口创建流程示例，添加子组件开发示例 3. UI组件使用指南：添加防重复注册保护，新增列表绑定模式和子组件开发规范
157 lines
4.7 KiB
Markdown
157 lines
4.7 KiB
Markdown
# 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项目业务开发人员 |