更新UI相关指南文档 v1.1
修改内容： 1. UI事件绑定指南：新增事件绑定位置规范，强调防重复注册保护，新增SFUI_ScrollRect绑定模式 2. UI窗口开发指南：更新窗口创建流程示例，添加子组件开发示例 3. UI组件使用指南：添加防重复注册保护，新增列表绑定模式和子组件开发规范
This commit is contained in:
Shiliang
@@ -1,90 +1,146 @@
|
||||
# StrayFog 框架 UI事件绑定指南
|
||||
|
||||
## 一、事件绑定方式
|
||||
## 一、事件绑定位置规范
|
||||
|
||||
### 1.1 代码绑定（使用框架封装组件）
|
||||
### 1.1 事件绑定位置总览
|
||||
|
||||
| 事件类型 | 推荐位置 | 原因 |
|
||||
|---------|---------|------|
|
||||
| **UI按钮事件** | `OnRunAwake` | 静态稳定，只需注册一次 |
|
||||
| **列表拖拽事件** | `OnRunAwake` | 窗口生命周期内持续响应 |
|
||||
| **全局CTC事件** | `OnOpen`/`OnClose` | 窗口关闭后不应响应 |
|
||||
| **数据刷新逻辑** | `OnOpen` | 每次打开窗口需刷新 |
|
||||
|
||||
### 1.2 推荐绑定模式（防重复注册保护）
|
||||
|
||||
```csharp
|
||||
public class LoginWindow : AbsHFUIWindow
|
||||
public class BagWindow : AbsHFUIWindow
|
||||
{
|
||||
private SFUI_Button BtnLogin;
|
||||
|
||||
private SFUI_Button BtnClose;
|
||||
private SFUI_ScrollRect BagListView;
|
||||
|
||||
protected override void OnRunAwake()
|
||||
{
|
||||
base.OnRunAwake();
|
||||
// OnRunAwake: 初始化组件引用和按钮事件绑定（仅调用一次）
|
||||
BtnLogin = FindUICtrlByName<SFUI_Button>("BtnLogin");
|
||||
|
||||
if (BtnLogin != null)
|
||||
{
|
||||
BtnLogin.OnAddClickListener += OnBtnLoginClick;
|
||||
BtnLogin.OnAddEnterListener += OnBtnLoginEnter;
|
||||
BtnLogin.OnAddExitListener += OnBtnLoginExit;
|
||||
}
|
||||
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);
|
||||
// OnOpen: 注册CTC事件监听（每次打开调用）
|
||||
HFFunCatalogue.Event.CTCEvent.AddListener<HFEvent_CTC_LoginResult>(
|
||||
enHFCTCEvent.LoginResult, OnLoginResult);
|
||||
// ✅ 全局CTC事件放在 OnOpen
|
||||
HFFunCatalogue.Event.TCEvent.AddListener<HFEvent_BagItemUpdate>(
|
||||
enHFCTCEvent.BagItemUpdate, OnBagItemUpdate);
|
||||
}
|
||||
|
||||
protected override void OnClose(Action _onCloseComplete)
|
||||
{
|
||||
// OnClose: 移除事件监听（每次关闭调用）
|
||||
if (BtnLogin != null)
|
||||
{
|
||||
BtnLogin.OnAddClickListener -= OnBtnLoginClick;
|
||||
BtnLogin.OnAddEnterListener -= OnBtnLoginEnter;
|
||||
BtnLogin.OnAddExitListener -= OnBtnLoginExit;
|
||||
}
|
||||
|
||||
HFFunCatalogue.Event.CTCEvent.RemoveListener<HFEvent_CTC_LoginResult>(
|
||||
enHFCTCEvent.LoginResult, OnLoginResult);
|
||||
|
||||
// ✅ 全局CTC事件在 OnClose 取消
|
||||
HFFunCatalogue.Event.TCEvent.RemoveListener<HFEvent_BagItemUpdate>(
|
||||
enHFCTCEvent.BagItemUpdate, OnBagItemUpdate);
|
||||
base.OnClose(_onCloseComplete);
|
||||
}
|
||||
|
||||
void OnBtnLoginClick(GameObject go)
|
||||
{
|
||||
// 处理登录逻辑 - 使用框架标准调用方式
|
||||
HFEvent_CTC_Login evt = HFFunCatalogue.New<HFEvent_CTC_Login>();
|
||||
evt.account = "player_account";
|
||||
evt.password = "encrypted_password";
|
||||
evt.Dispatch();
|
||||
}
|
||||
|
||||
void OnBtnLoginEnter(GameObject go)
|
||||
{
|
||||
// 鼠标进入
|
||||
}
|
||||
|
||||
void OnBtnLoginExit(GameObject go)
|
||||
{
|
||||
// 鼠标退出
|
||||
}
|
||||
|
||||
void OnLoginResult(HFEventArgBase arg)
|
||||
{
|
||||
// 处理登录结果
|
||||
}
|
||||
private void OnBtnClose(GameObject go) { /* 按钮点击处理 */ }
|
||||
private void OnBeginDrag(GameObject go) { /* 拖拽处理 */ }
|
||||
private void OnBagItemUpdate(IHFEventArg<enHFCTCEvent> arg) { /* 数据更新处理 */ }
|
||||
}
|
||||
```
|
||||
|
||||
### 1.2 框架封装UI组件列表
|
||||
### 1.3 防重复注册原理
|
||||
|
||||
| 组件名 | 基类 | 说明 |
|
||||
|-------|------|------|
|
||||
| `SFUI_Button` | `AbsSFUI_Button : Button` | 按钮组件 |
|
||||
| `SFUI_Text` | `AbsSFUI_Text : Text` | 文本组件 |
|
||||
| `SFUI_Image` | `AbsSFUI_Image : Image` | 图片组件 |
|
||||
| `SFUI_Toggle` | `AbsSFUI_Toggle : Toggle` | 开关组件 |
|
||||
| `SFUI_ScrollRect` | `AbsSFUI_ScrollRect : ScrollRect` | 滚动区域 |
|
||||
| `SFUI_InputField` | `AbsSFUI_InputField : InputField` | 输入框 |
|
||||
```csharp
|
||||
// 先取消注册，再添加注册
|
||||
BtnLogin.OnAddClickListener -= OnBtnLoginClick; // 防止重复注册
|
||||
BtnLogin.OnAddClickListener += OnBtnLoginClick; // 安全注册
|
||||
```
|
||||
|
||||
### 1.3 SFUI_Button事件委托
|
||||
**作用**：即使`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 事件列表
|
||||
|
||||
| 事件 | 委托签名 | 说明 |
|
||||
|-----|---------|------|
|
||||
@@ -92,51 +148,10 @@ public class LoginWindow : AbsHFUIWindow
|
||||
| `OnAddEnterListener` | `Enter(GameObject go)` | 鼠标进入 |
|
||||
| `OnAddExitListener` | `Exit(GameObject go)` | 鼠标退出 |
|
||||
| `OnAddPointerUpListener` | `PointerUp(GameObject go)` | 指针抬起 |
|
||||
| `OnAddBeginDragListener` | `BeginDrag(GameObject go)` | 开始拖拽 |
|
||||
| `OnAddEndDragListener` | `EndDrag(GameObject go)` | 结束拖拽 |
|
||||
|
||||
---
|
||||
|
||||
## 二、事件系统分类
|
||||
|
||||
### 2.1 CTCEvent（客户端内部事件）
|
||||
|
||||
```csharp
|
||||
// 注册监听
|
||||
HFFunCatalogue.Event.CTCEvent.AddListener<HFEvent_CTC_CardUpdate>(
|
||||
enHFCTCEvent.CardUpdate, OnCardUpdate);
|
||||
|
||||
// 触发事件
|
||||
HFEvent_CTC_CardUpdate evt = HFFunCatalogue.New<HFEvent_CTC_CardUpdate>();
|
||||
evt.cardId = 123;
|
||||
HFFunCatalogue.Event.CTCEvent.Dispatch(evt);
|
||||
```
|
||||
|
||||
### 2.2 STCEvent（服务器事件）
|
||||
|
||||
```csharp
|
||||
// 在Manager中注册
|
||||
HFFunCatalogue.Event.STCEvent.AddListener<HFEvent_STC_PlayerInfo>(
|
||||
enHFSTCEvent.PlayerInfo, OnPlayerInfo);
|
||||
```
|
||||
|
||||
> **注意**：UI窗口中不监听STCEvent，应在Logic层Manager中监听。
|
||||
|
||||
---
|
||||
|
||||
## 三、事件参数回收
|
||||
|
||||
### 3.1 使用对象池
|
||||
|
||||
```csharp
|
||||
// 获取事件参数（从对象池获取）
|
||||
HFEvent_CTC_PlayerLevelUp evt = HFFunCatalogue.New<HFEvent_CTC_PlayerLevelUp>();
|
||||
evt.playerId = 1;
|
||||
evt.newLevel = 10;
|
||||
|
||||
// 触发事件（事件系统会自动回收）
|
||||
HFFunCatalogue.Event.CTCEvent.Dispatch(evt);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**版本**: v1.0
|
||||
**版本**: v1.1
|
||||
**适用范围**: GiftGameX项目业务开发人员
|
||||
Reference in New Issue
Block a user