diff --git a/03_核心功能/UI事件绑定指南.md b/03_核心功能/UI事件绑定指南.md new file mode 100644 index 0000000..3f5a1eb --- /dev/null +++ b/03_核心功能/UI事件绑定指南.md @@ -0,0 +1,129 @@ +# StrayFog 框架 UI事件绑定指南 + +## 一、事件绑定方式 + +### 1.1 代码绑定（使用框架封装组件） + +```csharp +public class LoginWindow : AbsHFUIWindow +{ + [SerializeField] private SFUI_Button btn_Login; + + protected override void OnRunAwake() + { + base.OnRunAwake(); + // OnRunAwake: 初始化组件引用和按钮事件绑定（仅调用一次） + btn_Login.OnAddClickListener += OnBtnLogin; + btn_Login.OnAddEnterListener += OnBtnEnter; + btn_Login.OnAddExitListener += OnBtnExit; + } + + protected override void OnOpen(Action _onOpenComplete) + { + base.OnOpen(_onOpenComplete); + // OnOpen: 注册CTC事件监听（每次打开调用） + HFFunCatalogue.Event.CTCEvent.AddListener( + enHFCTCEvent.LoginResult, OnLoginResult); + } + + protected override void OnClose(Action _onCloseComplete) + { + base.OnClose(_onCloseComplete); + // OnClose: 移除CTC事件监听（每次关闭调用） + HFFunCatalogue.Event.CTCEvent.RemoveListener( + enHFCTCEvent.LoginResult, OnLoginResult); + } + + void OnBtnLogin(GameObject go) + { + // 处理登录逻辑 - 使用框架标准调用方式 + HFEvent_CTC_Login evt = HFFunCatalogue.New(); + evt.account = "player_account"; + evt.password = "encrypted_password"; + evt.Dispatch(); + } + + void OnBtnEnter(GameObject go) + { + // 鼠标进入 + } + + void OnBtnExit(GameObject go) + { + // 鼠标退出 + } + + void OnLoginResult(HFEventArgBase arg) + { + // 处理登录结果 + } +} +``` + +### 1.2 框架封装UI组件列表 + +| 组件名 | 基类 | 说明 | +|-------|------|------| +| `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` | 输入框 | + +### 1.3 SFUI_Button事件委托 + +| 事件 | 委托签名 | 说明 | +|-----|---------|------| +| `OnAddClickListener` | `Click(GameObject go)` | 点击事件 | +| `OnAddEnterListener` | `Enter(GameObject go)` | 鼠标进入 | +| `OnAddExitListener` | `Exit(GameObject go)` | 鼠标退出 | +| `OnAddPointerUpListener` | `PointerUp(GameObject go)` | 指针抬起 | + +--- + +## 二、事件系统分类 + +### 2.1 CTCEvent（客户端内部事件） + +```csharp +// 注册监听 +HFFunCatalogue.Event.CTCEvent.AddListener( + enHFCTCEvent.CardUpdate, OnCardUpdate); + +// 触发事件 +HFEvent_CTC_CardUpdate evt = HFFunCatalogue.New(); +evt.cardId = 123; +HFFunCatalogue.Event.CTCEvent.Dispatch(evt); +``` + +### 2.2 STCEvent（服务器事件） + +```csharp +// 在Manager中注册 +HFFunCatalogue.Event.STCEvent.AddListener( + enHFSTCEvent.PlayerInfo, OnPlayerInfo); +``` + +> **注意**：UI窗口中不监听STCEvent，应在Logic层Manager中监听。 + +--- + +## 三、事件参数回收 + +### 3.1 使用对象池 + +```csharp +// 获取事件参数（从对象池获取） +HFEvent_CTC_PlayerLevelUp evt = HFFunCatalogue.New(); +evt.playerId = 1; +evt.newLevel = 10; + +// 触发事件（事件系统会自动回收） +HFFunCatalogue.Event.CTCEvent.Dispatch(evt); +``` + +--- + +**版本**: v1.0 +**适用范围**: GiftGameX项目业务开发人员 \ No newline at end of file diff --git a/03_核心功能/UI窗口开发指南.md b/03_核心功能/UI窗口开发指南.md new file mode 100644 index 0000000..08a8b61 --- /dev/null +++ b/03_核心功能/UI窗口开发指南.md @@ -0,0 +1,81 @@ +# StrayFog 框架 UI窗口开发指南 + +## 一、UI窗口基础 + +### 1.1 窗口创建流程 + +```csharp +[HFAssetBundlePath(enHFLanguageRootFolder.ASSETS_GAME_GAMEHFRESOURCE, "UIWindows/Login/LoginWindow.prefab")] +[HFUIWindowLayer(enHFUICanvasLayer.UIWindow, enHFUIWindowLayer.Dynamic, isIgnoreCloseByESC = false)] +public class LoginWindow : AbsHFUIWindow +{ + protected override void OnRunAwake() + { + base.OnRunAwake(); + // 初始化UI组件引用 + } + + protected override void OnOpen(Action _onOpenComplete) + { + base.OnOpen(_onOpenComplete); + // 注册事件监听 + } + + protected override void OnClose(Action _onCloseComplete) + { + base.OnClose(_onCloseComplete); + // 取消事件监听 + } +} +``` + +### 1.2 窗口打开方式 + +```csharp +// 方式1：直接打开（无回调） +HFFunCatalogue.UIManager.OpenWindow(); + +// 方式2：打开并获取窗口实例（推荐） +HFFunCatalogue.UIManager.OpenWindow((win, args) => { + // win: 打开的窗口实例 + // args: 传入的额外参数 + Debug.Log("窗口打开完成"); +}); + +// 方式3：带额外参数打开 +object[] extraArgs = new object[] { "param1", 123 }; +HFFunCatalogue.UIManager.OpenWindow((win, args) => { + // 使用窗口实例 +}, extraArgs); +``` + +--- + +## 二、窗口生命周期 + +### 2.1 生命周期方法 + +| 方法 | 调用时机 | 说明 | +|-----|---------|------| +| `OnRunAwake` | 窗口创建时调用一次 | 初始化组件引用 | +| `OnOpen` | 每次打开窗口时调用 | 注册事件、刷新数据 | +| `OnClose` | 每次关闭窗口时调用 | 取消事件、清理资源 | +| `OnDestroy` | 窗口销毁时调用 | 释放资源 | + +--- + +## 三、窗口配置属性 + +### 3.1 常用属性 + +| 属性 | 说明 | 默认值 | +|-----|------|-------| +| `isIgnoreCloseByESC` | 是否忽略ESC关闭 | false | +| `isCloseOtherWindow` | 是否关闭其他窗口 | false | +| `isNeedMask` | 是否需要遮罩 | true | +| `maskType` | 遮罩类型 | 半透明 | + +--- + +**版本**: v1.0 +**适用范围**: GiftGameX项目业务开发人员 \ No newline at end of file diff --git a/03_核心功能/UI组件使用指南.md b/03_核心功能/UI组件使用指南.md new file mode 100644 index 0000000..dd3208c --- /dev/null +++ b/03_核心功能/UI组件使用指南.md @@ -0,0 +1,161 @@ +# StrayFog 框架 UI组件使用指南 + +## 一、常用UI组件（框架封装） + +### 1.1 SFUI_Button组件 + +```csharp +SFUI_Button btn = GetComponent(); + +// 添加点击事件 +btn.OnAddClickListener += OnBtnClick; + +// 添加鼠标进入/退出事件 +btn.OnAddEnterListener += OnBtnEnter; +btn.OnAddExitListener += OnBtnExit; + +// 设置按钮状态 +btn.SetSelfGray(true); // 设置灰色不可用 +btn.interactable = false; // 设置不可交互 + +void OnBtnClick(GameObject go) +{ + // 处理点击 +} + +void OnBtnEnter(GameObject go) +{ + // 鼠标进入 +} + +void OnBtnExit(GameObject go) +{ + // 鼠标退出 +} +``` + +### 1.2 SFUI_Text组件 + +```csharp +SFUI_Text txt = GetComponent(); + +// 设置文本 +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(); + +// 加载Sprite +HFFunCatalogue.Sprite.LoadSprite("Icon_Player", sprite => { + img.sprite = sprite; +}); + +// 设置透明度 +img.SetAlpha(0.5f); + +// 设置灰度 +img.SetSelfGray(true); +``` + +### 1.4 SFUI_Toggle组件 + +```csharp +SFUI_Toggle toggle = GetComponent(); + +// 添加状态改变事件 +toggle.onValueChanged.AddListener(OnToggleValueChanged); + +void OnToggleValueChanged(bool isOn) +{ + Debug.Log($"Toggle is {isOn}"); +} +``` + +### 1.5 SFUI_ScrollRect组件 + +```csharp +SFUI_ScrollRect scroll = GetComponent(); + +// 设置滚动位置 +scroll.verticalNormalizedPosition = 1f; + +// 添加滚动事件 +scroll.onValueChanged.AddListener(OnScrollValueChanged); + +void OnScrollValueChanged(Vector2 value) +{ + // 处理滚动 +} +``` + +--- + +## 二、UI组件命名规范 + +### 2.1 命名规则 + +| 组件类型 | 前缀 | 示例 | +|---------|------|-----| +| SFUI_Button | btn | btn_Login | +| SFUI_Text | txt | txt_Title | +| SFUI_Image | img | img_Avatar | +| SFUI_Toggle | toggle | toggle_Select | +| SFUI_ScrollRect | scroll | scroll_Content | +| SFUI_InputField | input | input_Name | + +### 2.2 层级结构 + +``` +WindowRoot/ +├── bg/ # 背景层 +├── content/ # 内容层 +│ ├── header/ # 头部 +│ ├── body/ # 主体 +│ └── footer/ # 底部 +└── top/ # 顶层（弹窗、提示等） +``` + +--- + +## 三、框架封装组件列表 + +| 组件名 | 基类 | 扩展功能 | +|-------|------|---------| +| `SFUI_Button` | Button | 灰色状态、多事件委托 | +| `SFUI_Text` | Text | 描边、阴影扩展 | +| `SFUI_Image` | Image | 灰度、透明度快捷设置 | +| `SFUI_Toggle` | Toggle | 状态改变事件 | +| `SFUI_ScrollRect` | ScrollRect | 滚动优化 | +| `SFUI_InputField` | InputField | 输入限制 | +| `SFUI_Slider` | Slider | 数值范围限制 | +| `SFUI_Dropdown` | Dropdown | 选项管理 | + +--- + +## 四、UI性能优化 + +### 4.1 优化建议 + +- **对象池复用**：频繁创建的UI元素使用对象池 +- **图集打包**：将小图标打包到SpriteAtlas +- **层级优化**：合理设置Canvas层级 +- **避免过度绘制**：减少重叠UI元素 +- **批量操作**：使用RectTransform批量修改 + +--- + +**版本**: v1.0 +**适用范围**: GiftGameX项目业务开发人员 \ No newline at end of file diff --git a/README.md b/README.md index 843ac64..7046f73 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,11 @@ - [资源管理使用指南](03_核心功能/资源管理使用指南.md) - [相机系统使用指南](03_核心功能/相机系统使用指南.md) +**UI开发（组合）：** +- [UI窗口开发指南](03_核心功能/UI窗口开发指南.md) - 窗口创建、生命周期、配置 +- [UI组件使用指南](03_核心功能/UI组件使用指南.md) - SFUI_Button/Text/Image等封装组件 +- [UI事件绑定指南](03_核心功能/UI事件绑定指南.md) - 事件委托绑定、CTC事件监听 + ### 04_开发流程 - [开发流程指南](04_开发流程/开发流程指南.md) - [最佳实践指南](04_开发流程/最佳实践指南.md)