@chiyou/minigame-framework 1.2.69 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chiyou/minigame-framework",
-  "version": "1.2.69",
+  "version": "1.3.0",
   "description": "基于 Cocos Creator 3.x 的小游戏开发框架，支持多平台发布",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/Framework/Definition/EventDefinition.ts

@@ -0,0 +1,7 @@
+/**
+ * 事件监听者信息（调试用）
+ */
+export interface EventListenerInfo {
+    callback: Function;
+    target: any;
+}

package/src/Framework/Definition/TimerDefinition.ts

@@ -0,0 +1,9 @@
+/**
+ * 定时器重复次数枚举
+ */
+export enum TimerRepeat {
+    /** 只执行一次 */
+    Once = 1,
+    /** 无限循环 */
+    Infinite = -1,
+}

package/src/Framework/Manager/EventMgr.ts

@@ -1,4 +1,5 @@
 import { LogUtils } from '../Utils/LogUtils';
+import { EventListenerInfo } from '../Definition/EventDefinition';
 import { BaseMgr } from './BaseMgr';
 
 /** 事件项 */
@@ -73,6 +74,20 @@ export class EventMgr extends BaseMgr {
         this.eventList.set(eventName, array);
     }
 
+    /**
+     * 监听事件（只触发一次，触发后自动移除）
+     * @param eventName 事件名称
+     * @param callback 回调函数
+     * @param target 回调目标对象
+     */
+    public once(eventName: string, callback: Function, target: any): void {
+        const wrappedCallback = (...data: any[]) => {
+            this.off(eventName, wrappedCallback, target);
+            callback.apply(target, data);
+        };
+        this.on(eventName, wrappedCallback, target);
+    }
+
     /**
      * 取消监听事件
      * @param eventName 事件名称
@@ -128,6 +143,22 @@ export class EventMgr extends BaseMgr {
         }
     }
 
+    /**
+     * 获取指定事件的所有监听者（调试用）
+     * @param eventName 事件名称
+     * @return 监听者信息数组
+     */
+    public getListeners(eventName: string): EventListenerInfo[] {
+        const array = this.eventList.get(eventName);
+        if (!array || array.length === 0) {
+            return [];
+        }
+        return array.map(item => ({
+            callback: item.callback,
+            target: item.target
+        }));
+    }
+
     /**
      * 触发事件
      * @param eventName 事件名称

package/src/Framework/Manager/NodePoolMgr.ts

@@ -3,7 +3,7 @@ import { BaseMgr } from './BaseMgr';
 import { LogUtils } from '../Utils/LogUtils';
 import { FwkErrorCode } from '../Definition/FwkErrorDefinition';
 import { ServiceLocator } from '../Utils/ServiceLocator';
-import type { UIMgr } from './UIMgr';
+import { UIMgr, UICtrl } from './UIMgr';
 
 /** 节点池配置接口 */
 export interface IPoolConfig {
@@ -334,6 +334,15 @@ export class NodePoolMgr extends BaseMgr {
         let node: Node = poolInfo.pool.get() as Node;
         poolInfo.usingNodeSet.add(node);
 
+        // 重置 Transform（_resetNode 只管 Transform，不管业务组件）
+        this._resetNode(node);
+
+        // 调用业务层钩子 onPoolGet（顺序：_resetNode → onPoolGet → addChild → active）
+        let ctrl: UICtrl = node.getComponent(UICtrl);
+        if (ctrl && typeof ctrl.onPoolGet === 'function' && node.isValid) {
+            ctrl.onPoolGet(node);
+        }
+
         if (parent) {
             parent.addChild(node);
         }
@@ -480,7 +489,10 @@ export class NodePoolMgr extends BaseMgr {
         }
     }
 
-    /** 回收节点（内部方法） */
+    /**
+     * 回收节点（内部方法）
+     * 调用顺序：NodePoolMgr.putNode → UICtrl.onPoolPut → NodePoolMgr._resetNode → node.active = false → 入池
+     */
     private _recycleNode(poolName: string, node: Node, resetNode: boolean = true): void {
         if (!node || !node.isValid) {
             return;
@@ -494,7 +506,12 @@ export class NodePoolMgr extends BaseMgr {
             node.removeFromParent();
         }
 
+        // 调用业务层钩子 onPoolPut（顺序：onPoolPut → _resetNode → active → 入池）
         if (resetNode) {
+            let ctrl: UICtrl = node.getComponent(UICtrl);
+            if (ctrl && typeof ctrl.onPoolPut === 'function' && node.isValid) {
+                ctrl.onPoolPut(node);
+            }
             this._resetNode(node);
         }
 
@@ -513,7 +530,11 @@ export class NodePoolMgr extends BaseMgr {
         }
     }
 
-    /** 重置节点（内部方法） */
+    /**
+     * 重置节点 Transform（内部方法）
+     * 注意：只重置 position/rotation/scale，不管业务组件（如 UIOpacity 等）。
+     * 业务组件的清理由 onPoolPut 钩子兜底。
+     */
     private _resetNode(node: Node): void {
         if (!node || !node.isValid) {
             return;

package/src/Framework/Manager/ResMgr.ts

@@ -575,11 +575,12 @@ export class ResMgr extends BaseMgr {
     }
 
     /**
-     * 获取资源
+     * 获取资源（同步）
+     * @description 必须先通过 preloadResBatch 预加载或 loadRes/loadResAsync 加载目标资源后，才能使用 getAsset 获取。同一帧内不支持同步触发加载。
      * @param bundleName AssetBundle 名称
      * @param url 资源路径
      * @param assetType 资源类型
-     * @return 资源实例
+     * @return 资源实例（未加载时返回 null）
      */
     public getAsset<T extends Asset>(bundleName: string, url: string, assetType?: typeof Asset): T | null {
         if (!bundleName || bundleName.trim() === "") {
@@ -739,6 +740,44 @@ export class ResMgr extends BaseMgr {
         });
     }
 
+    /**
+     * 动态加载资源（Promise 版本）
+     * @param bundleName AssetBundle 名称
+     * @param url 资源路径
+     * @param assetType 资源类型
+     * @return Promise<Asset> 资源实例
+     */
+    public loadResAsync<T extends Asset>(bundleName: string, url: string, assetType: typeof Asset): Promise<T> {
+        return new Promise<T>((resolve, reject) => {
+            this.loadRes(bundleName, url, assetType, (success: boolean) => {
+                if (success) {
+                    let asset = this.getAsset<T>(bundleName, url, assetType);
+                    if (asset) {
+                        resolve(asset);
+                    } else {
+                        LogUtils.Instance.error(ResMgr.TAG, FwkErrorCode.Res.NotFound, {
+                            operation: "loadResAsync",
+                            reason: "loadRes 成功但 getAsset 返回 null（可能原因：图集子资源 URL 不正确，或资源类型不匹配）",
+                            bundleName: bundleName,
+                            url: url,
+                            assetType: assetType?.name || "未指定"
+                        });
+                        reject(new Error(`loadResAsync: getAsset returned null, bundle=${bundleName}, url=${url}`));
+                    }
+                } else {
+                    LogUtils.Instance.error(ResMgr.TAG, FwkErrorCode.Res.LoadAssetFailed, {
+                        operation: "loadResAsync",
+                        reason: "loadRes 加载失败",
+                        bundleName: bundleName,
+                        url: url,
+                        assetType: assetType?.name || "未指定"
+                    });
+                    reject(new Error(`loadResAsync failed: bundle=${bundleName}, url=${url}`));
+                }
+            });
+        });
+    }
+
     /**
      * 加载远程图片
      * @param imageUrl 图片 URL

package/src/Framework/Manager/TimerMgr.ts

@@ -1,4 +1,5 @@
 import { FwkErrorCode } from "../Definition/FwkErrorDefinition";
+import { TimerRepeat } from "../Definition/TimerDefinition";
 import { LogUtils } from "../Utils/LogUtils";
 import { ServiceLocator } from "../Utils/ServiceLocator";
 import { BaseMgr } from "./BaseMgr";
@@ -45,15 +46,15 @@ export class TimerMgr extends BaseMgr {
      * 添加定时器
      * @param delay 延迟时间（秒）
      * @param interval 间隔时间（秒）
-     * @param repeat 重复次数，0表示拒绝，负数表示无限
+     * @param repeat 重复次数：TimerRepeat.Once（1）= 执行一次后移除，TimerRepeat.Infinite（-1）= 无限循环，0 = 不执行（立即跳过），>0 = 执行指定次数
      * @param func 回调函数
      * @param target 回调目标对象
      */
-    public addTimer(delay: number, interval: number, repeat: number, func: Function, target: Object) {
+    public addTimer(delay: number, interval: number, repeat: TimerRepeat | number, func: Function, target: Object) {
         if (repeat === 0) {
             LogUtils.Instance.error(TimerMgr.TAG, FwkErrorCode.Timer.InvalidState, {
                 operation: "addTimer",
-                reason: "重复次数为0",
+                reason: "repeat=0 拒绝添加（不支持），应使用 TimerRepeat.Once",
                 delay: delay,
                 interval: interval,
                 repeat: repeat

package/src/Framework/Manager/UIMgr.ts

@@ -16,6 +16,20 @@ export class UICtrl extends Component {
         this.load_all_object(this.node, "");
     }
 
+    /**
+     * 节点从池中取出时调用（UICtrl 子类可 override）
+     * 调用顺序：NodePoolMgr.getNode → NodePoolMgr._resetNode → UICtrl.onPoolGet → parent.addChild → node.active = true
+     * @param node 从池中取出的节点
+     */
+    public onPoolGet?(node: Node): void;
+
+    /**
+     * 节点归还到池中时调用（UICtrl 子类可 override）
+     * 调用顺序：NodePoolMgr.putNode → UICtrl.onPoolPut → NodePoolMgr._resetNode → node.active = false → 入池
+     * @param node 归还到池中的节点
+     */
+    public onPoolPut?(node: Node): void;
+
     /** 加载所有子节点到视图映射 */
     private load_all_object(root: Node, path: string): void {
         for (let i = 0; i < root.children.length; i++) {

package/src/index.ts

@@ -52,4 +52,6 @@ export * from './Framework/Definition/PrivacyDefinition';
 export * from './Framework/Definition/SocialDefinition';
 export * from './Framework/Definition/FwkErrorDefinition';
 export * from './Framework/Definition/UIDefinition';
+export * from './Framework/Definition/EventDefinition';
+export * from './Framework/Definition/TimerDefinition';
 export * from './Framework/Definition/FrameworkBase';