整理UI文档：创建UI文件夹，更新README

2026-05-22 16:58:41 +08:00
parent 42fcb5664a
commit 93b718b230
4 changed files with 325 additions and 353 deletions
--- a/03_核心功能/UI/UI开发指南.md
+++ b/03_核心功能/UI/UI开发指南.md
@@ -0,0 +1,154 @@
+# StrayFog 框架 UI开发指南
+
+## 一、窗口开发
+
+### 1.1 创建模板
+```csharp
+[HFAssetBundlePath(enHFLanguageRootFolder.ASSETS_GAME_GAMEHFRESOURCE, "UIWindows/MyWindow/MyWindow.prefab")]
+[HFUIWindowLayer(enHFUICanvasLayer.UIWindow, enHFUIWindowLayer.Dynamic)]
+public class MyWindow : AbsHFUIWindow
+{
+    private SFUI_Button BtnClose;
+
+    protected override void OnRunAwake()
+    {
+        base.OnRunAwake();
+        BtnClose = FindUICtrlByName<SFUI_Button>("BtnClose");
+        BtnClose.OnAddClickListener += OnBtnClose;
+    }
+
+    protected override void OnOpen(Action _onOpenComplete)
+    {
+        base.OnOpen(_onOpenComplete);
+        RefreshUI();
+    }
+
+    private void OnBtnClose(GameObject go) => CloseWindow();
+    private void RefreshUI() { }
+}
+```
+
+### 1.2 生命周期
+
+| 方法 | 调用时机 | 推荐操作 |
+|-----|---------|---------|
+| `OnRunAwake` | 创建时一次 | 绑定UI事件 |
+| `OnOpen` | 每次打开 | 注册TC事件、刷新数据 |
+| `OnClose` | 每次关闭 | 取消TC事件 |
+
+### 1.3 窗口操作
+```csharp
+// 打开
+HFFunCatalogue.UIManager.OpenWindow<MyWindow>();
+// 关闭
+HFFunCatalogue.UIManager.CloseWindow<MyWindow>();
+```
+
+---
+
+## 二、事件绑定
+
+| 事件类型 | 绑定位置 | 是否需要 `-=` |
+|---------|---------|--------------|
+| UI按钮/拖拽 | `OnRunAwake` | 不需要 |
+| 全局TC事件 | `OnOpen`/`OnClose` | 需要 |
+
+---
+
+## 三、常用组件
+
+### 3.1 按钮
+```csharp
+SFUI_Button btn = GetComponent<SFUI_Button>();
+btn.OnAddClickListener += OnBtnClick;
+btn.SetSelfGray(true);
+```
+
+### 3.2 文本
+```csharp
+SFUI_TextMeshProUGUI txt = GetComponent<SFUI_TextMeshProUGUI>();
+txt.text = "Hello";
+```
+
+### 3.3 图片
+```csharp
+SFUI_Image img = GetComponent<SFUI_Image>();
+img.HFSetSprite(/* atlasName */, "Icon_Player", /* languageRoot */);
+```
+
+### 3.4 滚动列表（核心）
+```csharp
+SFUI_ScrollRect scroll = GetComponent<SFUI_ScrollRect>();
+scroll.BindEvent(
+    () => itemList.Count,
+    (idx) => itemPrefab.gameObject,
+    OnUpdateItem,
+    (item) => item.gameObject.HFGetOrAddSimulateBehaviour<ItemSlot>()
+);
+scroll.ShowView();
+```
+
+---
+
+## 四、对象池
+
+| 场景 | 推荐方式 |
+|-----|---------|
+| 滚动列表 | `SFUI_ScrollRect.BindEvent`（内置池） |
+| 固定栏（装备/技能） | `HFSimulateBehaviourPool<T>` |
+
+---
+
+## 五、子组件
+
+### 5.1 多态基类
+```csharp
+public abstract class AbsListItem<T> : AbsHFUIWindow
+{
+    protected SFUI_Button m_BtnItem;
+    protected Action<T> m_OnSelect;
+
+    protected override void OnRunAwake()
+    {
+        base.OnRunAwake();
+        m_BtnItem = gameObject.GetComponent<SFUI_Button>();
+        m_BtnItem.OnAddClickListener += OnBtnClick;
+    }
+
+    public virtual void SetData(T data, Action<T> onSelect = null)
+    {
+        m_OnSelect = onSelect;
+        OnDataChanged(data);
+    }
+
+    protected abstract void OnDataChanged(T data);
+    private void OnBtnClick(GameObject go) => m_OnSelect?.Invoke(m_CurrentData);
+}
+
+// 子类
+public class CardItem : AbsListItem<CardData>
+{
+    protected override void OnDataChanged(CardData data) { }
+}
+```
+
+---
+
+## 六、开发规范
+
+### 6.1 文件路径
+| 类型 | 路径 |
+|-----|------|
+| 脚本 | `Assets/Game/GameHFScripte/GameFunction/UIWindows/{Name}/` |
+| 预制体 | `Assets/Game/GameHFResource/CN/UIWindows/{Name}/` |
+| 图片 | `Assets/Game/GameHFResource/CN/SpriteAtlas/{Name}/` |
+
+### 6.2 性能优化
+- 使用对象池复用UI元素
+- 将图标打包到SpriteAtlas
+- 滚动列表用 `SFUI_ScrollRect.BindEvent`
+
+---
+
+**版本**: v1.0  
+**适用**: StrayFog框架开发人员
--- a/03_核心功能/UI/UI界面拼接设计指南.md
+++ b/03_核心功能/UI/UI界面拼接设计指南.md
@@ -0,0 +1,167 @@
+# UI界面拼接设计指南
+
+## 一、界面结构设计原则
+
+### 1.1 模块化拆分
+将界面按功能划分为独立模块：
+
+| 模块类型 | 功能定位 | 示例 |
+|---------|---------|------|
+| **信息展示区** | 显示玩家状态、资源等静态信息 | 顶部信息栏、左侧状态栏 |
+| **功能入口区** | 提供功能按钮入口 | 中央功能区、底部快捷栏 |
+| **交互面板区** | 可展开/收起的功能面板 | 右侧功能面板、顶部按钮区 |
+| **输入输出区** | 用户输入和系统反馈 | 聊天输入框、提示信息 |
+
+### 1.2 经典布局模式
+
+```
+┌─────────────────────────────────────────────────────┐
+│  TopArea          (信息展示 + 可收起功能按钮)        │
+├──────────┬───────────────────────┬──────────────────┤
+│  Left    │                       │  Right           │
+│  Area    │     CenterArea        │  Area            │
+│ (状态)   │   (核心功能入口)       │ (功能面板)       │
+│          │                       │                  │
+├──────────┴───────────────────────┴──────────────────┤
+│  BottomArea       (快捷功能 + 状态信息 + 输入)       │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## 二、组件拆分方法
+
+### 2.1 基础组件识别
+
+| 组件类型 | 识别特征 | 处理方式 |
+|---------|---------|---------|
+| **按钮** | 可点击、有交互反馈 | 使用 `SFUI_Button` |
+| **文本** | 静态/动态文字显示 | 使用 `SFUI_TextMeshProUGUI` |
+| **图片** | 图标、背景图 | 使用 `SFUI_Image` |
+| **进度条** | HP、MP、经验等 | 使用 `SFUI_Slider` |
+| **列表** | 可滚动的项目列表 | 使用 `SFUI_ScrollRect` |
+
+### 2.2 复合组件封装
+
+将功能相关的基础组件组合为复合组件，便于复用和维护：
+
+**设计原则**：
+- 将同一功能模块的组件封装在一起（如玩家头像+血条+蓝条）
+- 提供统一的数据设置接口
+- 保持组件之间的逻辑独立性
+
+---
+
+## 三、预制体层级规范
+
+### 3.1 标准层级结构
+
+```
+WindowName (RectTransform)
+├── ModuleName (RectTransform)           # 模块容器
+│   ├── ComponentName (SFUI_*)           # 功能组件
+│   ├── SubModule (RectTransform)        # 子模块
+│   └── CollapsibleArea (RectTransform)  # 可收起区域
+└── BtnCollapse (SFUI_Button)            # 收起控制按钮
+```
+
+### 3.2 命名规范
+
+| 类型 | 命名规则 | 示例 |
+|-----|---------|------|
+| 模块容器 | PascalCase + Area | `TopArea` |
+| 功能组件 | PascalCase | `BtnCollapseTop` |
+| 可收起区域 | PascalCase + FuncArea | `TopFuncArea` |
+| 状态变量 | m_ + PascalCase | `m_IsTopCollapsed` |
+
+---
+
+## 四、收起/展开功能设计
+
+### 4.1 功能定义
+
+| 按钮 | 控制区域 | 用途 |
+|-----|---------|------|
+| `BtnCollapseTop` | 顶部功能按钮区 | 收起/展开顶部按钮群 |
+| `BtnCollapseRight` | 右侧功能面板区 | 收起/展开右侧功能面板 |
+
+### 4.2 设计要点
+
+**状态管理**：每个可收起区域需要一个布尔状态变量来记录当前收起/展开状态。
+
+**交互逻辑**：
+1. 点击收起按钮时，切换对应区域的显示/隐藏状态
+2. 同时切换按钮图标（收起时显示展开图标，展开时显示收起图标）
+
+**布局要求**：
+- 收起按钮应放置在对应区域的边缘位置，便于用户找到
+- 收起区域内的所有元素应作为一个整体进行显示/隐藏控制
+- 收起状态应在窗口生命周期内保持记忆
+
+---
+
+## 五、实际案例：主界面拼接
+
+### 5.1 模块化设计思想
+
+**核心原则**：将界面按功能边界划分为独立模块，模块内可嵌套子模块。
+
+**模块归类方法**：
+
+1. **一级模块**：按空间位置划分（顶部、左侧、中央、右侧、底部）
+2. **二级模块**：按功能类型划分（信息展示区、功能按钮区、输入输出区）
+3. **三级模块**：按具体功能划分（玩家头像、资源显示、功能按钮群）
+
+**层级关系示例**：
+
+```
+Window
+├── TopArea (一级：位置)
+│   ├── InfoPanel (二级：信息展示)
+│   │   └── TxtWelcome (三级：具体组件)
+│   └── FuncButtons (二级：功能按钮)
+│       └── BtnUpload (三级：具体按钮)
+└── LeftArea (一级：位置)
+    └── PlayerPortrait (二级：复合组件)
+        ├── ImgAvatar (三级：头像)
+        └── BarHP (三级：血条)
+```
+
+**设计要点**：
+- 同一功能域内的元素归为同一模块（如头像、血条、蓝条归为玩家状态模块）
+- 独立交互功能作为独立模块（如收起按钮单独作为控制模块）
+- 可收起区域作为独立子模块，便于统一控制显示/隐藏
+
+---
+
+## 六、界面拼接流程
+
+### 6.1 设计阶段
+1. **需求分析**：明确界面功能和交互需求
+2. **模块划分**：将界面拆分为独立功能模块
+3. **层级设计**：设计预制体层级结构
+
+### 6.2 开发阶段
+1. **组件创建**：创建基础组件和复合组件
+2. **预制体搭建**：按层级结构搭建预制体
+3. **脚本编写**：实现交互逻辑和收起/展开功能
+
+### 6.3 测试阶段
+1. **功能测试**：验证所有按钮和交互功能
+2. **收起测试**：测试收起/展开功能正常工作
+3. **适配测试**：验证不同分辨率下的显示效果
+
+---
+
+## 七、注意事项
+
+1. **组件复用**：相同功能的组件尽量复用，减少冗余
+2. **状态管理**：收起状态需要正确保存和恢复
+3. **图标反馈**：收起按钮图标应随状态变化
+4. **性能优化**：可收起区域使用 `SetActive` 而非销毁重建
+5. **命名规范**：统一的命名规则便于维护和查找
+
+---
+
+**版本**: v1.0  
+**适用**: StrayFog框架UI拼接开发人员