https://github.com/gameframex/com.gameframex.unity.ui
https://github.com/gameframex/com.gameframex.unity.ui
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/gameframex/com.gameframex.unity.ui
- Owner: GameFrameX
- License: apache-2.0
- Created: 2024-08-14T07:01:01.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2026-03-02T02:59:37.000Z (4 months ago)
- Last Synced: 2026-03-02T06:41:38.220Z (4 months ago)
- Language: C#
- Size: 232 KB
- Stars: 1
- Watchers: 1
- Forks: 5
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Game Frame X UI
[](LICENSE.md)
[](https://unity3d.com/get-unity/download)
[](package.json)
**Game Frame X UI** 是 GameFrameX 框架的 UI 组件，提供了完整的 UI 管理解决方案，支持 UGUI 和 FairyGUI 两种 UI 系统。
## 📋 目录
- [特性](#特性)
- [安装](#安装)
- [快速开始](#快速开始)
- [核心概念](#核心概念)
- [API 文档](#api-文档)
- [UI 组层级](#ui-组层级)
- [事件系统](#事件系统)
- [最佳实践](#最佳实践)
- [示例代码](#示例代码)
- [依赖项](#依赖项)
- [版本历史](#版本历史)
- [许可证](#许可证)
## ✨ 特性
- 🎯 **统一的 UI 管理接口** - 支持 UGUI 和 FairyGUI
- 🏗️ **分层 UI 系统** - 预定义的 UI 组层级管理
- 🔄 **对象池管理** - 自动回收和复用 UI 实例
- 📡 **事件驱动** - 完整的 UI 生命周期事件
- ⚡ **异步加载** - 支持异步 UI 加载和依赖管理
- 🎨 **灵活配置** - 可配置的 UI 组和辅助器
- 🔧 **编辑器支持** - 完整的 Unity 编辑器集成
## 📦 安装
### 方式一：Package Manager (推荐)
1. 打开 Unity Package Manager
2. 点击 "+" 按钮，选择 "Add package from git URL"
3. 输入以下 URL：
```
https://github.com/gameframex/com.gameframex.unity.ui.git
```
### 方式二：manifest.json
在项目的 `Packages/manifest.json` 文件中添加：
```json
{
"dependencies": {
"com.gameframex.unity.ui": "https://github.com/gameframex/com.gameframex.unity.ui.git"
}
}
```
### 方式三：本地安装
1. 下载或克隆此仓库
2. 将文件夹放置到项目的 `Packages` 目录下
3. Unity 会自动识别并加载包
## 🚀 快速开始
### 1. 添加 UI 组件
在场景中创建一个 GameObject 并添加 `UIComponent` 组件：
```csharp
// 获取 UI 组件
var uiComponent = GameEntry.GetComponent();
```
### 2. 创建 UI 窗体
```csharp
// 继承 UIForm 创建自定义 UI
public class MainMenuUI : UIForm
{
protected override void OnInit(object userData)
{
base.OnInit(userData);
// 初始化 UI 逻辑
}
protected override void OnOpen(object userData)
{
base.OnOpen(userData);
// UI 打开时的逻辑
}
protected override void OnClose(bool isShutdown, object userData)
{
base.OnClose(isShutdown, userData);
// UI 关闭时的逻辑
}
}
```
### 3. 打开和关闭 UI
```csharp
// 打开 UI
uiComponent.OpenUIForm("MainMenuUI", "UI/MainMenu");
// 异步打开 UI
await uiComponent.OpenUIFormAsync("MainMenuUI", "UI/MainMenu");
// 关闭 UI
uiComponent.CloseUIForm("MainMenuUI");
// 关闭所有 UI
uiComponent.CloseAllLoadedUIForms();
```
## 🏗️ 核心概念
### UI 管理器 (IUIManager)
UI 管理器是整个 UI 系统的核心，负责：
- UI 窗体的生命周期管理
- UI 组的管理和层级控制
- 对象池的管理和回收
- 事件的分发和处理
### UI 窗体 (UIForm)
UI 窗体是所有 UI 界面的基类，提供：
- 标准的生命周期方法
- 可见性控制
- 暂停和恢复功能
- 用户数据传递
### UI 组 (UIGroup)
UI 组用于管理 UI 的层级关系，每个组有不同的深度值：
- 深度值越小，显示层级越高
- 支持组内 UI 的排序和管理
- 可配置组的辅助器
## 📚 API 文档
### UIComponent 主要方法
#### 打开 UI 窗体
```csharp
///
/// 打开界面。
///
/// 界面资源名称。
/// 界面组名称。
/// 加载界面资源的优先级。
/// 是否暂停被覆盖的界面。
/// 用户自定义数据。
/// 界面的序列编号。
public int OpenUIForm(string uiFormAssetName, string uiGroupName, int priority = 0, bool pauseCoveredUIForm = true, object userData = null)
///
/// 异步打开界面。
///
/// 界面资源名称。
/// 界面组名称。
/// 加载界面资源的优先级。
/// 是否暂停被覆盖的界面。
/// 用户自定义数据。
/// 界面实例。
public Task OpenUIFormAsync(string uiFormAssetName, string uiGroupName, int priority = 0, bool pauseCoveredUIForm = true, object userData = null)
```
#### 关闭 UI 窗体
```csharp
///
/// 关闭界面。
///
/// 要关闭界面的序列编号。
/// 用户自定义数据。
public void CloseUIForm(int serialId, object userData = null)
///
/// 关闭界面。
///
/// 要关闭的界面。
/// 用户自定义数据。
public void CloseUIForm(IUIForm uiForm, object userData = null)
```
#### 获取 UI 窗体
```csharp
///
/// 获取界面。
///
/// 要获取界面的序列编号。
/// 要获取的界面。
public IUIForm GetUIForm(int serialId)
///
/// 获取界面。
///
/// 要获取界面的资源名称。
/// 要获取的界面。
public IUIForm GetUIForm(string uiFormAssetName)
```
### UIForm 生命周期方法
```csharp
///
/// 界面初始化。
///
/// 用户自定义数据。
protected virtual void OnInit(object userData) { }
///
/// 界面回收。
///
protected virtual void OnRecycle() { }
///
/// 界面打开。
///
/// 用户自定义数据。
protected virtual void OnOpen(object userData) { }
///
/// 界面关闭。
///
/// 是否是关闭界面管理器时触发。
/// 用户自定义数据。
protected virtual void OnClose(bool isShutdown, object userData) { }
///
/// 界面暂停。
///
protected virtual void OnPause() { }
///
/// 界面暂停恢复。
///
protected virtual void OnResume() { }
```
## 🎯 UI 组层级
框架预定义了以下 UI 组层级（按深度值排序）：
| 组名 | 深度值 | 描述 |
|------|--------|------|
| System | -35 | 系统顶级界面 |
| Notify | -30 | 通知界面 |
| Loading | -25 | 加载界面 |
| Dialogue | -23 | 对话界面 |
| BlackBoard | -22 | 黑板界面 |
| Guide | -20 | 引导界面 |
| Tip | -15 | 提示界面 |
| Window | -10 | 窗口界面 |
| Fixed | 0 | 固定界面 |
| Normal | 10 | 普通界面 |
| Floor | 15 | 底板界面 |
| Map | 20 | 地图界面 |
| Hud | 22 | 头顶界面 |
| Battle | 25 | 战斗界面 |
| World | 27 | 世界界面 |
| Scene | 30 | 场景界面 |
| Background | 35 | 背景界面 |
| Hidden | 40 | 隐藏界面 |
## 📡 事件系统
框架提供了完整的 UI 事件系统：
### 事件类型
- `OpenUIFormSuccessEventArgs` - UI 打开成功事件
- `OpenUIFormFailureEventArgs` - UI 打开失败事件
- `CloseUIFormCompleteEventArgs` - UI 关闭完成事件
- `UIFormVisibleChangedEventArgs` - UI 可见性改变事件
### 事件订阅示例
```csharp
// 订阅 UI 打开成功事件
GameEntry.Event.Subscribe(OpenUIFormSuccessEventArgs.EventId, OnOpenUIFormSuccess);
private void OnOpenUIFormSuccess(object sender, GameEventArgs e)
{
var args = (OpenUIFormSuccessEventArgs)e;
Debug.Log($"UI {args.UIForm.UIFormAssetName} 打开成功");
}
```
## 💡 最佳实践
### 1. UI 资源命名规范
```csharp
// 推荐的命名方式
"UI/MainMenu" // 主菜单
"UI/Battle/HUD" // 战斗 HUD
"UI/Shop/ItemList" // 商店物品列表
```
### 2. UI 数据传递
```csharp
// 使用强类型数据类
public class ShopUIData
{
public int PlayerId { get; set; }
public List Items { get; set; }
}
// 打开 UI 时传递数据
var shopData = new ShopUIData { PlayerId = 123, Items = itemList };
uiComponent.OpenUIForm("ShopUI", "Normal", userData: shopData);
// 在 UI 中接收数据
protected override void OnOpen(object userData)
{
var shopData = userData as ShopUIData;
if (shopData != null)
{
// 使用数据初始化 UI
}
}
```
### 3. UI 性能优化
```csharp
// 配置对象池参数
uiComponent.InstanceCapacity = 16; // 对象池容量
uiComponent.InstanceExpireTime = 60f; // 对象过期时间
uiComponent.RecycleInterval = 60; // 回收间隔
```
## 📝 示例代码
### 完整的 UI 窗体示例
```csharp
using GameFrameX.UI.Runtime;
using UnityEngine;
using UnityEngine.UI;
public class MainMenuUI : UIForm
{
[SerializeField] private Button startButton;
[SerializeField] private Button settingsButton;
[SerializeField] private Button exitButton;
protected override void OnInit(object userData)
{
base.OnInit(userData);
// 绑定按钮事件
startButton.onClick.AddListener(OnStartButtonClick);
settingsButton.onClick.AddListener(OnSettingsButtonClick);
exitButton.onClick.AddListener(OnExitButtonClick);
}
protected override void OnOpen(object userData)
{
base.OnOpen(userData);
// 播放打开动画
PlayOpenAnimation();
}
protected override void OnClose(bool isShutdown, object userData)
{
base.OnClose(isShutdown, userData);
// 清理资源
CleanupResources();
}
private void OnStartButtonClick()
{
// 关闭当前 UI 并打开游戏 UI
UIComponent.CloseUIForm(this);
UIComponent.OpenUIForm("GameUI", "Normal");
}
private void OnSettingsButtonClick()
{
// 打开设置 UI
UIComponent.OpenUIForm("SettingsUI", "Window");
}
private void OnExitButtonClick()
{
// 退出游戏
Application.Quit();
}
private void PlayOpenAnimation()
{
// 实现打开动画
}
private void CleanupResources()
{
// 清理资源
}
}
```
### UI 管理器使用示例
```csharp
public class UIManager : MonoBehaviour
{
private UIComponent uiComponent;
private void Start()
{
uiComponent = GameEntry.GetComponent();
// 配置 UI 组件
ConfigureUIComponent();
// 打开主菜单
OpenMainMenu();
}
private void ConfigureUIComponent()
{
// 设置对象池参数
uiComponent.InstanceCapacity = 20;
uiComponent.InstanceExpireTime = 120f;
uiComponent.RecycleInterval = 60;
// 订阅事件
GameEntry.Event.Subscribe(OpenUIFormSuccessEventArgs.EventId, OnUIFormOpenSuccess);
GameEntry.Event.Subscribe(OpenUIFormFailureEventArgs.EventId, OnUIFormOpenFailure);
}
private async void OpenMainMenu()
{
try
{
var mainMenuUI = await uiComponent.OpenUIFormAsync("MainMenuUI", "Normal");
Debug.Log("主菜单打开成功");
}
catch (System.Exception ex)
{
Debug.LogError($"主菜单打开失败: {ex.Message}");
}
}
private void OnUIFormOpenSuccess(object sender, GameEventArgs e)
{
var args = (OpenUIFormSuccessEventArgs)e;
Debug.Log($"UI 打开成功: {args.UIForm.UIFormAssetName}");
}
private void OnUIFormOpenFailure(object sender, GameEventArgs e)
{
var args = (OpenUIFormFailureEventArgs)e;
Debug.LogError($"UI 打开失败: {args.UIFormAssetName}, 错误: {args.ErrorMessage}");
}
}
```
## 🔗 依赖项
此包依赖以下 GameFrameX 组件：
- `com.gameframex.unity` (>= 1.1.1) - 核心框架
- `com.gameframex.unity.asset` (>= 1.0.6) - 资源管理
- `com.gameframex.unity.event` (>= 1.0.0) - 事件系统
- `com.gameframex.unity.localization` (>= 1.0.0) - 本地化支持
## 📋 版本历史
### 2.0.0 (2025-06-12)
- 重大版本更新
- 优化 UI 管理器架构
- 改进对象池性能
### 1.2.7 (2025-06-11)
- 修复 UI 回收后参数重置问题
- 优化异步加载性能
查看完整的 [CHANGELOG.md](CHANGELOG.md) 了解详细的版本历史。
## 📄 许可证
本项目采用 MIT 许可证 - 查看 [LICENSE.md](LICENSE.md) 文件了解详情。
## 🤝 贡献
欢迎提交 Issue 和 Pull Request！
## 📞 联系方式
- 文档地址: https://gameframex.doc.alianblank.com
- 作者: Blank (alianblank@outlook.com)
- 仓库地址: https://github.com/gameframex/com.gameframex.unity.ui
---
**Game Frame X** - 独立游戏前后端一体化解决方案，独立游戏开发者的圆梦大使。