dzkcc-mflow 0.0.37 → 0.0.39

package/dist/core/Api.d.ts

@@ -65,6 +65,10 @@ export interface IView {
     onPause(): void;
     /** 恢复视图（从暂停状态恢复） */
     onResume(): void;
+    /** 进入动画（可选） */
+    onEnterAnimation?(): Promise<void>;
+    /** 退出动画（可选） */
+    onExitAnimation?(): Promise<void>;
 }
 /**
  * UI 管理器接口 - 管理视图的打开、关闭和栈操作
@@ -75,15 +79,17 @@ export interface IUIManager {
     /** 打开视图 */
     open<T extends keyof UIRegistry>(viewClass: T, args?: any): Promise<InstanceType<UIRegistry[T]>>;
     /** 关闭视图 */
-    close<T extends keyof UIRegistry>(viewClass: T): void;
+    close<T extends keyof UIRegistry>(viewClass: T): Promise<void>;
     /** 打开视图并入栈 */
     openAndPush<T extends keyof UIRegistry>(viewClass: T, group: string, args?: any): Promise<InstanceType<UIRegistry[T]>>;
     /** 关闭栈顶视图并弹出 */
-    closeAndPop(group: string, destroy?: boolean): void;
+    closeAndPop(group: string, destroy?: boolean): Promise<void>;
     /** 获取栈顶视图 */
     getTopView(): IView | undefined;
     /** 清空视图栈 */
     clearStack(group: string, destroy?: boolean): void;
+    /** 关闭所有视图 */
+    closeAll(destroy?: boolean): void;
 }
 /**
  * 资源管理器接口

package/dist/core/Core.js

@@ -33,7 +33,7 @@ class AbstractCore {
      * ```
      */
     getModel(modelClass) {
-        const className = modelClass.name;
+        const className = modelClass;
         // 如果已存在实例，直接返回
         if (this.container.has(className)) {
             return this.container.get(className);
@@ -55,7 +55,7 @@ class AbstractCore {
      * ```
      */
     getManager(managerClass) {
-        const className = managerClass.name;
+        const className = managerClass;
         // 如果已存在实例，直接返回
         if (this.container.has(className)) {
             return this.container.get(className);

package/dist/libs/BaseView.d.ts

@@ -36,4 +36,40 @@ export declare abstract class BaseView extends Component implements IView {
      * ```
      */
     protected getManager<T extends keyof ManagerRegistry>(managerClass: T): InstanceType<ManagerRegistry[T]>;
+    /**
+     * 进入动画（可被子类覆盖以实现自定义动画）
+     * 默认实现：缩放+淡入效果
+     * @returns 返回 Promise 以支持异步动画
+     * @example
+     * ```typescript
+     * async onEnterAnimation(): Promise<void> {
+     *     // 自定义动画实现
+     *     return new Promise<void>((resolve) => {
+     *         tween(this.node)
+     *             .to(0.5, { scale: new Vec3(1, 1, 1) })
+     *             .call(() => resolve())
+     *             .start();
+     *     });
+     * }
+     * ```
+     */
+    onEnterAnimation(): Promise<void>;
+    /**
+     * 退出动画（可被子类覆盖以实现自定义动画）
+     * 默认实现：缩放+淡出效果
+     * @returns 返回 Promise 以支持异步动画
+     * @example
+     * ```typescript
+     * async onExitAnimation(): Promise<void> {
+     *     // 自定义动画实现
+     *     return new Promise<void>((resolve) => {
+     *         tween(this.node)
+     *             .to(0.3, { scale: new Vec3(0, 0, 1) })
+     *             .call(() => resolve())
+     *             .start();
+     *     });
+     * }
+     * ```
+     */
+    onExitAnimation(): Promise<void>;
 }

package/dist/libs/BaseView.js

@@ -1,4 +1,5 @@
-import { _decorator, Component } from 'cc';
+import { __awaiter } from '../_virtual/_tslib.js';
+import { _decorator, Component, UIOpacity, tween, Vec3 } from 'cc';
 
 const { ccclass, property } = _decorator;
 class BaseView extends Component {
@@ -93,6 +94,78 @@ class BaseView extends Component {
     getManager(managerClass) {
         return mf.core.getManager(managerClass);
     }
+    /**
+     * 进入动画（可被子类覆盖以实现自定义动画）
+     * 默认实现：缩放+淡入效果
+     * @returns 返回 Promise 以支持异步动画
+     * @example
+     * ```typescript
+     * async onEnterAnimation(): Promise<void> {
+     *     // 自定义动画实现
+     *     return new Promise<void>((resolve) => {
+     *         tween(this.node)
+     *             .to(0.5, { scale: new Vec3(1, 1, 1) })
+     *             .call(() => resolve())
+     *             .start();
+     *     });
+     * }
+     * ```
+     */
+    onEnterAnimation() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const node = this.node;
+            node.setScale(0.8, 0.8, 1);
+            let uiOpacity = node.getComponent(UIOpacity);
+            if (uiOpacity) {
+                uiOpacity.opacity = 0;
+            }
+            return new Promise((resolve) => {
+                const tweenNode = tween(node).to(0.3, { scale: new Vec3(1, 1, 1) }, { easing: 'backOut' });
+                if (uiOpacity) {
+                    tween(uiOpacity)
+                        .to(0.3, { opacity: 255 })
+                        .start();
+                }
+                tweenNode
+                    .call(() => resolve())
+                    .start();
+            });
+        });
+    }
+    /**
+     * 退出动画（可被子类覆盖以实现自定义动画）
+     * 默认实现：缩放+淡出效果
+     * @returns 返回 Promise 以支持异步动画
+     * @example
+     * ```typescript
+     * async onExitAnimation(): Promise<void> {
+     *     // 自定义动画实现
+     *     return new Promise<void>((resolve) => {
+     *         tween(this.node)
+     *             .to(0.3, { scale: new Vec3(0, 0, 1) })
+     *             .call(() => resolve())
+     *             .start();
+     *     });
+     * }
+     * ```
+     */
+    onExitAnimation() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const node = this.node;
+            const uiOpacity = node.getComponent(UIOpacity);
+            return new Promise((resolve) => {
+                const tweenNode = tween(node).to(0.2, { scale: new Vec3(0.8, 0.8, 1) }, { easing: 'backIn' });
+                if (uiOpacity) {
+                    tween(uiOpacity)
+                        .to(0.2, { opacity: 0 })
+                        .start();
+                }
+                tweenNode
+                    .call(() => resolve())
+                    .start();
+            });
+        });
+    }
 }
 
 export { BaseView };

package/dist/libs/ResLoader.d.ts

@@ -1,10 +1,24 @@
 import { Asset, Prefab, SpriteFrame, Sprite, sp } from "cc";
 import { ICocosResManager, AssetType } from "../core";
 export declare class ResLoader implements ICocosResManager {
+    /**
+     *
+     * @param nameOrUrl 资源包名称或路径
+     * @returns Promise<AssetManager.Bundle>
+     */
+    private _loadBundle;
+    /**
+     *
+     * @param path
+     * @param type
+     * @param nameOrUrl
+     * @returns
+     */
     loadAsset<T extends Asset>(path: string, type: AssetType<T>, nameOrUrl?: string): Promise<T>;
     loadPrefab(path: string, nameOrUrl?: string): Promise<Prefab>;
     loadSpriteFrame(ref: Sprite, path: string, nameOrUrl?: string): Promise<SpriteFrame>;
     loadSpine(ref: sp.Skeleton, path: string, nameOrUrl?: string): Promise<sp.SkeletonData>;
+    preloadAsset(paths: string | string[], type: AssetType<Asset>, nameOrUrl?: string): Promise<void>;
     release(asset: Asset, force?: boolean): void;
     release(path: string, type?: AssetType<Asset>, nameOrUrl?: string, force?: boolean): void;
 }

package/dist/libs/ResLoader.js

@@ -1,13 +1,18 @@
 import { __awaiter } from '../_virtual/_tslib.js';
-import { assetManager, Prefab, Asset, SpriteFrame, sp } from 'cc';
+import { path, assetManager, Prefab, SpriteFrame, sp, Asset } from 'cc';
 
 const DefaultBundle = "resources";
 class ResLoader {
-    loadAsset(path, type, nameOrUrl = DefaultBundle) {
-        if (assetManager.assets.has(path)) {
-            const asset = assetManager.assets.get(path);
-            asset.addRef();
-            return Promise.resolve(asset);
+    /**
+     *
+     * @param nameOrUrl 资源包名称或路径
+     * @returns Promise<AssetManager.Bundle>
+     */
+    _loadBundle(nameOrUrl = DefaultBundle) {
+        const bundleName = path.basename(nameOrUrl);
+        const bundle = assetManager.getBundle(bundleName);
+        if (bundle) {
+            return Promise.resolve(bundle);
         }
         return new Promise((resolve, reject) => {
             assetManager.loadBundle(nameOrUrl, (err, bundle) => {
@@ -15,22 +20,52 @@ class ResLoader {
                     reject(err);
                 }
                 else {
-                    bundle.load(path, type, (err, data) => {
-                        if (err) {
-                            reject(err);
-                        }
-                        else {
-                            data.addRef();
-                            resolve(data);
-                        }
-                    });
+                    resolve(bundle);
                 }
             });
         });
     }
+    /**
+     *
+     * @param path
+     * @param type
+     * @param nameOrUrl
+     * @returns
+     */
+    loadAsset(path, type, nameOrUrl = DefaultBundle) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 如果是在resources路径下，则截取resources之后的路径，否则直接使用路径
+            const _path = (nameOrUrl == DefaultBundle && path.includes('resources')) ? path.split('resources/')[1] : path;
+            // 加载资源的通用逻辑
+            const loadFromBundle = (bundle) => {
+                const cachedAsset = bundle.get(_path, type);
+                if (cachedAsset) {
+                    cachedAsset.addRef();
+                    return Promise.resolve(cachedAsset);
+                }
+                else {
+                    return new Promise((resolve, reject) => {
+                        bundle.load(_path, type, (err, data) => {
+                            if (err) {
+                                reject(err);
+                            }
+                            else {
+                                data.addRef();
+                                resolve(data);
+                            }
+                        });
+                    });
+                }
+            };
+            const bundle = yield this._loadBundle(nameOrUrl);
+            return loadFromBundle(bundle);
+        });
+    }
     loadPrefab(path, nameOrUrl = DefaultBundle) {
-        //refCount 记录的是持有者数量，不是资源份数，所以prefab也需要addRef
-        return this.loadAsset(path, Prefab, nameOrUrl);
+        return __awaiter(this, void 0, void 0, function* () {
+            //refCount 记录的是持有者数量，不是资源份数，所以prefab也需要addRef
+            return yield this.loadAsset(path, Prefab, nameOrUrl);
+        });
     }
     loadSpriteFrame(ref, path, nameOrUrl = DefaultBundle) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -60,6 +95,21 @@ class ResLoader {
             }
         });
     }
+    preloadAsset(paths, type, nameOrUrl = DefaultBundle) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const bundle = yield this._loadBundle(nameOrUrl);
+            new Promise((resolve, reject) => {
+                bundle.preload(paths, type, (err, data) => {
+                    if (err) {
+                        reject(err);
+                    }
+                    else {
+                        resolve(data);
+                    }
+                });
+            });
+        });
+    }
     release(pathOrAsset, typeOrForce, nameOrUrl = DefaultBundle, forceParam = false) {
         var _a;
         let asset;

package/dist/libs/UIManager.d.ts

@@ -1,34 +1,179 @@
-import { Component } from "cc";
+import { Component, Node, Color } from "cc";
 import { IUIManager, IView } from "../core";
+/**
+ * UI遮罩配置选项
+ */
+export interface UIMaskOptions {
+    /** 遮罩颜色 */
+    color?: Color;
+    /** 是否可点击关闭顶层UI */
+    clickToClose?: boolean;
+}
+/**
+ * UI打开选项
+ */
+export interface UIOpenOptions {
+    /** 是否显示等待视图 */
+    showLoading?: boolean;
+    /** 是否可点击遮罩关闭 */
+    clickToClose?: boolean;
+    /** 自定义参数 */
+    args?: any;
+}
+/**
+ * 等待视图配置
+ */
+export interface UILoadingConfig {
+    /** 是否全局启用等待视图 */
+    enabled?: boolean;
+    /** 等待视图预制体路径 */
+    prefabPath?: string;
+    /** 等待视图显示延迟（毫秒） */
+    delay?: number;
+    /** 最小显示时间（毫秒） */
+    minShowTime?: number;
+    /** 自定义创建函数（高级用法） */
+    createCustomLoading?: () => Node | Promise<Node>;
+}
+/**
+ * LRU缓存配置
+ */
+export interface UICacheConfig {
+    /** 最大缓存数量 */
+    maxSize?: number;
+    /** 是否启用LRU策略 */
+    enableLRU?: boolean;
+}
+/**
+ * 预加载配置
+ */
+export interface UIPreloadConfig {
+    /** 预加载的视图列表 */
+    views?: (keyof UIRegistry)[];
+    /** 预加载延迟（毫秒） */
+    delay?: number;
+}
 type ICocosView = IView & Component;
 declare abstract class CcocosUIManager implements IUIManager {
     getTopView(): IView | undefined;
-    open<T extends keyof UIRegistry>(viewClass: T, args?: any): Promise<InstanceType<UIRegistry[T]>>;
-    close<T extends keyof UIRegistry>(viewClass: T): void;
-    openAndPush<T extends keyof UIRegistry>(viewClass: T, group: string, args?: any): Promise<InstanceType<UIRegistry[T]>>;
-    closeAndPop(group: string, destroy?: boolean): void;
+    open<T extends keyof UIRegistry>(viewClass: T, args?: UIOpenOptions): Promise<InstanceType<UIRegistry[T]>>;
+    close<T extends keyof UIRegistry>(viewClass: T): Promise<void>;
+    openAndPush<T extends keyof UIRegistry>(viewClass: T, group: string, args?: UIOpenOptions): Promise<InstanceType<UIRegistry[T]>>;
+    closeAndPop(group: string, destroy?: boolean): Promise<void>;
     clearStack(group: string, destroy?: boolean): void;
-    protected abstract internalOpen(viewKey: string, args?: any): Promise<ICocosView>;
-    protected abstract internalClose(viewKey: string | IView, destory?: boolean): void;
-    protected abstract internalOpenAndPush(viewKey: string, group: string, args?: any): Promise<ICocosView>;
-    protected abstract internalCloseAndPop(group: string, destroy?: boolean): void;
-    protected abstract internalClearStack(group: string, destroy?: boolean): void;
-    protected abstract internalGetTopView(): ICocosView | undefined;
+    closeAll(destroy?: boolean): void;
+    protected abstract _internalOpen(viewKey: string, args?: UIOpenOptions): Promise<ICocosView>;
+    protected abstract _internalClose(viewKey: string | IView, destory?: boolean): Promise<void>;
+    protected abstract _internalOpenAndPush(viewKey: string, group: string, args?: UIOpenOptions): Promise<ICocosView>;
+    protected abstract _internalCloseAndPop(group: string, destroy?: boolean): Promise<void>;
+    protected abstract _internalClearStack(group: string, destroy?: boolean): void;
+    protected abstract _internalGetTopView(): ICocosView | undefined;
+    protected abstract _internalCloseAll(destroy?: boolean): void;
 }
 export declare class UIManager extends CcocosUIManager {
     private _cache;
     private _groupStacks;
+    private _inputBlocker;
+    private _loadingView;
+    private _loadingPromises;
+    private _lruOrder;
+    private _preloadedViews;
+    private _maskOptions;
+    private _loadingConfig;
+    private _cacheConfig;
+    private _preloadConfig;
+    private _openOptions;
     constructor();
+    /**
+     * 设置遮罩配置
+     */
+    setMaskConfig(options: UIMaskOptions): void;
+    /**
+     * 设置等待视图配置
+     */
+    setLoadingConfig(config: UILoadingConfig): void;
+    /**
+     * 设置缓存配置
+     */
+    setCacheConfig(config: UICacheConfig): void;
+    /**
+     * 设置预加载配置
+     */
+    setPreloadConfig(config: UIPreloadConfig): void;
+    /**
+     * 检查指定视图是否已打开
+     */
+    contains<T extends keyof UIRegistry>(viewKey: T): boolean;
+    /**
+     * 检查视图是否正在加载
+    */
+    isLoading<T extends keyof UIRegistry>(viewKey: T): boolean;
+    /**
+     * 预加载视图（支持单个或多个）
+     */
+    preload<T extends keyof UIRegistry>(viewKeyOrKeys: T | T[]): Promise<void>;
     private _getPrefabPath;
+    /**
+     * 获取所有活跃的视图节点（排除遮罩节点）
+     */
+    private _getActiveViews;
+    /**
+     * 通过prefab创建Node对象
+     * @param args
+     * @returns Node对象
+     */
+    private _generateNode;
+    /**
+     * 调整遮罩层级：始终保持在最顶层UI的下一层
+     */
     private _adjustMaskLayer;
+    /**
+     * 更新LRU顺序
+     */
+    private _updateLRUOrder;
+    /**
+     * 阻塞/解除输入事件
+     */
     private _blockInput;
+    /**
+     * 设置遮罩点击处理器
+     */
+    private _setupMaskClickHandler;
+    /**
+    * 显示等待视图
+    */
+    private _showLoading;
+    /**
+     * 隐藏等待视图
+     */
+    private _hideLoading;
+    /**
+     * 预加载视图
+     */
+    private _startPreload;
+    /**
+     * 预加载单个视图
+     */
+    private _preloadView;
+    /**
+     * 获取当前最顶层的视图
+     */
+    protected _internalGetTopView(): ICocosView | undefined;
     private _load;
+    private _loadInternal;
+    protected _internalOpen(viewKey: string, options?: UIOpenOptions): Promise<ICocosView>;
+    protected _internalClose(viewKeyOrInstance: string | IView, destroy?: boolean): Promise<void>;
+    protected _internalOpenAndPush(viewKey: string, group: string, options?: UIOpenOptions): Promise<ICocosView>;
+    protected _internalCloseAndPop(group: string, destroy?: boolean): Promise<void>;
+    /**
+     * 移除视图
+     */
     private _remove;
-    protected internalGetTopView(): ICocosView | undefined;
-    protected internalOpen(viewKey: string, args?: any): Promise<ICocosView>;
-    protected internalClose(viewKey: string | IView, destroy?: boolean): void;
-    protected internalOpenAndPush(viewKey: string, group: string, args?: any): Promise<ICocosView>;
-    protected internalCloseAndPop(group: string, destroy?: boolean): void;
-    protected internalClearStack(group: string, destroy?: boolean): void;
+    private _releasePrefab;
+    protected _internalClearStack(group: string, destroy?: boolean): void;
+    /**
+     * 关闭所有视图，不播放动画
+     */
+    protected _internalCloseAll(destroy?: boolean): void;
 }
 export {};

package/dist/libs/UIManager.js

@@ -1,8 +1,14 @@
 import { __awaiter } from '../_virtual/_tslib.js';
-import { director, Node, Sprite, Widget, Input, input, Prefab, instantiate } from 'cc';
+import { director, Node, Sprite, Widget, input, Input, Prefab, instantiate } from 'cc';
 import { ServiceLocator } from '../core/ServiceLocator.js';
 import { getViewClass } from '../core/Decorators.js';
+import '../utils/ArrayExt.js';
+import { ImageUtil } from '../utils/ImageUtil.js';
+import '../utils/MathUtil.js';
 
+/**
+ * 为节点添加全屏Widget组件
+ */
 function addWidget(node) {
     const widget = node.getComponent(Widget) || node.addComponent(Widget);
     widget.isAlignLeft = widget.isAlignRight = widget.isAlignTop = widget.isAlignBottom = true;
@@ -33,19 +39,21 @@ function addChild(node) {
     setLayer(node);
 }
 let _uiMask;
+/**
+ * UI遮罩节点代理
+ */
 const UIMask = new Proxy({}, {
     get(target, prop) {
         if (!_uiMask) {
             _uiMask = new Node('__UIMask__');
             addChild(_uiMask);
-            addWidget(_uiMask);
             _uiMask.setPosition(0, 0);
-            _uiMask.addComponent(Sprite).color.set(0, 0, 0, 0.5);
+            _uiMask.addComponent(Sprite).spriteFrame = ImageUtil.createSolidColorSpriteFrame();
+            addWidget(_uiMask);
         }
         const value = Reflect.get(_uiMask, prop);
-        // 如果是放的话，可能要绑定原始实例上下文
+        // 绑定方法到原始实例
         return typeof value === 'function' ? value.bind(_uiMask) : value;
-        // return Reflect.get(_uiMask, prop)
     },
     set(target, p, newValue, receiver) {
         if (p === 'active') {
@@ -58,25 +66,25 @@ const UIMask = new Proxy({}, {
 // 接口隔离，实现具体的CcocosUIManager
 class CcocosUIManager {
     getTopView() {
-        return this.internalGetTopView();
+        return this._internalGetTopView();
     }
     open(viewClass, args) {
-        const className = viewClass.name;
-        return this.internalOpen(className, args);
+        return this._internalOpen(viewClass, args);
     }
     close(viewClass) {
-        const className = viewClass.name;
-        this.internalClose(className);
+        return this._internalClose(viewClass);
     }
     openAndPush(viewClass, group, args) {
-        const className = viewClass.name;
-        return this.internalOpenAndPush(className, group, args);
+        return this._internalOpenAndPush(viewClass, group, args);
     }
     closeAndPop(group, destroy) {
-        this.internalCloseAndPop(group, destroy);
+        return this._internalCloseAndPop(group, destroy);
     }
     clearStack(group, destroy) {
-        this.internalClearStack(group, destroy);
+        this._internalClearStack(group, destroy);
+    }
+    closeAll(destroy) {
+        this._internalCloseAll(destroy);
     }
 }
 class UIManager extends CcocosUIManager {
@@ -84,19 +92,80 @@ class UIManager extends CcocosUIManager {
         super();
         this._cache = new Map();
         this._groupStacks = new Map();
-        UIMask.on(Node.EventType.TOUCH_END, (event) => {
-            let view = this.getTopView();
-            if ('__group__' in view) {
-                if (view.__group__ != undefined) {
-                    this.closeAndPop(view.__group__, false);
-                }
-                else {
-                    // 对于直接关闭视图，我们需要通过内部方法处理
-                    this.internalClose(view, false);
-                }
+        this._inputBlocker = null;
+        this._loadingView = null;
+        this._loadingPromises = new Map();
+        this._lruOrder = [];
+        this._preloadedViews = new Set();
+        this._maskOptions = { clickToClose: true };
+        this._loadingConfig = { enabled: true, delay: 200, minShowTime: 500 };
+        this._cacheConfig = { maxSize: 10, enableLRU: true };
+        this._preloadConfig = { views: [], delay: 1000 };
+        this._openOptions = { showLoading: true, clickToClose: true };
+        this._setupMaskClickHandler();
+        this._startPreload();
+    }
+    /**
+     * 设置遮罩配置
+     */
+    setMaskConfig(options) {
+        this._maskOptions = Object.assign(Object.assign({}, this._maskOptions), options);
+        if (options.color && UIMask) {
+            const sprite = UIMask.getComponent(Sprite);
+            if (sprite) {
+                sprite.color = options.color;
+            }
+        }
+    }
+    /**
+     * 设置等待视图配置
+     */
+    setLoadingConfig(config) {
+        this._loadingConfig = Object.assign(Object.assign({}, this._loadingConfig), config);
+    }
+    /**
+     * 设置缓存配置
+     */
+    setCacheConfig(config) {
+        this._cacheConfig = Object.assign(Object.assign({}, this._cacheConfig), config);
+    }
+    /**
+     * 设置预加载配置
+     */
+    setPreloadConfig(config) {
+        this._preloadConfig = Object.assign(Object.assign({}, this._preloadConfig), config);
+        this._startPreload();
+    }
+    /**
+     * 检查指定视图是否已打开
+     */
+    contains(viewKey) {
+        const viewType = getViewClass(viewKey);
+        return this._cache.has(viewType.name) && this._cache.get(viewType.name).parent !== null;
+    }
+    /**
+     * 检查视图是否正在加载
+    */
+    isLoading(viewKey) {
+        return this._loadingPromises.has(viewKey);
+    }
+    /**
+     * 预加载视图（支持单个或多个）
+     */
+    preload(viewKeyOrKeys) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (Array.isArray(viewKeyOrKeys)) {
+                const promises = viewKeyOrKeys.map(key => this._preloadView(key));
+                yield Promise.all(promises);
+            }
+            else {
+                yield this._preloadView(viewKeyOrKeys);
             }
         });
     }
+    //----------------------------------------------------------
+    // ⬇️⬇️⬇️⬇️⬇️ 内部私有方法 ⬇️⬇️⬇️⬇️⬇️
+    //----------------------------------------------------------
     _getPrefabPath(viewType) {
         let prototype = Object.getPrototypeOf(viewType);
         // 沿着原型链向上查找直到找到定义__path__的基类。注意通过类只能找到静态属性。
@@ -108,175 +177,474 @@ class UIManager extends CcocosUIManager {
         }
         throw new Error(`Prefab path not found for ${viewType.name}`);
     }
-    // 调整Mask层级
+    /**
+     * 获取所有活跃的视图节点（排除遮罩节点）
+     */
+    _getActiveViews() {
+        return UIRoot.children.filter(child => child !== _uiMask && child.name !== '__UIMask__');
+    }
+    /**
+     * 通过prefab创建Node对象
+     * @param args
+     * @returns Node对象
+     */
+    _generateNode(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let prefabPath = args.prefabPath;
+            if (!prefabPath) {
+                prefabPath = this._getPrefabPath(getViewClass(args.viewKey));
+            }
+            const ResMgr = ServiceLocator.getService('ResLoader');
+            const prefab = yield ResMgr.loadPrefab(prefabPath);
+            return instantiate(prefab);
+        });
+    }
+    /**
+     * 调整遮罩层级：始终保持在最顶层UI的下一层
+     */
     _adjustMaskLayer() {
-        let children = UIRoot.children;
-        if (children.length == 1) {
+        const activeViews = this._getActiveViews();
+        // 没有活跃视图时隐藏遮罩
+        if (activeViews.length === 0) {
             UIMask.active = false;
             return;
         }
+        // 有视图时显示遮罩并调整到倒数第二层
         UIMask.active = true;
-        UIMask.setSiblingIndex(Math.max(children.length - 2, 0));
+        const targetIndex = Math.max(UIRoot.children.length - 2, 0);
+        UIMask.setSiblingIndex(targetIndex);
     }
-    _blockInput(block) {
-        function blocker(event) {
-            event.propagationImmediateStopped = true;
+    /**
+     * 更新LRU顺序
+     */
+    _updateLRUOrder(viewKey) {
+        if (!this._cacheConfig.enableLRU)
+            return;
+        const index = this._lruOrder.indexOf(viewKey);
+        if (index > -1) {
+            this._lruOrder.splice(index, 1);
+        }
+        this._lruOrder.push(viewKey);
+        // 检查缓存大小限制
+        if (this._lruOrder.length > this._cacheConfig.maxSize) {
+            const oldestKey = this._lruOrder.shift();
+            const oldestNode = this._cache.get(oldestKey);
+            // 只清理未激活的视图（不在场景树中的）
+            if (oldestNode && !oldestNode.parent) {
+                this._cache.delete(oldestKey);
+                // LRU清理不需要走框架的remove机制，因为：
+                // 1. 这些节点已经不在场景树中（已通过_remove移除）
+                // 2. onExit等生命周期已在_remove中调用过
+                // 3. 直接销毁节点释放内存即可
+                oldestNode.destroy();
+                // 尝试释放对应的Prefab资源
+                this._releasePrefab(oldestKey);
+            }
         }
+    }
+    /**
+     * 阻塞/解除输入事件
+     */
+    _blockInput(block) {
         if (block) {
-            for (const eventType in Input.EventType) {
-                input.on(Input.EventType[eventType], blocker);
+            // 创建并保存阻塞器引用
+            if (!this._inputBlocker) {
+                this._inputBlocker = (event) => {
+                    event.propagationImmediateStopped = true;
+                };
             }
+            // 只监听常用的触摸和鼠标事件
+            input.on(Input.EventType.TOUCH_START, this._inputBlocker, this);
+            input.on(Input.EventType.TOUCH_MOVE, this._inputBlocker, this);
+            input.on(Input.EventType.TOUCH_END, this._inputBlocker, this);
+            input.on(Input.EventType.TOUCH_CANCEL, this._inputBlocker, this);
         }
         else {
-            for (const eventType in Input.EventType) {
-                input.off(Input.EventType[eventType], blocker);
+            // 使用保存的引用解除监听
+            if (this._inputBlocker) {
+                input.off(Input.EventType.TOUCH_START, this._inputBlocker, this);
+                input.off(Input.EventType.TOUCH_MOVE, this._inputBlocker, this);
+                input.off(Input.EventType.TOUCH_END, this._inputBlocker, this);
+                input.off(Input.EventType.TOUCH_CANCEL, this._inputBlocker, this);
             }
         }
     }
-    _load(viewKey, args) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const viewType = getViewClass(viewKey);
-            let target;
-            if (this._cache.has(viewType.name)) {
-                target = this._cache.get(viewType.name);
+    /**
+     * 设置遮罩点击处理器
+     */
+    _setupMaskClickHandler() {
+        UIMask.on(Node.EventType.TOUCH_END, (event) => {
+            if (!this._maskOptions.clickToClose) {
+                return;
+            }
+            const view = this.getTopView();
+            if (!view) {
+                return;
+            }
+            // 区分两种情况处理：
+            // 1. 如果视图有 __group__ 属性且不为 undefined，说明是通过 openAndPush 打开的栈式UI
+            // 2. 否则是通过 open 打开的普通 UI
+            if ('__group__' in view && view.__group__ !== undefined) {
+                // 栈式UI：调用 _internalCloseAndPop 来处理返回逻辑
+                this._internalCloseAndPop(view.__group__, false);
             }
             else {
-                let prefabPath = this._getPrefabPath(viewType);
-                const ResMgr = ServiceLocator.getService('ResLoader');
-                const prefab = yield ResMgr.loadPrefab(prefabPath);
-                target = instantiate(prefab);
-                this._cache.set(viewType.name, target);
+                // 普通UI：直接关闭该视图
+                this._internalClose(view, false);
             }
-            target.active = true;
-            return target.getComponent(viewType);
         });
     }
-    _remove(viewKeyOrInstance, destroy) {
-        var _a;
-        // 如果是 string，从缓存中获取视图实例
-        if (typeof viewKeyOrInstance === 'string') {
-            const viewType = getViewClass(viewKeyOrInstance);
-            const cached = this._cache.get(viewType.name);
-            if (!cached) {
-                console.warn(`No cached view found for ${viewType.name}`);
-                return;
+    /**
+    * 显示等待视图
+    */
+    _showLoading() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this._loadingConfig.enabled) {
+                return Promise.resolve();
             }
-            const viewInstance = cached.getComponent(viewType);
-            if (!viewInstance) {
-                console.warn(`No view component found on node ${cached.name}`);
-                return;
+            // 如果已经显示了等待视图，直接返回
+            if (this._loadingView && this._loadingView.activeInHierarchy) {
+                return Promise.resolve();
+            }
+            // 首次加载或创建等待视图
+            if (!this._loadingView) {
+                if (this._loadingConfig.createCustomLoading) {
+                    // 使用自定义创建函数
+                    this._loadingView = yield this._loadingConfig.createCustomLoading();
+                }
+                else if (this._loadingConfig.prefabPath) {
+                    try {
+                        // 从 prefab 创建等待视图
+                        this._loadingView = yield this._generateNode({ prefabPath: this._loadingConfig.prefabPath });
+                    }
+                    catch (error) {
+                        throw error;
+                    }
+                }
+                else {
+                    // 没有配置等待视图
+                    return Promise.resolve();
+                }
+            }
+            // 激活并添加到场景，调整到最顶层
+            this._loadingView.active = true;
+            UIRoot.parent.addChild(this._loadingView);
+        });
+    }
+    /**
+     * 隐藏等待视图
+     */
+    _hideLoading() {
+        if (this._loadingView && this._loadingView.activeInHierarchy) {
+            this._loadingView.active = false;
+            if (this._loadingView.parent) {
+                this._loadingView.removeFromParent();
             }
-            this._remove(viewInstance, destroy);
-            return;
         }
-        // 处理视图实例
-        const viewInstance = viewKeyOrInstance;
-        if ('__group__' in viewInstance) {
-            viewInstance.__group__ = undefined;
+    }
+    /**
+     * 预加载视图
+     */
+    _startPreload() {
+        if (!this._preloadConfig.views || this._preloadConfig.views.length === 0) {
+            return;
         }
-        viewInstance.onExit();
-        viewInstance.node.removeFromParent();
-        viewInstance.node.active = false;
-        if (destroy) {
-            let cacheKey = viewInstance.constructor.name;
-            (_a = this._cache.get(cacheKey)) === null || _a === void 0 ? void 0 : _a.destroy();
-            this._cache.delete(cacheKey);
-            // 销毁被克隆出的UI后Node后，尝试释放 Prefab 资源
-            try {
-                const viewType = viewInstance.constructor;
-                const prefabPath = this._getPrefabPath(viewType);
-                const ResMgr = ServiceLocator.getService('ResLoader');
-                ResMgr.release(prefabPath, Prefab);
+        setTimeout(() => __awaiter(this, void 0, void 0, function* () {
+            for (const viewKey of this._preloadConfig.views) {
+                if (!this._preloadedViews.has(viewKey)) {
+                    try {
+                        yield this._preloadView(viewKey);
+                        this._preloadedViews.add(viewKey);
+                    }
+                    catch (error) {
+                        console.warn(`Failed to preload view ${viewKey}:`, error);
+                    }
+                }
             }
-            catch (error) {
-                console.error(`Failed to release prefab for ${cacheKey}:`, error);
+        }), this._preloadConfig.delay || 1000);
+    }
+    /**
+     * 预加载单个视图
+     */
+    _preloadView(viewKey) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const viewType = getViewClass(viewKey);
+            if (this._cache.has(viewType.name)) {
+                return; // 已经缓存
             }
-        }
+            const target = yield this._generateNode({ viewKey: viewKey });
+            target.active = false; // 预加载的视图保持不激活状态
+            this._cache.set(viewType.name, target);
+            this._updateLRUOrder(viewType.name);
+        });
     }
-    internalGetTopView() {
-        let target = UIRoot.children.reverse()[0];
-        if (!target) {
+    /**
+     * 获取当前最顶层的视图
+     */
+    _internalGetTopView() {
+        const activeViews = this._getActiveViews();
+        if (activeViews.length === 0) {
             return undefined;
         }
+        // 获取最后一个视图节点（最顶层）
+        const target = activeViews[activeViews.length - 1];
         const comps = target.components;
         for (let i = 0; i < comps.length; i++) {
             const comp = comps[i];
-            if ("__isIView__" in comp) {
-                if (comp.__isIView__) {
-                    return comp;
-                }
+            if ("__isIView__" in comp && comp.__isIView__) {
+                return comp;
             }
         }
         console.warn(`No view found in ${target.name}`);
         return undefined;
     }
-    internalOpen(viewKey, args) {
+    //----------------------------------------------------------
+    _load(viewKey) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 并发控制：如果正在加载同一个视图，返回现有的Promise
+            if (this._loadingPromises.has(viewKey)) {
+                return this._loadingPromises.get(viewKey);
+            }
+            const loadPromise = this._loadInternal(viewKey);
+            this._loadingPromises.set(viewKey, loadPromise);
+            try {
+                return yield loadPromise;
+            }
+            finally {
+                this._loadingPromises.delete(viewKey);
+            }
+        });
+    }
+    _loadInternal(viewKey) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const viewType = getViewClass(viewKey);
+            let target;
+            if (this._cache.has(viewType.name)) {
+                target = this._cache.get(viewType.name);
+            }
+            else {
+                target = yield this._generateNode({ viewKey: viewKey });
+                this._cache.set(viewType.name, target);
+            }
+            // 更新LRU顺序
+            this._updateLRUOrder(viewType.name);
+            target.active = true;
+            return target.getComponent(viewType);
+        });
+    }
+    _internalOpen(viewKey, options) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            const op = Object.assign(Object.assign({}, this._openOptions), options);
+            // 显示等待视图
+            if (op.showLoading) {
+                yield this._showLoading();
+            }
+            // 打开UI前，阻塞输入事件
+            this._blockInput(true);
+            try {
+                const view = yield this._load(viewKey);
+                addChild(view.node);
+                this._adjustMaskLayer();
+                // 先执行onEnter初始化，再播放动画
+                view.onEnter(op.args);
+                // 播放打开动画
+                yield ((_a = view.onEnterAnimation) === null || _a === void 0 ? void 0 : _a.call(view));
+                return view;
+            }
+            finally {
+                // 隐藏等待视图
+                if (op.showLoading) {
+                    this._hideLoading();
+                }
+                // 打开UI后，解除输入事件阻塞
+                this._blockInput(false);
+            }
+        });
+    }
+    _internalClose(viewKeyOrInstance, destroy) {
         return __awaiter(this, void 0, void 0, function* () {
             this._blockInput(true);
-            let view = yield this._load(viewKey, args);
-            addChild(view.node);
-            this._adjustMaskLayer();
-            view.onEnter(args);
-            this._blockInput(false);
-            return view;
+            try {
+                yield this._remove(viewKeyOrInstance, destroy);
+                this._adjustMaskLayer();
+            }
+            finally {
+                this._blockInput(false);
+            }
         });
     }
-    internalClose(viewKey, destroy) {
-        this._remove(viewKey, destroy);
-        this._adjustMaskLayer();
+    _internalOpenAndPush(viewKey, group, options) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            const op = Object.assign(Object.assign({}, this._openOptions), options);
+            // 显示等待视图
+            if (op.showLoading) {
+                yield this._showLoading();
+            }
+            // 打开UI前，阻塞输入事件
+            this._blockInput(true);
+            try {
+                const view = yield this._load(viewKey);
+                let stack = this._groupStacks.get(group);
+                if (!stack) {
+                    stack = [];
+                    this._groupStacks.set(group, stack);
+                }
+                // 暂停并移除当前栈顶视图
+                const top = stack[stack.length - 1];
+                if (top) {
+                    // 先执行onExit，再播放退出动画
+                    yield ((_a = top.onExitAnimation) === null || _a === void 0 ? void 0 : _a.call(top));
+                    top.onPause();
+                    top.node.removeFromParent();
+                }
+                // 标记视图所属组并入栈
+                if ('__group__' in view) {
+                    view.__group__ = group;
+                }
+                stack.push(view);
+                addChild(view.node);
+                this._adjustMaskLayer();
+                // 先执行onEnter初始化，再播放动画
+                view.onEnter(op.args);
+                // 播放打开动画
+                yield ((_b = view.onEnterAnimation) === null || _b === void 0 ? void 0 : _b.call(view));
+                return view;
+            }
+            finally {
+                // 隐藏等待视图
+                if (op.showLoading) {
+                    this._hideLoading();
+                }
+                // 打开UI后，解除输入事件阻塞
+                this._blockInput(false);
+            }
+        });
     }
-    internalOpenAndPush(viewKey, group, args) {
+    _internalCloseAndPop(group, destroy) {
+        var _a;
         return __awaiter(this, void 0, void 0, function* () {
+            const stack = this._groupStacks.get(group);
+            if (!stack || stack.length === 0) {
+                console.warn(`No stack or empty stack for group ${group}`);
+                return;
+            }
             this._blockInput(true);
-            let view = yield this._load(viewKey, args);
-            let stack = this._groupStacks.get(group) || [];
-            this._groupStacks.set(group, stack);
-            let top = stack[stack.length - 1];
-            if (top) {
-                top.onPause();
-                top.node.removeFromParent();
-            }
-            if ('__group__' in view) {
-                view.__group__ = group;
-            }
-            stack.push(view);
-            addChild(view.node);
-            this._adjustMaskLayer();
-            view.onEnter(args);
-            this._blockInput(false);
-            return view;
+            try {
+                // 移除当前栈顶视图
+                yield this._remove(stack.pop(), destroy);
+                // 恢复上一个视图
+                const top = stack[stack.length - 1];
+                if (top) {
+                    top.onResume();
+                    addChild(top.node);
+                    // 播放恢复动画
+                    yield ((_a = top.onEnterAnimation) === null || _a === void 0 ? void 0 : _a.call(top));
+                }
+                // 调整遮罩层级
+                this._adjustMaskLayer();
+            }
+            finally {
+                this._blockInput(false);
+            }
         });
     }
-    internalCloseAndPop(group, destroy) {
-        let stack = this._groupStacks.get(group);
-        if (!stack) {
-            console.warn(`No stack found for group ${group}`);
-            return;
-        }
-        if (stack.length == 0) {
-            console.warn(`Stack is empty for group ${group}`);
-            return;
+    /**
+     * 移除视图
+     */
+    _remove(viewKeyOrInstance, destroy, skipAnimation) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            // 如果是 string，从缓存中获取视图实例
+            if (typeof viewKeyOrInstance === 'string') {
+                const viewType = getViewClass(viewKeyOrInstance);
+                const cached = this._cache.get(viewType.name);
+                if (!cached) {
+                    console.warn(`No cached view found for ${viewType.name}`);
+                    return;
+                }
+                const viewInstance = cached.getComponent(viewType);
+                if (!viewInstance) {
+                    console.warn(`No view component found on node ${cached.name}`);
+                    return;
+                }
+                yield this._remove(viewInstance, destroy);
+                return;
+            }
+            // 处理视图实例
+            const viewInstance = viewKeyOrInstance;
+            if ('__group__' in viewInstance) {
+                viewInstance.__group__ = undefined;
+            }
+            if (!skipAnimation) {
+                // * 播放关闭动画,使用async是必要的，因为：
+                // * 确保动画播放完成后再执行onExit和节点移除，不然还没播放动画了，UI就已经没了
+                yield ((_a = viewInstance.onExitAnimation) === null || _a === void 0 ? void 0 : _a.call(viewInstance));
+            }
+            viewInstance.onExit();
+            viewInstance.node.removeFromParent();
+            viewInstance.node.active = false;
+            if (destroy) {
+                let cacheKey = viewInstance.constructor.name;
+                (_b = this._cache.get(cacheKey)) === null || _b === void 0 ? void 0 : _b.destroy();
+                this._cache.delete(cacheKey);
+                // 销毁被克隆出的UI后Node后，尝试释放 Prefab 资源
+                this._releasePrefab(viewInstance);
+            }
+        });
+    }
+    _releasePrefab(viewKey) {
+        try {
+            let prefabPath;
+            if (typeof viewKey === 'string') {
+                prefabPath = this._getPrefabPath(getViewClass(viewKey));
+            }
+            else {
+                prefabPath = this._getPrefabPath(viewKey.constructor);
+            }
+            const ResMgr = ServiceLocator.getService('ResLoader');
+            ResMgr.release(prefabPath, Prefab);
         }
-        this._remove(stack.pop(), destroy);
-        let top = stack[stack.length - 1];
-        if (top) {
-            top.onResume();
-            addChild(top.node);
+        catch (error) {
+            console.error(`Failed to release prefab for ${viewKey}:`, error);
         }
-        this._adjustMaskLayer();
     }
-    internalClearStack(group, destroy) {
-        let stack = this._groupStacks.get(group);
+    _internalClearStack(group, destroy) {
+        const stack = this._groupStacks.get(group);
         if (!stack) {
             console.warn(`No stack found for group ${group}`);
             return;
         }
+        // 清空栈中所有视图，不播放动画
         while (stack.length > 0) {
-            let view = stack.pop();
+            const view = stack.pop();
             if (view) {
-                this._remove(view, destroy);
+                this._remove(view, destroy, true);
             }
         }
+        // 调整遮罩层级
+        this._adjustMaskLayer();
+    }
+    /**
+     * 关闭所有视图，不播放动画
+     */
+    _internalCloseAll(destroy) {
+        const activeViews = this._getActiveViews();
+        for (const node of activeViews) {
+            const comps = node.components;
+            for (let i = 0; i < comps.length; i++) {
+                const comp = comps[i];
+                if ("__isIView__" in comp && comp.__isIView__) {
+                    this._remove(comp, destroy, true);
+                    break;
+                }
+            }
+        }
+        // 清空所有栈
+        this._groupStacks.clear();
+        // 调整遮罩
+        this._adjustMaskLayer();
     }
 }
 

package/dist/utils/ImageUtil.d.ts

@@ -1,4 +1,4 @@
-import { Color, Texture2D } from "cc";
+import { Color, Texture2D, SpriteFrame } from "cc";
 /**
  * 图像工具
  */
@@ -30,4 +30,8 @@ export declare class ImageUtil {
      * @param base64 Base64 字符
      */
     static base64ToBlob(base64: string): Blob;
+    /**
+     * 创建纯色SpriteFrame用于遮罩
+     */
+    static createSolidColorSpriteFrame(color?: Color): SpriteFrame;
 }

package/dist/utils/ImageUtil.js

@@ -1,4 +1,4 @@
-import { Color, Texture2D } from 'cc';
+import { Color, Texture2D, SpriteFrame, Rect } from 'cc';
 
 /**
  * 图像工具
@@ -92,6 +92,30 @@ class ImageUtil {
         }
         return new Blob([uint8Array], { type: type });
     }
+    /**
+     * 创建纯色SpriteFrame用于遮罩
+     */
+    static createSolidColorSpriteFrame(color = new Color(0, 0, 0, 125)) {
+        // 创建一个1x1像素的纯色纹理
+        const texture = new Texture2D();
+        texture.reset({
+            width: 1,
+            height: 1,
+            format: Texture2D.PixelFormat.RGBA8888
+        });
+        // 设置像素数据
+        const pixelData = new Uint8Array(4);
+        pixelData[0] = color.r;
+        pixelData[1] = color.g;
+        pixelData[2] = color.b;
+        pixelData[3] = color.a;
+        texture.uploadData(pixelData);
+        // 创建SpriteFrame
+        const spriteFrame = new SpriteFrame();
+        spriteFrame.texture = texture;
+        spriteFrame.rect = new Rect(0, 0, 1, 1);
+        return spriteFrame;
+    }
 }
 
 export { ImageUtil };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "dzkcc-mflow",
-    "version": "0.0.37",
+    "version": "0.0.39",
     "description": "A modular design and process management framework developed for the cocos engine, suitable for decoupling and dependency injection.",
     "author": "duanzhk",
     "license": "MIT",