@chiyou/minigame-framework 1.2.69 → 1.3.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/InputMgr.ts

@@ -625,6 +625,36 @@ export class InputMgr extends BaseMgr {
         }
     }
 
+    /**
+     * 监听键盘按下（一次性）
+     * 触发一次后自动移除监听
+     * @param keyCode 按键码（KeyCode），KeyCode.NONE 表示监听所有按键
+     * @param callback 回调函数
+     * @param target 回调目标
+     */
+    public onceKeyDown(keyCode: KeyCode, callback: (event: EventKeyboard) => void, target: any): void {
+        let onceCallback = (event: EventKeyboard) => {
+            this.offKeyDown(keyCode, onceCallback, target);
+            callback.apply(target, [event]);
+        };
+        this.onKeyDown(keyCode, onceCallback, target);
+    }
+
+    /**
+     * 监听键盘抬起（一次性）
+     * 触发一次后自动移除监听
+     * @param keyCode 按键码（KeyCode），KeyCode.NONE 表示监听所有按键
+     * @param callback 回调函数
+     * @param target 回调目标
+     */
+    public onceKeyUp(keyCode: KeyCode, callback: (event: EventKeyboard) => void, target: any): void {
+        let onceCallback = (event: EventKeyboard) => {
+            this.offKeyUp(keyCode, onceCallback, target);
+            callback.apply(target, [event]);
+        };
+        this.onKeyUp(keyCode, onceCallback, target);
+    }
+
     /**
      * 判断按键是否处于按下状态
      * @param keyCode 按键码（KeyCode）
@@ -891,6 +921,22 @@ export class InputMgr extends BaseMgr {
         }
     }
 
+    /**
+     * 监听按钮点击（一次性）
+     * 触发一次后自动移除监听
+     * @param button 按钮节点
+     * @param callback 回调函数
+     * @param target 回调目标
+     * @param preventAccidental 是否防误触（连续点击），默认 true
+     */
+    public onceButtonClick(button: Node, callback: () => void, target: any, preventAccidental: boolean = true): void {
+        let onceCallback = () => {
+            this.offButtonClick(button, onceCallback, target);
+            callback.apply(target);
+        };
+        this.onButtonClick(button, onceCallback, target, preventAccidental);
+    }
+
     // ==================== 节点触摸事件（对外） ====================
 
     /**
@@ -1019,6 +1065,21 @@ export class InputMgr extends BaseMgr {
         }
     }
 
+    /**
+     * 监听节点触摸结束（一次性）
+     * 触发一次后自动移除监听
+     * @param node 节点
+     * @param callback 回调函数
+     * @param target 回调目标
+     */
+    public onceNodeTouchEnd(node: Node, callback: (touch: Touch) => void, target: any): void {
+        let onceCallback = (touch: Touch) => {
+            this.offNodeTouchEnd(node, onceCallback, target);
+            callback.apply(target, [touch]);
+        };
+        this.onNodeTouchEnd(node, onceCallback, target);
+    }
+
     /**
      * 移除节点触摸事件
      */

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 {
@@ -25,6 +25,8 @@ export interface IPoolStatistics {
     nowActiveCount: number;
     /** 历史最大活跃节点数 */
     maxActiveCount: number;
+    /** 当前可用节点数 */
+    availableCount: number;
     /** 最后访问时间 */
     lastAccessTime: number;
 }
@@ -49,6 +51,7 @@ export class PoolInfo {
             reusedCount: 0,
             nowActiveCount: 0,
             maxActiveCount: 0,
+            availableCount: 0,
             lastAccessTime: Date.now(),
         };
     }
@@ -229,8 +232,9 @@ export class NodePoolMgr extends BaseMgr {
                     reusedCount: 0,
                     nowActiveCount: 0,
                     maxActiveCount: 0,
+                    availableCount: 0,
                     lastAccessTime: Date.now(),
-                }
+                };
             }
         }
 
@@ -334,6 +338,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);
         }
@@ -466,6 +479,13 @@ export class NodePoolMgr extends BaseMgr {
         }
 
         let poolInfo: PoolInfo = this._poolInfoMap.get(poolName);
+        if (!poolInfo) {
+            LogUtils.Instance.error(NodePoolMgr.TAG, FwkErrorCode.NodePool.NotFound, {
+                operation: "_destoryNode",
+                poolName: poolName,
+                reason: "节点池信息获取失败"
+            });
+        }
 
         if (this.uiMgr === null) {
             this.uiMgr = ServiceLocator.Instance.get<UIMgr>("UIMgr");
@@ -480,7 +500,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 +517,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 +541,11 @@ export class NodePoolMgr extends BaseMgr {
         }
     }
 
-    /** 重置节点（内部方法） */
+    /**
+     * 重置节点 Transform（内部方法）
+     * 注意：只重置 position/rotation/scale，不管业务组件（如 UIOpacity 等）。
+     * 业务组件的清理由 onPoolPut 钩子兜底。
+     */
     private _resetNode(node: Node): void {
         if (!node || !node.isValid) {
             return;
@@ -524,6 +556,52 @@ export class NodePoolMgr extends BaseMgr {
         node.scale = Vec3.ONE;
     }
 
+    /**
+     * 检查节点池是否存在
+     * @param poolName 节点池名称
+     */
+    public hasPool(poolName: string): boolean {
+        return this._poolInfoMap.has(poolName);
+    }
+
+    /**
+     * 获取指定节点池的统计信息
+     * @param poolName 节点池名称
+     */
+    public getPoolStats(poolName: string): IPoolStatistics | null {
+        let poolInfo: PoolInfo = this._poolInfoMap.get(poolName);
+        if (!poolInfo) {
+            return null;
+        }
+
+        return {
+            createdCount: poolInfo.statistics.createdCount,
+            reusedCount: poolInfo.statistics.reusedCount,
+            nowActiveCount: poolInfo.statistics.nowActiveCount,
+            maxActiveCount: poolInfo.statistics.maxActiveCount,
+            availableCount: poolInfo.pool.size(),
+            lastAccessTime: poolInfo.statistics.lastAccessTime,
+        };
+    }
+
+    /**
+     * 获取所有节点池的统计信息
+     */
+    public getAllPoolStats(): Map<string, IPoolStatistics> {
+        let result: Map<string, IPoolStatistics> = new Map<string, IPoolStatistics>();
+        this._poolInfoMap.forEach((poolInfo: PoolInfo, poolName: string) => {
+            result.set(poolName, {
+                createdCount: poolInfo.statistics.createdCount,
+                reusedCount: poolInfo.statistics.reusedCount,
+                nowActiveCount: poolInfo.statistics.nowActiveCount,
+                maxActiveCount: poolInfo.statistics.maxActiveCount,
+                availableCount: poolInfo.pool.size(),
+                lastAccessTime: poolInfo.statistics.lastAccessTime,
+            });
+        });
+        return result;
+    }
+
     /** 打印节点池状态（调试用） */
     private _printPoolState(poolName: string): void {
         let poolInfo: PoolInfo = this._poolInfoMap.get(poolName);
@@ -552,6 +630,7 @@ export class NodePoolMgr extends BaseMgr {
             reusedCount: poolInfo.statistics.reusedCount,
             nowActiveCount: poolInfo.statistics.nowActiveCount,
             maxActiveCount: poolInfo.statistics.maxActiveCount,
+            availableCount: poolInfo.pool.size(),
             lastAccessTime: poolInfo.statistics.lastAccessTime
         });
     }

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,7 +1,10 @@
 import { FwkErrorCode } from "../Definition/FwkErrorDefinition";
+import { FrameworkBase } from "../Definition/FrameworkBase";
+import { TimerRepeat } from "../Definition/TimerDefinition";
 import { LogUtils } from "../Utils/LogUtils";
 import { ServiceLocator } from "../Utils/ServiceLocator";
 import { BaseMgr } from "./BaseMgr";
+import { EventMgr } from "./EventMgr";
 
 interface ITimer {
     tick: number;
@@ -18,6 +21,7 @@ export class TimerMgr extends BaseMgr {
     static TAG: string = "TimerMgr";
 
     private timers: ITimer[] = [];
+    private _paused: boolean = false;
 
     onLoad(): void {
         super.onLoad();
@@ -30,6 +34,10 @@ export class TimerMgr extends BaseMgr {
         }
 
         ServiceLocator.Instance.register("TimerMgr", this);
+
+        // 监听生命周期事件，切后台暂停定时器
+        EventMgr.Instance.on(FrameworkBase.Message.LifeCycle_onGameHide, this._onGameHide, this);
+        EventMgr.Instance.on(FrameworkBase.Message.LifeCycle_onGameShow, this._onGameShow, this);
     }
 
     /**
@@ -37,23 +45,63 @@ export class TimerMgr extends BaseMgr {
      */
     public init(): void {
         this.timers = [];
+        this._paused = false;
 
         LogUtils.Instance.info(TimerMgr.TAG, "初始化完成");
     }
 
+    /**
+     * 暂停所有定时器
+     */
+    public pauseAll(): void {
+        if (this._paused) return;
+        this._paused = true;
+        LogUtils.Instance.info(TimerMgr.TAG, "定时器已暂停");
+    }
+
+    /**
+     * 恢复所有定时器
+     */
+    public resumeAll(): void {
+        if (!this._paused) return;
+        this._paused = false;
+        LogUtils.Instance.info(TimerMgr.TAG, "定时器已恢复");
+    }
+
+    /**
+     * 定时器是否暂停中
+     */
+    public isPaused(): boolean {
+        return this._paused;
+    }
+
+    private _onGameHide(): void {
+        this.pauseAll();
+    }
+
+    private _onGameShow(): void {
+        this.resumeAll();
+    }
+
+    onDestroy(): void {
+        EventMgr.Instance.off(FrameworkBase.Message.LifeCycle_onGameHide, this._onGameHide, this);
+        EventMgr.Instance.off(FrameworkBase.Message.LifeCycle_onGameShow, this._onGameShow, this);
+        super.onDestroy();
+    }
+
     /**
      * 添加定时器
      * @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
@@ -117,6 +165,8 @@ export class TimerMgr extends BaseMgr {
     }
 
     protected update(dt: number): void {
+        if (this._paused) return;
+
         for (let index = 0; index < this.timers.length; index++) {
             const item = this.timers[index];
             item.tick += dt;

package/src/Framework/Manager/UIMgr.ts

@@ -1,10 +1,12 @@
-import { Component, Node, Button, Prefab, instantiate, screen, UITransform, v3, view, ResolutionPolicy, math, Tween, tween, Label, Color, Sprite, SpriteFrame, BlockInputEvents, Texture2D } from 'cc';
+import { Component, Node, Button, Prefab, instantiate, screen, UITransform, v3, view, ResolutionPolicy, math, Tween, tween, Label, Color, Sprite, SpriteFrame, BlockInputEvents, Texture2D, Vec3 } from 'cc';
 import { FwkErrorCode } from '../Definition/FwkErrorDefinition';
 import { LogUtils } from '../Utils/LogUtils';
-import { ToastDuration } from '../Definition/UIDefinition';
+import { ToastDuration, ToastPosition } from '../Definition/UIDefinition';
 import { BaseMgr } from './BaseMgr';
 import { ServiceLocator } from '../Utils/ServiceLocator';
 import type { ResMgr } from './ResMgr';
+import type { SystemMgr } from './SystemMgr';
+import type { InputMgr } from './InputMgr';
 
 /** UI 控制器基类 */
 export class UICtrl extends Component {
@@ -16,6 +18,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++) {
@@ -111,6 +127,8 @@ export class UIMgr extends BaseMgr {
     private toastHistoryMaxCount: number = 10;
 
     private resMgr: ResMgr = null;
+    private inputMgr: InputMgr = null;
+    private systemMgr: SystemMgr = null;
 
     /** 打印 UI 映射（调试用） */
     public print(): void {
@@ -269,6 +287,10 @@ export class UIMgr extends BaseMgr {
             this.resMgr = ServiceLocator.Instance.get<ResMgr>("ResMgr");
         }
 
+        if (this.inputMgr === null) {
+            this.inputMgr = ServiceLocator.Instance.get<InputMgr>("InputMgr");
+        }
+
         if (!this.resMgr) {
             return null;
         }
@@ -420,12 +442,18 @@ export class UIMgr extends BaseMgr {
      * 显示 Toast
      * @param content 显示内容
      * @param toastDuration 显示时长
+     * @param position 显示位置（ToastPosition 枚举或世界坐标 Vec3），默认居中
      */
-    public showToast(content: string, toastDuration: ToastDuration = ToastDuration.Duration_Short): void {
+    public showToast(content: string, toastDuration: ToastDuration = ToastDuration.Duration_Short, position?: ToastPosition | Vec3): void {
         if (this.node_toastRoot === null) {
             return;
         }
 
+        // 延迟加载 SystemMgr（避免循环依赖）
+        if (this.systemMgr === null) {
+            this.systemMgr = ServiceLocator.Instance.get<SystemMgr>("SystemMgr");
+        }
+
         // 记录 Toast 历史
         this.toastHistory.push(content);
         if (this.toastHistory.length > this.toastHistoryMaxCount) {
@@ -449,6 +477,33 @@ export class UIMgr extends BaseMgr {
 
         this.node_toastRoot.active = true;
         this.node_toastRoot.getComponent(UITransform).width = textWidth + 80;
+
+        // 设置 Toast 位置
+        if (position !== undefined) {
+            if (position instanceof Vec3) {
+                // Vec3 世界坐标，转换为节点坐标
+                let localPos: Vec3 = this.node_toastRoot.getComponent(UITransform).convertToNodeSpaceAR(position);
+                this.node_toastRoot.setPosition(localPos.x, localPos.y);
+            } else {
+                // ToastPosition 枚举
+                let x: number = 0;
+                let y: number = 0;
+                if (this.systemMgr) {
+                    let screenInfo = this.systemMgr.getScreenInfo();
+                    let screenH: number = screenInfo.windowHeight;
+                    let edgeOffset: number = 150; // 距屏幕边缘的距离
+                    if (position === ToastPosition.Top) {
+                        y = screenH / 2 - edgeOffset;
+                    } else if (position === ToastPosition.Bottom) {
+                        y = -screenH / 2 + edgeOffset;
+                    }
+                    // Center: x=0, y=0
+                }
+                // systemMgr 为空时默认居中（x=0, y=0）
+                this.node_toastRoot.setPosition(x, y);
+            }
+        }
+
         this.tween_toast = tween(this.node_toastRoot)
             .delay(showTime)
             .call(() => {
@@ -469,13 +524,10 @@ export class UIMgr extends BaseMgr {
     /**
      * 打开 Dialog
      * @param ui_name UI 名称
-     * @param maskColor 遮罩颜色
-     * @return Dialog 节点
+     * @param maskColor 遮罩颜色（默认半透明黑）
+     * @param closeOnMaskClick 点击遮罩是否关闭 Dialog（默认 false）
      */
-    public openDialog(ui_name: string, maskColor?: Color): Node {
-        if (!maskColor) {
-            maskColor = new Color(51, 51, 51, 230);
-        }
+    public openDialog(ui_name: string, maskColor: Color = new Color(51, 51, 51, 230), closeOnMaskClick: boolean = false): Node {
 
         const whitePixelData = new Uint8Array([maskColor.r, maskColor.g, maskColor.b, maskColor.a]);
         const texture = new Texture2D();
@@ -505,6 +557,18 @@ export class UIMgr extends BaseMgr {
         if (node_dialog) {
             this.node_dialogRoot.addChild(node_agent);
             this.node_dialogRoot.active = true;
+
+            // 点击遮罩关闭 Dialog
+            if (closeOnMaskClick) {
+                let maskTouchCallback = () => {
+                    this.closeDialog(ui_name, node_dialog);
+                };
+                // 将回调存到 node_mask 上，方便 closeDialog 时清理
+                (node_mask as any)._maskTouchCallback = maskTouchCallback;
+                if (this.inputMgr) {
+                    this.inputMgr.onNodeTouchEnd(node_mask, maskTouchCallback, this);
+                }
+            }
         } else {
             node_agent.destroy();
         }
@@ -532,6 +596,14 @@ export class UIMgr extends BaseMgr {
 
         if (hasNode) {
             let node_agent: Node = node.parent;
+            // 清理点击遮罩关闭的监听器（如果存在）
+            let node_mask: Node = node_agent.getChildByName("Node_Mask");
+            if (node_mask && (node_mask as any)._maskTouchCallback) {
+                if (this.inputMgr) {
+                    this.inputMgr.offNodeTouchEnd(node_mask, (node_mask as any)._maskTouchCallback, this);
+                }
+                (node_mask as any)._maskTouchCallback = null;
+            }
             this.destroy_ui(ui_name, node);
             node_agent.destroy();
         }
@@ -560,6 +632,14 @@ export class UIMgr extends BaseMgr {
                 if (child.name !== "Node_Mask") {
                     let uiName = this._nodeToUIName(child);
                     if (uiName) {
+                        // 清理点击遮罩关闭的监听器（如果存在）
+                        let node_mask: Node = agent.getChildByName("Node_Mask");
+                        if (node_mask && (node_mask as any)._maskTouchCallback) {
+                            if (this.inputMgr) {
+                                this.inputMgr.offNodeTouchEnd(node_mask, (node_mask as any)._maskTouchCallback, this);
+                            }
+                            (node_mask as any)._maskTouchCallback = null;
+                        }
                         this.destroy_ui(uiName, child);
                         closedCount++;
                         break;

package/src/Framework/Utils/LogUtils.ts

@@ -9,6 +9,7 @@ export class LogUtils {
     static TAG: string = "LogUtils";
 
     private isDebug: boolean = false;
+    private _timers: Map<string, number> = new Map();
 
     /**
      * 初始化日志模块
@@ -133,6 +134,32 @@ export class LogUtils {
         return `[${level}][${tag}][${timestamp}]: ${content}`;
     }
 
+    /**
+     * 开始计时
+     * @param label 计时标签
+     */
+    public timeStart(label: string): void {
+        if (!this.isDebug) return;
+        this._timers.set(label, Date.now());
+        console.log(this.formatLog("TIMER", label, "计时开始"));
+    }
+
+    /**
+     * 结束计时并输出耗时
+     * @param label 计时标签（需与 timeStart 匹配）
+     */
+    public timeEnd(label: string): void {
+        if (!this.isDebug) return;
+        const startTime = this._timers.get(label);
+        if (startTime === undefined) {
+            console.warn(this.formatLog("TIMER", label, "未找到计时起点"));
+            return;
+        }
+        const elapsed = Date.now() - startTime;
+        this._timers.delete(label);
+        console.log(this.formatLog("TIMER", label, `耗时 ${elapsed}ms`));
+    }
+
     /**
      * 格式化值
      */