@gongxh/bit-ui 0.0.1 → 0.0.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 bit老宫
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,243 +1,161 @@
-## UI模块 
-
-### 特点
-
-  * 基于FairyGUI, 查看[FairyGUI官方文档](https://www.fairygui.com/docs/editor)
-  
-  * 灵活的 UI 装饰器（配合插件  `kunpo-fgui` 使用，一键导出界面配置，省时省力省代码）
-  
-  * 控制窗口之间的相互关系（eg: 打开界面时，是隐藏/关闭前一个界面，还是隐藏/关闭所有界面）
-  
-  * 多窗口组管理
-  
-  * 顶部显示金币钻石的资源栏（header），一次实现，多界面复用，
-  
-  * 支持不同界面使用不同 header
-
-### 插件链接
-* **kunpo-fgui**: [https://store.cocos.com/app/detail/7213](https://store.cocos.com/app/detail/7213)
-
-### 使用
-
-#### *一、FairyGUI界面*
-> ![image-fgui-project](../image/image-fgui-project.png#pic_left)
-
-#### *二、UI 装饰器使用*
-
-> 注：只有使用了装饰器的内容才能在 `kunpo-fgui` 插件中识别，`kunpo-fgui`插件操作界面如下图
-
-> ![image-fgui-editor](../image/image-fgui-editor.png#pic_left)
-
-
-1. 窗口装饰器
-
-   ```typescript
-   import { Window, _uidecorator } from 'bit-ui';
-   const { uiclass, uiprop, uiclick } = _uidecorator;
-   
-   /** 
-   * 窗口装饰器
-   * @param 参数1: 窗口容器节点名字
-   * @param 参数2: FairyGUI中的UI包名
-   * @param 参数3: FairyGUI中的组件名 必须和 class 类同名 这里是 MyWindow
-   */
-   @uiclass("Window", "UI包名", "MyWindow")
-   export class MyWindow extends Window {
-       // ... 窗口实现
-   }
-   ```
-
-2. Header 装饰器
-
-   ```typescript
-   import { WindowHeader, _uidecorator } from 'bit-ui';
-   const { uiheader } = _uidecorator;
-   
-   /** 
-   * 窗口顶部资源栏装饰器
-   * @param 参数1: FairyGUI中的UI包名
-   * @param 参数2: FairyGUI中的组件名 必须和 class 类同名 这里是 MyWindowHeader
-   */
-   @uiheader("UI包名", "WindowHeader")
-   export class MyWindowHeader extends WindowHeader {
-       // ... Header 实现
-   }
-   ```
-
-3. UI组件装饰器
-
-   ```typescript
-   import { _uidecorator } from 'bit-ui';
-   const { uicom, uiprop, uiclick } = _uidecorator;
-   
-   /** 
-   * UI组件类装饰器
-   * @param 参数1: FairyGUI中的UI包名
-   * @param 参数2: FairyGUI中的组件名 必须和 class 类同名 这里是 MyComponent
-   */
-   @uicom("Home", "MyComponent")
-   export class MyComponent {
-       // ... 组件实现
-   }
-   ```
-
-4. UI属性装饰器
-
-   ```typescript
-   import { Window, _uidecorator } from 'bit-ui';
-   const { uiclass, uiprop, uiclick } = _uidecorator;
-   
-   @uiclass("Window", "Home", "MyWindow")
-   export class MyWindow extends Window {
-       // FairyGUI 组件属性装饰器
-       @uiprop private btnConfirm: GButton;  // 按钮组件
-       @uiprop private txtTitle: GTextField; // 文本组件
-       @uiprop private listItems: GList;     // 列表组件
-   }
-   ```
-   
-5. 点击事件装饰器
-
-   ```typescript
-   import { Window, _uidecorator } from 'bit-ui';
-   const { uiclass, uiprop, uiclick } = _uidecorator;
-   
-   @uiclass("Window", "Home", "MyWindow")
-   export class MyWindow extends Window {
-       // 点击事件装饰器
-       @uiclick
-       private onTouchEvent(event: cc.Event): void {
-           console.log('确认按钮被点击');
-       }
-   }
-   ```
-   
-6. 控制器和动画装饰器
-
-   ```typescript
-   import { Window, _uidecorator } from 'bit-ui';
-   const { uiclass, uiprop, uiclick, uicontrol, uitransition } = _uidecorator;
-   
-   @uiclass("Window", "Home", "MyWindow")
-   export class MyWindow extends Window {
-       // FairyGUI 组件属性装饰器
-       @uicontrol private control: Controller;
-       @uitransition private transition: Transition;
-   }
-   ```
-
-   
-#### *三、创建窗口*
-
-1. 新建窗口类
-
-   ```typescript
-   /**
-   * 窗口名必须和FairyGUI中的组件同名
-   */
-   import { Window, _uidecorator } from 'bit-ui';
-   const { uiclass, uiprop, uiclick } = _uidecorator;
-   
-   @uiclass("Window", "UI包名", "MyWindow")
-   export class MyWindow extends Window {
-       protected onInit(): void {
-           // 初始化窗口
-       }
-   
-       protected onShow(userdata?: any): void {
-           // 窗口显示时的逻辑
-       }
-   
-       protected onClose(): void {
-           // 窗口关闭时的逻辑
-       }
-   }
-   ```
-
-2. 窗口生命周期
-- `onInit`: 窗口初始化时调用
-- `onShow`: 窗口显示时调用
-- `onClose`: 窗口关闭时调用
-- `onHide`: 窗口隐藏时调用
-- `onShowFromHide`: 窗口从隐藏状态恢复时调用
-- `onCover`: 窗口被覆盖时调用
-- `onRecover`: 窗口恢复时调用
-- `onEmptyAreaClick`: 点击窗口空白区域时调用
-
-#### *四、窗口资源加载配置*
-```typescript
-interface IPackageConfig {
-    /** UI所在resources中的路径 */
-    uiPath: string;
-    /** 
-     * 手动管理资源的包
-     * 1. 用于基础UI包, 提供一些最基础的组件，所有其他包都可能引用其中的内容
-     * 2. 资源header所在的包
-     * 3. 用于一些特殊场景, 比如需要和其他资源一起加载, 并且显示进度条的包
-     */
-    manualPackages: string[];
-    /** 
-     * 不推荐配置 只是提供一种特殊需求的实现方式
-     * 窗口引用到其他包中的资源 需要的配置信息
-     */
-    linkPackages: { [windowName: string]: string[] };
-
-    /**
-     * 关闭界面后，需要立即释放资源的包名（建议尽量少）
-     * 一般不建议包进行频繁装载卸载，因为每次装载卸载必然是要消耗CPU时间（意味着耗电）和产生大量GC的。UI系统占用的内存是可以精确估算的，你可以按照包的使用频率设定哪些包是需要立即释放的。
-     * 不包括手动管理的包 
-     */
-    imReleasePackages: string[];
-}
-
-export interface IPackageConfigRes {
-    /** 配置信息 */
-    config: IPackageConfig;
-    /** 显示加载等待窗 */
-    showWaitWindow: () => void;
-    /** 隐藏加载等待窗 */
-    hideWaitWindow: () => void;
-    /** 打开窗口时UI包加载失败 */
-    fail: (windowName: string, errmsg: string, pkgs: string[]) => void;
-}
+# bit-ui
+
+基于 FairyGUI 的 UI 管理系统，提供灵活的窗口管理和装饰器支持。
+
+## 简介
+
+`bit-ui` 是基于 FairyGUI 的 UI 管理库，提供窗口生命周期管理、资源自动加载、多窗口组管理等功能。支持配套的可视化编辑器一键导出界面配置。
+
+**核心特性**：
+- 🎨 灵活的 UI 装饰器
+- 🪟 完整的窗口生命周期管理
+- 📦 自动资源加载和卸载
+- 🎯 窗口间关系控制（隐藏/关闭前一个界面）
+- 🎪 多窗口组管理
+- 📊 Header 资源栏复用
+- 🖥️ 配套可视化编辑器（付费插件）
+
+**依赖**：
+- FairyGUI - [官方文档](https://www.fairygui.com/docs/editor)
+
+## 安装
+
+```bash
+npm install @gongxh/bit-ui
 ```
 
-#### *五、窗口管理接口*
-   ```typescript
-   export class WindowManager {
-     	/** 
-     	 * 配置UI包的一些信息 (可以不配置 完全手动管理资源) 
-     	 */
-   		public static initPackageConfig(res: IPackageConfigRes): void;
-     
-       /**
-        * 异步打开一个窗口 (如果UI包的资源未加载, 会自动加载 配合 WindowManager.initPackageConfig一起使用)
-        */
-       public static showWindow(windowName: string, userdata?: any): Promise<void>
-   
-       /**
-        * 打开一个窗口 (用于已加载过资源的窗口)
-        */
-       public static showWindowIm(windowName: string, userdata?: any): void;
-   
-       /**
-        * 关闭窗口
-        */
-       public static closeWindow(windowName: string);
-
-       /* 
-        * 获取窗口实例
-        */
-       public static getWindow<T extends Window>(windowName: string): T;
-
-       /**
-        * 获取当前最顶层窗口
-        */
-       public static getTopWindow(): Window;
-
-       /**
-        * 检查窗口是否存在
-        */
-       public static hasWindow(windowName: string): boolean;
-   }
-   ```
+## 可视化编辑器
+
+提供专业的 FairyGUI 配置编辑器，支持快速配置和导出。
+
+**下载地址**：[Cocos Store - kunpo-fgui](https://store.cocos.com/app/detail/7213)
+
+## 使用说明
+
+### UI 装饰器
+
+使用装饰器简化 UI 组件定义和配置。
+
+**窗口装饰器**：
+- `@uiclass(groupName, pkgName, name, inlinePkgs?)` - 注册窗口类
+  - `groupName` - 窗口组名称
+  - `pkgName` - FairyGUI 包名
+  - `name` - 组件名（必须和类名相同）
+  - `inlinePkgs` - 内联的包名（可选，当前界面引用其他包资源时使用）
+
+**Header 装饰器**：
+- `@uiheader(pkgName, name)` - 注册 Header 类
+  - 用于定义窗口顶部资源栏
+
+**UI 组件装饰器**：
+- `@uicom(pkgName, name)` - 注册自定义 UI 组件类
+
+**属性装饰器**：
+- `@uiprop` - 标记 FairyGUI 组件属性（按钮、文本、列表等）
+- `@uicontrol` - 标记 FairyGUI 控制器
+- `@uitransition` - 标记 FairyGUI 动画
+
+**事件装饰器**：
+- `@uiclick` - 标记点击事件处理函数
+
+### 窗口基类 (Window)
+
+所有窗口的基类，提供完整的生命周期。
+
+**生命周期方法**：
+- `onInit()` - 窗口初始化
+- `onShow(userdata?)` - 窗口显示
+- `onHide()` - 窗口隐藏
+- `onClose()` - 窗口关闭
+- `onShowFromHide()` - 从隐藏状态恢复
+- `onToTop()` - 窗口到顶层
+- `onToBottom()` - 窗口到底层
+- `onEmptyAreaClick()` - 点击空白区域
+- `onAdapted()` - 窗口适配完成
+
+### Header 基类 (Header)
+
+窗口顶部资源栏基类，支持多窗口复用。
+
+**生命周期方法**：
+- `onInit()` - Header 初始化
+- `onShow(userdata?)` - Header 显示
+- `onHide()` - Header 隐藏
+- `onClose()` - Header 关闭
+- `onShowFromHide()` - 从隐藏状态恢复
+- `onAdapted()` - 适配完成
+
+### 窗口管理器 (WindowManager)
+
+全局窗口管理器，负责窗口的创建、显示、关闭等。
+
+**配置方法**：
+- `setPackageCallbacks(callbacks)` - 设置 UI 包加载回调
+  - `callbacks.showWaitWindow` - 显示加载等待窗口
+  - `callbacks.hideWaitWindow` - 隐藏加载等待窗口
+  - `callbacks.fail` - 加载失败回调
+- `addManualPackage(pkgName)` - 添加手动管理资源的包
+- `setPackageInfo(pkgName, bundleName?, path?)` - 设置包所在的 bundle 和路径
+- `setUIConfig(config)` - 设置 UI 导出数据
+
+**窗口操作**：
+- `showWindow<T>(windowClass, userdata?)` - 异步打开窗口（自动加载资源）
+  - 参数是窗口类（构造函数），非窗口名称
+- `closeWindow<T>(windowClass)` - 关闭窗口（通过窗口类）
+- `closeWindowByName(name)` - 关闭窗口（通过窗口名称）
+- `getWindow<T>(name)` - 获取窗口实例
+- `getTopWindow<T>(isAll?)` - 获取最顶层窗口
+- `hasWindow(name)` - 检查窗口是否存在
+
+**其他方法**：
+- `getGroupNames()` - 获取所有窗口组名称
+- `getWindowGroup(name)` - 获取指定窗口组
+- `closeAllWindow(ignores?)` - 关闭所有窗口
+- `releaseUnusedRes()` - 释放不再使用的 UI 资源
+
+### 窗口类型 (WindowType)
+
+定义窗口显示时对其他窗口的处理方式：
+
+- `Normal` - 不做任何处理
+- `CloseAll` - 关闭所有窗口
+- `CloseOne` - 关闭上一个窗口
+- `HideAll` - 隐藏所有窗口
+- `HideOne` - 隐藏上一个窗口
+
+### 适配类型 (AdapterType)
+
+窗口适配类型：
+
+- `Full` - 全屏适配（默认）
+- `Bang` - 空出刘海区域
+- `Fixed` - 固定尺寸，不适配
+
+### 典型使用流程
+
+1. **FairyGUI 设计** - 使用 FairyGUI 编辑器设计界面
+2. **定义窗口类** - 继承 Window 并使用 @uiclass 装饰器注册
+3. **配置属性和事件** - 使用 @uiprop 和 @uiclick 标记
+4. **配置加载回调** - 调用 `WindowManager.setPackageCallbacks()`（可选）
+5. **打开窗口** - 调用 `WindowManager.showWindow(MyWindow, userdata)`
+6. **管理生命周期** - 实现窗口生命周期方法
+
+详细 API 请查看 `bit-ui.d.ts` 类型定义文件和 FairyGUI 官方文档。
+
+## 依赖
+
+- [FairyGUI](https://www.fairygui.com/) - UI 编辑器和运行时库
+
+## 许可证
+
+MIT License
+
+## 作者
+
+**bit老宫** (gongxh)  
+**邮箱**: gong.xinhai@163.com
+
+## 源码仓库
+
+- [GitHub](https://github.com/Gongxh0901/bit-framework)
+- [npm](https://www.npmjs.com/package/@gongxh/bit-ui)