Skip to content

README.zh-TW.md

Latest commit

 

History

History
160 lines (116 loc) · 5.62 KB

README.zh-TW.md

File metadata and controls

160 lines (116 loc) · 5.62 KB
Game Frame X Logo

GameFrameX UI FairyGUI

License Version Unity Version Documentation

獨立遊戲前後端一體化解決方案 · 獨立遊戲開發者的圓夢大使


文檔 · 快速開始 · QQ群: 467608841 / 233840761


English | 简体中文 | 繁體中文 | 日本語 | 한국어

項目簡介

GameFrameX UI FairyGUI 是一個 Unity UI 適配器，將 FairyGUI 框架封裝到 GameFrameX 模組化遊戲框架中。它提供了完整的 UI 生命週期管理（開啟/關閉/回收/動畫），並透過 YooAsset 實現非同步資源載入。

主要特性

  • 完整 UI 生命週期 — 透過統一 API 實現介面的開啟、關閉、回收和動畫
  • 非同步資源載入 — 基於 YooAsset 的 FairyGUI 包和資源非同步載入
  • 物件池復用 — UI 介面實例被池化復用，最小化 GC 分配
  • 單例去重 — 自動防止重複建立同一介面
  • 載入佇列 — 合併對同一介面的並行開啟請求
  • 屬性驅動配置 — 透過 C# 特性控制 UI 分組、顯示/隱藏動畫
  • MVVM 繫結支援 — 透過 BindablePropertyExtension 自動清理繫結屬性事件
  • 雙模式資源載入 — 同時支援 Resources.Load 和 YooAsset AssetBundle 載入
  • IL2CPP 安全 — Preserve 特性防止 IL2CPP 建置時程式碼裁剪

架構概覽

┌─────────────────────────────────────────────┐
│              你的 UI 面板 (FUI)               │
├─────────────────────────────────────────────┤
│                  UIManager                   │
│      (開啟 / 關閉 / 回收 / 載入佇列)          │
├──────────┬──────────┬───────────────────────┤
│ FormHelper│UIGroup   │ PackageComponent      │
│ (建立/    │Helper    │ (新增包 /             │
│  釋放)    │(深度)    │  移除包)              │
├──────────┴──────────┴───────────────────────┤
│         FairyGUI Runtime + YooAsset          │
└─────────────────────────────────────────────┘
元件 描述
UIManager 核心 UI 管理器，處理開啟/關閉/回收生命週期
FUI 所有 FairyGUI 面板的基底類別 — 繼承此類別建立介面
FairyGUIPackageComponent MonoBehaviour，管理 FairyGUI 包的載入/卸載
FairyGUIFormHelper 處理介面的實例化、建立和釋放
FairyGUIUIGroupHelper 管理 UI 分組深度和層級
FairyGUILoadAsyncResourceHelper 將 FairyGUI 資源請求橋接到 YooAsset
FairyGUIPathFinderHelper 基於路徑的 GObject 查找工具

快速開始

安裝

編輯 Unity 專案的 Packages/manifest.json，添加 scopedRegistries 部分：

{
  "scopedRegistries": [
    {
      "name": "GameFrameX",
      "url": "https://gameframex.upm.alianblank.uk",
      "scopes": [
        "com.gameframex"
      ]
    }
  ]
}

scopes 控制哪些套件透過此註冊表解析。只有以 com.gameframex 開頭的套件才會從這個註冊表取得。

Then add the package to dependencies:

{
  "dependencies": {
    "com.gameframex.unity.ui.fairygui": "3.3.2"
  }
}

使用範例

顯示/隱藏動畫

使用特性配置動畫：

[OptionUIShowAnimation(typeof(FadeInAnimation))]
[OptionUIHideAnimation(typeof(FadeOutAnimation))]
public class AnimatedPanel : FUI { }

基於路徑的物件查找

// 取得 GObject 的層級路徑
string path = gObject.GetUIPath();

// 透過路徑解析 GObject
GObject obj = FairyGUIPathFinderHelper.GetUIFromPath("GRoot/Group/MyButton");

MVVM 繫結自動清理

// GObject 銷毀時自動註銷事件
myProperty.ClearWithGObjectDestroyed(gObject);

平台支援

平台 支援
Android ✅
iOS ✅
Windows ✅
macOS ✅
WebGL ✅

最低 Unity 版本：2019.4

文檔與資源

社區與支援

更新日誌

詳見 CHANGELOG.md。

開源協議

詳見 LICENSE.md 檔案。