Shiliang/UnityAI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

优化UI开发指南：整合三个文档为一个，精简代码示例，添加文件放置规范

Browse Source
This commit is contained in:
Shiliang
2026-05-22 15:23:11 +08:00
parent 094ae2eedb
commit 6ede453103
5 changed files with 316 additions and 646 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,157 +0,0 @@
# 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项目业务开发人员

315
03_核心功能/UI开发指南.md Normal file
View File

@@ -0,0 +1,315 @@
# StrayFog 框架 UI开发指南
## 一、UI窗口开发
### 1.1 窗口创建模板
```csharp
[HFAssetBundlePath(enHFLanguageRootFolder.ASSETS_GAME_GAMEHFRESOURCE, "UIWindows/MyWindow/MyWindow.prefab")]
[HFUIWindowLayer(enHFUICanvasLayer.UIWindow, enHFUIWindowLayer.Dynamic, isIgnoreCloseByESC = false)]
public class MyWindow : AbsHFUIWindow
{
// UI组件
private SFUI_Button BtnClose;
private SFUI_TextMeshProUGUI TxtTitle;
protected override void OnRunAwake()
{
base.OnRunAwake();
// 初始化UI组件引用
BtnClose = FindUICtrlByName<SFUI_Button>("BtnClose");
TxtTitle = FindUICtrlByName<SFUI_TextMeshProUGUI>("TxtTitle");
// 绑定按钮事件（OnRunAwake只执行一次）
BtnClose.OnAddClickListener += OnBtnClose;
}
protected override void OnOpen(Action _onOpenComplete)
{
base.OnOpen(_onOpenComplete);
// 注册全局事件监听（每次打开都要注册）
HFFunCatalogue.Event.TCEvent.AddListener<HFEvent_DataUpdate>(
enHFCTCEvent.DataUpdate, OnDataUpdate);
// 初始化数据显示
RefreshUI();
}
protected override void OnClose(Action _onCloseComplete)
{
// 取消全局事件监听（每次关闭都要取消）
HFFunCatalogue.Event.TCEvent.RemoveListener<HFEvent_DataUpdate>(
enHFCTCEvent.DataUpdate, OnDataUpdate);
base.OnClose(_onCloseComplete);
}
private void OnBtnClose(GameObject go) => CloseWindow();
private void OnDataUpdate(IHFEventArg<enHFCTCEvent> arg) => RefreshUI();
private void RefreshUI() { /* 更新UI显示 */ }
}
```
### 1.2 窗口生命周期
| 方法 | 调用时机 | 说明 | 推荐操作 |
|-----|---------|------|---------|
| `OnRunAwake` | 窗口创建时调用一次 | 初始化组件引用 | **绑定按钮事件、初始化对象池** |
| `OnRunStart` | OnRunAwake之后调用一次 | 初始化数据 | **配置数据加载** |
| `OnOpen` | 每次打开窗口时调用 | 注册事件、刷新数据 | **注册TC事件、初始化数据显示** |
| `OnClose` | 每次关闭窗口时调用 | 取消事件、清理资源 | **取消TC事件、回收对象池** |
| `OnDestroy` | 窗口销毁时调用 | 释放资源 | **释放非托管资源** |
### 1.3 窗口操作
```csharp
// 打开窗口
HFFunCatalogue.UIManager.OpenWindow<MyWindow>();
// 打开窗口并获取实例
HFFunCatalogue.UIManager.OpenWindow<MyWindow>((win, args) => {
// win: 窗口实例
});
// 关闭窗口
HFFunCatalogue.UIManager.CloseWindow<MyWindow>();
```
---
## 二、事件绑定规范
### 2.1 事件绑定位置
| 事件类型 | 推荐位置 | 原因 | 是否需要 `-=` 防重复 |
|---------|---------|------|-------------------|
| **UI按钮事件** | `OnRunAwake` | 静态稳定，只需注册一次 | ❌ 不需要 |
| **列表拖拽事件** | `OnRunAwake` | 窗口生命周期内持续响应 | ❌ 不需要 |
| **全局TC事件** | `OnOpen`/`OnClose` | 窗口关闭后不应响应 | ✅ 需要 |
| **数据刷新逻辑** | `OnOpen` | 每次打开窗口需刷新 | - |
---
## 三、常用UI组件
### 3.1 SFUI_Button组件
```csharp
SFUI_Button btn = GetComponent<SFUI_Button>();
// 添加事件
btn.OnAddClickListener += OnBtnClick;
btn.OnAddEnterListener += OnBtnEnter;
btn.OnAddExitListener += OnBtnExit;
// 设置状态
btn.SetSelfGray(true); // 灰色不可用
btn.interactable = false; // 不可交互
btn.SetSelected(true); // 选中状态
```
### 3.2 SFUI_TextMeshProUGUI组件
```csharp
SFUI_TextMeshProUGUI txt = GetComponent<SFUI_TextMeshProUGUI>();
txt.text = "Hello World";
txt.color = Color.red;
txt.fontSize = 24;
txt.outlineColor = Color.black;
txt.outlineWidth = 2;
// 动态调整高度
txt.rectTransform.SetSizeWithCurrentAnchors(RectTransform.Axis.Vertical, txt.preferredHeight);
```
### 3.3 SFUI_Image组件
```csharp
SFUI_Image img = GetComponent<SFUI_Image>();
// 加载Sprite
img.HFSetSprite(enHFSpriteAtlas.ASSETS_GAME_GAMEHFRESOURCE_SPRITEATLAS_ITEM,
"Icon_Player",
enHFLanguageRootFolder.ASSETS_GAME_GAMEHFRESOURCE);
// 设置透明度
img.SetAlpha(0.5f);
// 设置灰度
img.SetSelfGray(true);
// 清空Sprite
img.HFClearSprite();
```
### 3.4 SFUI_ScrollRect组件（列表滚动）
SFUI_ScrollRect 专门用于处理多物品的上下滑动列表，提供高效的列表渲染和滚动管理。
```csharp
SFUI_ScrollRect scroll = GetComponent<SFUI_ScrollRect>();
// 绑定列表数据（核心方法）
scroll.BindEvent(
() => itemList.Count, // 数据数量
(idx) => itemPrefab.gameObject, // 获取模板对象
OnUpdateItem, // 更新回调
(item) => item.gameObject.HFGetOrAddSimulateBehaviour<ItemSlot>() // 获取组件
);
// 刷新列表显示
scroll.ShowView();
// 滚动到指定位置
scroll.ScrollToIndex(0); // 滚动到第N项
scroll.verticalNormalizedPosition = 0; // 滚动到底部（1=顶部，0=底部）
```
**使用流程**：
1. 在 `OnRunAwake` 中调用 `BindEvent` 绑定数据
2. 在 `OnOpen` 或数据更新时调用 `ShowView` 刷新显示
3. 通过 `ScrollToIndex` 或 `verticalNormalizedPosition` 控制滚动位置
---
## 四、对象池模式
### 4.1 对象池初始化
```csharp
HFSimulateBehaviourPool<ItemSlot> m_ItemPool = null;
protected override void OnRunAwake()
{
base.OnRunAwake();
SFUI_Button itemPrefab = FindUICtrlByName<SFUI_Button>("ItemPrefab");
SFUI_Behaviour parentContainer = FindUICtrlByName<SFUI_Behaviour>("ParentContainer");
// 创建对象池
m_ItemPool = new HFSimulateBehaviourPool<ItemSlot>(
itemPrefab.gameObject, // 模板对象
parentContainer.gameObject // 父容器
);
}
```
### 4.2 对象池使用
```csharp
private void RefreshItems()
{
// 回收所有已使用对象
m_ItemPool.RecycUsingObject();
// 遍历数据创建新对象
foreach (var data in itemDataList)
{
ItemSlot slot = m_ItemPool.GetItem(out bool isNew);
slot.SetData(data, OnItemClick);
}
}
private void OnItemClick(ItemData data)
{
// 处理点击逻辑
}
```
---
## 五、子组件开发
子组件作为列表项使用，继承 `AbsHFUIWindow`，核心特点：
| 特点 | 说明 |
|-----|------|
| **数据传递** | 通过 `SetData` 方法接收数据 |
| **回调机制** | 通过 `Action<T>` 与父组件通信 |
| **对象池** | 配合 `HFSimulateBehaviourPool<T>` 实现复用 |
---
## 六、UI开发规范
### 6.1 文件放置结构
UI相关文件应按照以下规范组织：
**脚本文件**（.cs）：
```
Assets/Game/GameHFScripte/GameFunction/UIWindows/
├── BagWindow/
│ └── BagWindow.cs # 窗口脚本
├── MainWindow/
│ └── MainWindow.cs
└── Common/
└── ItemSlot.cs # 公共子组件脚本
```
**预制体文件**（.prefab）：
```
Assets/Game/GameHFResource/CN/UIWindows/
├── BagWindow/
│ └── BagWindow.prefab # 窗口预制体
├── MainWindow/
│ └── MainWindow.prefab
└── Common/
└── ItemSlot.prefab # 公共子组件预制体
```
**图片资源**（按UI名称分类）：
```
Assets/Game/GameHFResource/CN/SpriteAtlas/
├── BagWindow/ # 背包窗口相关图片
│ ├── Icon_Bag.png
│ └── Btn_Close.png
├── MainWindow/ # 主窗口相关图片
│ └── Btn_Menu.png
└── Common/ # 公共图片
└── Btn_Confirm.png
```
### 6.2 窗口属性配置
每个窗口必须配置以下属性：
```csharp
[HFAssetBundlePath(enHFLanguageRootFolder.ASSETS_GAME_GAMEHFRESOURCE,
"UIWindows/BagWindow/BagWindow.prefab")]
[HFUIWindowLayer(enHFUICanvasLayer.UIWindow,
enHFUIWindowLayer.Dynamic,
isIgnoreCloseByESC = false)]
public class BagWindow : AbsHFUIWindow
{
// ...
}
```
**路径对应关系**：
- 属性路径：`UIWindows/BagWindow/BagWindow.prefab`
- 实际路径：`Assets/Game/GameHFResource/CN/UIWindows/BagWindow/BagWindow.prefab`
**属性说明**：
| 属性 | 作用 | 必填 |
|-----|------|------|
| `HFAssetBundlePath` | 指定预制体路径，用于资源加载 | ✅ |
| `HFUIWindowLayer` | 指定窗口层级和行为 | ✅ |
| `isIgnoreCloseByESC` | 是否忽略ESC关闭 | ❌ |
### 6.3 性能优化建议
| 优化项 | 说明 | 实现方式 |
|-------|------|---------|
| **对象池复用** | 频繁创建的UI元素使用对象池 | 使用 `HFSimulateBehaviourPool<T>` |
| **图集打包** | 将小图标打包到SpriteAtlas | 在Unity中配置SpriteAtlas |
| **层级优化** | 合理设置Canvas层级 | 使用 `HFUIWindowLayer` 属性 |
| **避免过度绘制** | 减少重叠UI元素 | 合理设计UI布局 |
| **批量操作** | 使用RectTransform批量修改 | 禁用后批量修改再启用 |
| **列表优化** | 使用SFUI_ScrollRect绑定模式 | 自动复用列表项 |
---
**版本**: v1.0
**适用范围**: StrayFog框架项目业务开发人员

228
03_核心功能/UI窗口开发指南.md
View File

@@ -1,228 +0,0 @@
# StrayFog 框架 UI窗口开发指南
## 一、UI窗口基础
### 1.1 窗口创建流程
```csharp
[HFAssetBundlePath(enHFLanguageRootFolder.ASSETS_GAME_GAMEHFRESOURCE, "UIWindows/Bag/BagWindow.prefab")]
[HFUIWindowLayer(enHFUICanvasLayer.UIWindow, enHFUIWindowLayer.Fixed, isIgnoreCloseByESC = false)]
public class BagWindow : AbsHFUIWindow
{
// ========== UI组件 ==========
private SFUI_Button BtnClose;
private SFUI_ScrollRect BagListView;
private BagTips tips;
// ========== 数据 ==========
private List<ItemInfo> m_items = new List<ItemInfo>();
private ItemInfo m_select;
protected override void OnRunAwake()
{
base.OnRunAwake();
// ✅ 初始化UI组件引用
BtnClose = FindUICtrlByName<SFUI_Button>("BtnClose");
BagListView = FindUICtrlByName<SFUI_ScrollRect>("BagListView");
tips = BindUI<BagTips, SFUI_Image>("BagTips");
// ✅ 按钮事件绑定（带防重复注册保护）
BtnClose.OnAddClickListener -= OnBtnClose;
BtnClose.OnAddClickListener += OnBtnClose;
// ✅ 列表绑定
var itemPrefab = FindUICtrlByName<SFUI_Behaviour>("Item");
BagListView.BindEvent(
() => { return m_items.Count; },
(idx) => { return itemPrefab.gameObject; },
OnUpdateItem,
(item) => { return item.gameObject.HFGetOrAddSimulateBehaviour<BagItemSlot>(); }
);
}
protected override void OnOpen(Action _onOpenComplete)
{
base.OnOpen(_onOpenComplete);
// ✅ 注册全局事件监听
HFFunCatalogue.Event.TCEvent.AddListener<HFEvent_BagItemUpdate>(
enHFCTCEvent.BagItemUpdate, OnBagItemUpdate);
// ✅ 初始化数据
RefreshBagItems();
}
protected override void OnClose(Action _onCloseComplete)
{
// ✅ 取消全局事件监听
HFFunCatalogue.Event.TCEvent.RemoveListener<HFEvent_BagItemUpdate>(
enHFCTCEvent.BagItemUpdate, OnBagItemUpdate);
// ✅ 清理资源
tips.Clear();
base.OnClose(_onCloseComplete);
}
private void OnBtnClose(GameObject go) => CloseWindow();
private void OnUpdateItem(SFUI_ScrollRectItem item) { /* 更新列表项 */ }
private void RefreshBagItems() { /* 刷新背包数据 */ }
}
```
### 1.2 窗口打开方式
```csharp
// 方式1：直接打开（无回调）
HFFunCatalogue.UIManager.OpenWindow<BagWindow>();
// 方式2：打开并获取窗口实例（推荐）
HFFunCatalogue.UIManager.OpenWindow<BagWindow>((win, args) => {
Debug.Log("窗口打开完成");
});
// 方式3：带额外参数打开
object[] extraArgs = new object[] { "param1", 123 };
HFFunCatalogue.UIManager.OpenWindow<BagWindow>((win, args) => {
// 使用窗口实例
}, extraArgs);
```
---
## 二、窗口生命周期
### 2.1 生命周期方法
| 方法 | 调用时机 | 说明 | 推荐操作 |
|-----|---------|------|---------|
| `OnRunAwake` | 窗口创建时调用一次 | 初始化组件引用 | **绑定按钮事件、列表初始化** |
| `OnOpen` | 每次打开窗口时调用 | 注册事件、刷新数据 | **注册全局TC事件、初始化数据** |
| `OnClose` | 每次关闭窗口时调用 | 取消事件、清理资源 | **取消全局TC事件、清理UI状态** |
| `OnDestroy` | 窗口销毁时调用 | 释放资源 | **释放非托管资源** |
### 2.2 生命周期流程图
```
窗口创建
↓
OnRunAwake() ──→ 初始化组件、绑定按钮事件
↓
窗口打开（可多次）
↓
OnOpen() ──→ 注册TC事件、刷新数据
↓
窗口关闭（可多次）
↓
OnClose() ──→ 取消TC事件、清理资源
↓
窗口销毁
↓
OnDestroy() ──→ 释放资源
```
---
## 三、窗口配置属性
### 3.1 常用属性
| 属性 | 说明 | 默认值 |
|-----|------|-------|
| `isIgnoreCloseByESC` | 是否忽略ESC关闭 | false |
| `isCloseOtherWindow` | 是否关闭其他窗口 | false |
| `isNeedMask` | 是否需要遮罩 | true |
| `maskType` | 遮罩类型 | 半透明 |
### 3.2 层叠配置
```csharp
[HFUIWindowLayer(enHFUICanvasLayer.UIWindow, enHFUIWindowLayer.Fixed, isIgnoreCloseByESC = false)]
// ↑ Canvas层级 ↑ 窗口层级
```
---
## 四、子组件开发
### 4.1 物品槽组件示例
```csharp
public class BagItemSlot : AbsHFUIWindow
{
private SFUI_Button Btn_Item;
private SFUI_Image Img_Icon;
private SFUI_TextMeshProUGUI Txt_Num;
private Action<ItemInfo, int, Vector3> selectCallback;
private ItemInfo item;
private int m_index;
protected override void OnRunAwake()
{
base.OnRunAwake();
Btn_Item = FindUICtrlByName<SFUI_Button>("Btn_Item");
Img_Icon = FindUICtrlByName<SFUI_Image>("Img_Icon");
Txt_Num = FindUICtrlByName<SFUI_TextMeshProUGUI>("Txt_Num");
Btn_Item.OnAddClickListener -= OnClick;
Btn_Item.OnAddClickListener += OnClick;
}
public void SetData(ItemInfo item, ItemInfo nowSelect, int index, Action<ItemInfo, int, Vector3> onSelect)
{
this.item = item;
this.m_index = index;
this.selectCallback = onSelect;
Img_Icon.HFSetItemIcon(item.ItemConfig.Resource);
Txt_Num.text = item.Info.count.ToString();
}
private void OnClick(GameObject go)
{
selectCallback?.Invoke(item, m_index, go.transform.position);
}
}
```
### 4.2 提示框组件示例
```csharp
public class BagTips : AbsHFUIWindow
{
private SFUI_Image Img_ItemIcon;
private SFUI_TextMeshProUGUI Txt_ItemName;
private SFUI_TextMeshProUGUI Txt_ItemDesc;
public ItemInfo Info { get; private set; }
protected override void OnRunAwake()
{
base.OnRunAwake();
Img_ItemIcon = FindUICtrlByName<SFUI_Image>("Img_ItemIcon");
Txt_ItemName = FindUICtrlByName<SFUI_TextMeshProUGUI>("Txt_ItemName");
Txt_ItemDesc = FindUICtrlByName<SFUI_TextMeshProUGUI>("Txt_ItemDesc");
}
public void SetData(ItemInfo item)
{
Info = item;
Img_ItemIcon.HFSetItemIcon(item.ItemConfig.Resource);
Txt_ItemName.text = item.ItemConfig.NameCN;
Txt_ItemDesc.text = item.ItemConfig.DesLanguageCN;
}
public void Clear()
{
Info = null;
Img_ItemIcon.HFClearSprite();
Txt_ItemName.text = string.Empty;
Txt_ItemDesc.text = string.Empty;
}
}
```
---
**版本**: v1.1
**适用范围**: GiftGameX项目业务开发人员

256
03_核心功能/UI组件使用指南.md
View File

@@ -1,256 +0,0 @@
# StrayFog 框架 UI组件使用指南
## 一、常用UI组件（框架封装）
### 1.1 SFUI_Button组件
```csharp
SFUI_Button btn = GetComponent<SFUI_Button>();
// 添加点击事件（带防重复注册保护）
btn.OnAddClickListener -= OnBtnClick;
btn.OnAddClickListener += OnBtnClick;
// 添加鼠标进入/退出事件
btn.OnAddEnterListener -= OnBtnEnter;
btn.OnAddEnterListener += OnBtnEnter;
btn.OnAddExitListener -= OnBtnExit;
btn.OnAddExitListener += OnBtnExit;
// 设置按钮状态
btn.SetSelfGray(true); // 设置灰色不可用
btn.interactable = false; // 设置不可交互
btn.SetSelected(true); // 设置选中状态
void OnBtnClick(GameObject go) { /* 处理点击 */ }
void OnBtnEnter(GameObject go) { /* 鼠标进入 */ }
void OnBtnExit(GameObject go) { /* 鼠标退出 */ }
```
### 1.2 SFUI_TextMeshProUGUI组件
```csharp
SFUI_TextMeshProUGUI txt = GetComponent<SFUI_TextMeshProUGUI>();
// 设置文本
txt.text = "Hello World";
// 设置颜色
txt.color = Color.red;
// 设置字体大小
txt.fontSize = 24;
// 设置描边
txt.outlineColor = Color.black;
txt.outlineWidth = 2;
```
### 1.3 SFUI_Image组件
```csharp
SFUI_Image img = GetComponent<SFUI_Image>();
// 加载Sprite（使用框架封装方法）
img.HFSetItemIcon("Icon_Player");
// 加载远程图片
img.HFSetUrlSprite("https://example.com/icon.png");
// 设置透明度
img.SetAlpha(0.5f);
// 设置灰度
img.SetSelfGray(true);
// 清空Sprite
img.HFClearSprite();
```
### 1.4 SFUI_Toggle组件
```csharp
SFUI_Toggle toggle = GetComponent<SFUI_Toggle>();
// 添加状态改变事件
toggle.onValueChanged.RemoveListener(OnToggleValueChanged);
toggle.onValueChanged.AddListener(OnToggleValueChanged);
void OnToggleValueChanged(bool isOn)
{
Debug.Log($"Toggle is {isOn}");
}
```
### 1.5 SFUI_ScrollRect组件（列表绑定模式）
```csharp
SFUI_ScrollRect scroll = GetComponent<SFUI_ScrollRect>();
List<ItemInfo> m_items = new List<ItemInfo>();
// ✅ 列表绑定（推荐方式）
scroll.BindEvent(
() => { return m_items.Count; }, // 数据源数量
(idx) => { return itemPrefab.gameObject; }, // 实例化模板
OnUpdateItem, // 更新回调
(item) => { // 组件获取
return item.gameObject.HFGetOrAddSimulateBehaviour<BagItemSlot>();
}
);
// 刷新列表
scroll.ShowView(); // 显示视图
scroll.RefreshView(null); // 刷新当前视图
scroll.ScrollToIndex(0); // 滚动到指定索引
// 添加拖拽事件
scroll.OnAddBeginDragListener -= OnBeginDrag;
scroll.OnAddBeginDragListener += OnBeginDrag;
void OnUpdateItem(SFUI_ScrollRectItem item)
{
var slot = item.simulateBehaviour as BagItemSlot;
slot.SetData(m_items[item.dataIdx]);
}
void OnBeginDrag(GameObject go) { /* 处理拖拽开始 */ }
```
---
## 二、UI组件命名规范
### 2.1 命名规则
变量名直接使用组件名，保持与 Unity 编辑器中组件名称一致。
| 组件类型 | 示例 |
|---------|-----|
| SFUI_Button | BtnLogin, BtnClose |
| SFUI_TextMeshProUGUI | TxtTitle, TxtNum |
| SFUI_Image | ImgIcon, ImgKuang |
| SFUI_Toggle | ToggleSelect |
| SFUI_ScrollRect | BagListView, ScrollContent |
| SFUI_InputField | InputName, InputPassword |
| SFUI_GridLayoutGroup | GridItemContainer |
**命名约定**：
- 变量名 = 组件名（保持完全一致）
- 首字母大写，采用 PascalCase 命名风格
- 前缀说明：Btn（按钮）、Txt（文本）、Img（图片）、Toggle（开关）、Scroll（滚动）、Input（输入框）、Grid（网格）
### 2.2 层级结构
```
WindowRoot/
├── bg/ # 背景层
├── content/ # 内容层
│ ├── header/ # 头部（标签页、标题）
│ ├── body/ # 主体（列表、内容区）
│ └── footer/ # 底部（操作按钮）
└── top/ # 顶层（弹窗、提示、遮罩）
```
---
## 三、框架封装组件列表
| 组件名 | 基类 | 扩展功能 |
|-------|------|---------|
| `SFUI_Button` | Button | 灰色状态、多事件委托、选中状态 |
| `SFUI_Text` | Text | 描边、阴影扩展 |
| `SFUI_TextMeshProUGUI` | TextMeshProUGUI | 继承原生功能 |
| `SFUI_Image` | Image | 灰度、透明度快捷设置、Sprite加载 |
| `SFUI_Toggle` | Toggle | 状态改变事件 |
| `SFUI_ScrollRect` | ScrollRect | **列表绑定模式、滚动优化** |
| `SFUI_InputField` | InputField | 输入限制 |
| `SFUI_Slider` | Slider | 数值范围限制 |
| `SFUI_Dropdown` | Dropdown | 选项管理 |
| `SFUI_GridLayoutGroup` | GridLayoutGroup | 网格布局 |
---
## 四、UI性能优化
### 4.1 优化建议
| 优化项 | 说明 | 实现方式 |
|-------|------|---------|
| **对象池复用** | 频繁创建的UI元素使用对象池 | 使用 `HFClassEntityManager` |
| **图集打包** | 将小图标打包到SpriteAtlas | 在Unity中配置SpriteAtlas |
| **层级优化** | 合理设置Canvas层级 | 使用 `HFUIWindowLayer` 属性 |
| **避免过度绘制** | 减少重叠UI元素 | 合理设计UI布局 |
| **批量操作** | 使用RectTransform批量修改 | 禁用后批量修改再启用 |
| **列表优化** | 使用SFUI_ScrollRect绑定模式 | 自动复用列表项 |
### 4.2 列表性能优化示例
```csharp
// ✅ 使用SFUI_ScrollRect绑定模式（自动复用）
BagListView.BindEvent(
() => { return m_items.Count; },
(idx) => { return itemPrefab.gameObject; },
OnUpdateItem,
(item) => { return item.gameObject.HFGetOrAddSimulateBehaviour<BagItemSlot>(); }
);
// ✅ 数据变化时只刷新必要项
private void OnBagItemUpdate(IHFEventArg<enHFCTCEvent> arg)
{
// 只在数据实际变化时刷新
if (HasDataChanged())
{
BagListView.ShowView();
}
}
```
---
## 五、子组件开发规范
### 5.1 子组件模板
```csharp
public class CustomSlot : AbsHFUIWindow
{
// UI组件
private SFUI_Button Btn_Item;
private SFUI_Image Img_Icon;
// 数据和回调
private Action<ItemInfo> onSelect;
private ItemInfo item;
protected override void OnRunAwake()
{
base.OnRunAwake();
Btn_Item = FindUICtrlByName<SFUI_Button>("Btn_Item");
Img_Icon = FindUICtrlByName<SFUI_Image>("Img_Icon");
// 事件绑定（带防重复保护）
Btn_Item.OnAddClickListener -= OnClick;
Btn_Item.OnAddClickListener += OnClick;
}
public void SetData(ItemInfo item, Action<ItemInfo> onSelect)
{
this.item = item;
this.onSelect = onSelect;
// 更新UI
Img_Icon.HFSetItemIcon(item.ItemConfig.Resource);
}
private void OnClick(GameObject go)
{
onSelect?.Invoke(item);
}
}
```
---
**版本**: v1.1
**适用范围**: GiftGameX项目业务开发人员

6
README.md
View File

@@ -13,11 +13,7 @@
- [事件系统使用指南](03_核心功能/事件系统使用指南.md) - [事件系统使用指南](03_核心功能/事件系统使用指南.md)
- [资源管理使用指南](03_核心功能/资源管理使用指南.md) - [资源管理使用指南](03_核心功能/资源管理使用指南.md)
- [相机系统使用指南](03_核心功能/相机系统使用指南.md) - [相机系统使用指南](03_核心功能/相机系统使用指南.md)
- [UI开发指南](03_核心功能/UI开发指南.md) - 窗口开发、组件使用、事件绑定、对象池、开发规范
**UI开发（组合）：**
- [UI窗口开发指南](03_核心功能/UI窗口开发指南.md) - 窗口创建、生命周期、配置
- [UI组件使用指南](03_核心功能/UI组件使用指南.md) - SFUI_Button/Text/Image等封装组件
- [UI事件绑定指南](03_核心功能/UI事件绑定指南.md) - 事件委托绑定、CTC事件监听
### 04_开发流程 ### 04_开发流程
- [开发流程指南](04_开发流程/开发流程指南.md) - [开发流程指南](04_开发流程/开发流程指南.md)