更新UI相关指南文档 v1.1

修改内容： 1. UI事件绑定指南：新增事件绑定位置规范，强调防重复注册保护，新增SFUI_ScrollRect绑定模式 2. UI窗口开发指南：更新窗口创建流程示例，添加子组件开发示例 3. UI组件使用指南：添加防重复注册保护，新增列表绑定模式和子组件开发规范
2026-05-22 14:40:44 +08:00
parent 75687450ad
commit 094ae2eedb
3 changed files with 416 additions and 197 deletions
--- a/03_核心功能/UI组件使用指南.md
+++ b/03_核心功能/UI组件使用指南.md
@@ -7,37 +7,31 @@
 ```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)
-{
-    // 鼠标退出
-}
+void OnBtnClick(GameObject go) { /* 处理点击 */ }
+void OnBtnEnter(GameObject go) { /* 鼠标进入 */ }
+void OnBtnExit(GameObject go) { /* 鼠标退出 */ }
 ```

-### 1.2 SFUI_Text组件
+### 1.2 SFUI_TextMeshProUGUI组件

 ```csharp
-SFUI_Text txt = GetComponent<SFUI_Text>();
+SFUI_TextMeshProUGUI txt = GetComponent<SFUI_TextMeshProUGUI>();

 // 设置文本
 txt.text = "Hello World";
@@ -58,16 +52,20 @@ txt.outlineWidth = 2;
 ```csharp
 SFUI_Image img = GetComponent<SFUI_Image>();

-// 加载Sprite
-HFFunCatalogue.Sprite.LoadSprite("Icon_Player", sprite => {
-    img.sprite = sprite;
-});
+// 加载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组件
@@ -76,6 +74,7 @@ img.SetSelfGray(true);
 SFUI_Toggle toggle = GetComponent<SFUI_Toggle>();

 // 添加状态改变事件
+toggle.onValueChanged.RemoveListener(OnToggleValueChanged);
 toggle.onValueChanged.AddListener(OnToggleValueChanged);

 void OnToggleValueChanged(bool isOn)
@@ -84,21 +83,38 @@ void OnToggleValueChanged(bool isOn)
 }
 ```

-### 1.5 SFUI_ScrollRect组件
+### 1.5 SFUI_ScrollRect组件（列表绑定模式）

 ```csharp
 SFUI_ScrollRect scroll = GetComponent<SFUI_ScrollRect>();
+List<ItemInfo> m_items = new List<ItemInfo>();

-// 设置滚动位置
-scroll.verticalNormalizedPosition = 1f;
+// ✅ 列表绑定（推荐方式）
+scroll.BindEvent(
+    () => { return m_items.Count; },                    // 数据源数量
+    (idx) => { return itemPrefab.gameObject; },         // 实例化模板
+    OnUpdateItem,                                       // 更新回调
+    (item) => {                                         // 组件获取
+        return item.gameObject.HFGetOrAddSimulateBehaviour<BagItemSlot>();
+    }
+);

-// 添加滚动事件
-scroll.onValueChanged.AddListener(OnScrollValueChanged);
+// 刷新列表
+scroll.ShowView();                   // 显示视图
+scroll.RefreshView(null);           // 刷新当前视图
+scroll.ScrollToIndex(0);            // 滚动到指定索引

-void OnScrollValueChanged(Vector2 value)
+// 添加拖拽事件
+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) { /* 处理拖拽开始 */ }
 ```

 ---
@@ -111,23 +127,18 @@ void OnScrollValueChanged(Vector2 value)

 | 组件类型 | 示例 |
 |---------|-----|
-| SFUI_Button | BtnLogin |
-| SFUI_Text | TxtTitle |
-| SFUI_Image | ImgAvatar |
+| SFUI_Button | BtnLogin, BtnClose |
+| SFUI_TextMeshProUGUI | TxtTitle, TxtNum |
+| SFUI_Image | ImgIcon, ImgKuang |
 | SFUI_Toggle | ToggleSelect |
-| SFUI_ScrollRect | ScrollContent |
-| SFUI_InputField | InputName |
+| SFUI_ScrollRect | BagListView, ScrollContent |
+| SFUI_InputField | InputName, InputPassword |
+| SFUI_GridLayoutGroup | GridItemContainer |

 **命名约定**：
 - 变量名 = 组件名（保持完全一致）
 - 首字母大写，采用 PascalCase 命名风格
-
-**使用示例**：
-```csharp
-BtnLogin = FindUICtrlByName<SFUI_Button>("BtnLogin");
-TxtTitle = FindUICtrlByName<SFUI_Text>("TxtTitle");
-ImgAvatar = FindUICtrlByName<SFUI_Image>("ImgAvatar");
-```
+- 前缀说明：Btn（按钮）、Txt（文本）、Img（图片）、Toggle（开关）、Scroll（滚动）、Input（输入框）、Grid（网格）

 ### 2.2 层级结构

@@ -135,10 +146,10 @@ ImgAvatar = FindUICtrlByName<SFUI_Image>("ImgAvatar");
 WindowRoot/
 ├── bg/                    # 背景层
 ├── content/               # 内容层
-│   ├── header/            # 头部
-│   ├── body/              # 主体
-│   └── footer/            # 底部
-└── top/                   # 顶层（弹窗、提示等）
+│   ├── header/            # 头部（标签页、标题）
+│   ├── body/              # 主体（列表、内容区）
+│   └── footer/            # 底部（操作按钮）
+└── top/                   # 顶层（弹窗、提示、遮罩）
 ```

 ---
@@ -147,14 +158,16 @@ WindowRoot/

 | 组件名 | 基类 | 扩展功能 |
 |-------|------|---------|
-| `SFUI_Button` | Button | 灰色状态、多事件委托 |
+| `SFUI_Button` | Button | 灰色状态、多事件委托、选中状态 |
 | `SFUI_Text` | Text | 描边、阴影扩展 |
-| `SFUI_Image` | Image | 灰度、透明度快捷设置 |
+| `SFUI_TextMeshProUGUI` | TextMeshProUGUI | 继承原生功能 |
+| `SFUI_Image` | Image | 灰度、透明度快捷设置、Sprite加载 |
 | `SFUI_Toggle` | Toggle | 状态改变事件 |
-| `SFUI_ScrollRect` | ScrollRect | 滚动优化 |
+| `SFUI_ScrollRect` | ScrollRect | **列表绑定模式、滚动优化** |
 | `SFUI_InputField` | InputField | 输入限制 |
 | `SFUI_Slider` | Slider | 数值范围限制 |
 | `SFUI_Dropdown` | Dropdown | 选项管理 |
+| `SFUI_GridLayoutGroup` | GridLayoutGroup | 网格布局 |

 ---

@@ -162,13 +175,82 @@ WindowRoot/

 ### 4.1 优化建议

- **对象池复用**：频繁创建的UI元素使用对象池
- **图集打包**：将小图标打包到SpriteAtlas
- **层级优化**：合理设置Canvas层级
- **避免过度绘制**：减少重叠UI元素
- **批量操作**：使用RectTransform批量修改
+| 优化项 | 说明 | 实现方式 |
+|-------|------|---------|
+| **对象池复用** | 频繁创建的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();
+    }
+}
+```

 ---

-**版本**: v1.0  
+## 五、子组件开发规范
+
+### 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项目业务开发人员