dzkcc-mflow 0.0.38 → 0.0.40

package/README.md

@@ -7,7 +7,7 @@
 ## 核心特性
 
 ✨ **模块化设计** - 通过 Manager 和 Model 模式实现业务逻辑的模块化管理  
-✨ **依赖注入** - 基于装饰器的自动依赖注入和 Symbol 映射  
+✨ **依赖注入** - 基于装饰器的自动依赖注入和字符串标识  
 ✨ **服务定位器** - 统一的服务管理机制，实现服务解耦  
 ✨ **UI 管理系统** - 完整的 UI 界面管理方案，支持视图栈和分组  
 ✨ **事件系统** - 强大的事件广播和监听机制，支持粘性事件  
@@ -62,7 +62,7 @@ export class GameCore extends CocosCore {
 
 ### 1. 核心概念
 
-了解框架的基础架构、Core 容器、ServiceLocator、Manager、Model、View 和 Symbol 映射系统。
+了解框架的基础架构、Core 容器、ServiceLocator、Manager、Model、View 和字符串标识系统。
 
 📖 **查看文档**: [核心概念](./docs/CORE_CONCEPTS.md)
 
@@ -171,12 +171,13 @@ mf.reddot.on('main/bag', (totalCount) => {
 // types/api-type-hints.d.ts
 declare module 'dzkcc-mflow/core' {
     interface ModelTypeMap {
-        [ModelNames.User]: UserModel;
+        UserModel: UserModel;
+        GameModel: GameModel;
     }
 }
 
 // 使用时自动推断类型
-const userModel = mf.core.getModel(ModelNames.User);
+const userModel = mf.core.getModel('UserModel');
 userModel.name;  // ✅ 有完整的代码补全
 ```
 
@@ -187,7 +188,7 @@ userModel.name;  // ✅ 有完整的代码补全
 **编辑器菜单**：**mflow-tools -> Generate API type hints/生成API类型提示**
 
 > ⚠️ **如果 getManager/getModel 没有类型提示**？
-> 
+>
 > 需要创建类型映射文件，使用编辑器的 **mflow-tools -> Generate API type hints/生成API类型提示** 自动生成，
 > 或查看 [类型提示问题解决方案](./docs/TYPE_INFERENCE_FIX.md)
 
@@ -219,40 +220,58 @@ Cocos Creator 编辑器插件，自动生成 UI 脚本，自动设置组件引
 ## 架构图
 
 ```
-┌─────────────────────────────────────────────────┐
-│                    全局对象 mf                    │
-│  (统一访问入口，暴露所有框架能力)                   │
-└──────────────────┬──────────────────────────────┘
-                   │
-    ┌──────────────┼──────────────┐
-    │              │              │
-    ▼              ▼              ▼
-┌─────────┐  ┌──────────┐  ┌──────────┐
-│  Core   │  │ Services │  │  Views   │
-│(核心容器)│  │(基础服务) │  │ (UI界面)  │
-└─────────┘  └──────────┘  └──────────┘
-    │              │              │
-    ├─ Manager ─┐  ├─ UIManager  ├─ BaseView
-    │           │  ├─ ResLoader  └─ 自动资源管理
-    ├─ Model ───┤  ├─ EventMgr     自动事件清理
-    │           │  ├─ HttpMgr
-    └─ Symbol ──┘  ├─ SocketMgr
-       映射系统    └─ RedDotMgr
+┌─────────────────────────────────────────────────────────────────┐
+│                          全局对象 mf                              │
+│              (统一访问入口，暴露所有框架能力)                        │
+└─────────────────────────┬───────────────────────────────────────┘
+                          │
+    ┌─────────────────────┼─────────────────────┐
+    │                     │                     │
+    ▼                     ▼                     ▼
+┌─────────┐  ┌─────────────────────────────────────────┐  ┌──────────┐
+│  Core   │  │            ServiceLocator              │  │  Views   │
+│(核心容器)│  │           (服务定位器)                  │  │ (UI界面)  │
+└─────────┘  └─────────────────────────────────────────┘  └──────────┘
+    │                     │                                   │
+    ├─ Manager ─┐         ├─ Broadcaster(EventMgr)             ├─ BaseView
+    │           │         ├─ UIManager                         └─ 自动资源管理
+    ├─ Model ───┤         ├─ ResLoader                          └─ 自动事件清理
+    │           │         ├─ HttpManager
+    └─ 字符串 ───┘         ├─ WebSocketManager
+       标识系统              └─ RedDotManager
 ```
 
+### 架构说明
+
+1. **全局对象 `mf`** - 提供统一访问入口，通过 `mf.core`、`mf.gui`、`mf.event` 等访问各模块功能
+
+2. **Core (核心容器)** - 管理业务层的 Model 和 Manager，支持依赖注入和类型推断
+
+3. **ServiceLocator (服务定位器)** - 统一管理框架的基础服务，包括：
+   - **Broadcaster** - 事件广播系统，支持粘性事件
+   - **UIManager** - UI界面管理系统，支持视图栈和生命周期管理
+   - **ResLoader** - 资源加载器，支持自动释放和缓存管理
+   - **HttpManager** - HTTP网络客户端，支持RESTful API
+   - **WebSocketManager** - WebSocket实时通信，支持自动重连和心跳
+   - **RedDotManager** - 树形结构的红点提示管理系统
+
+4. **Views (UI界面)** - 基于 BaseView 的界面组件，支持完整的生命周期管理和自动资源清理
+
+5. **依赖注入系统** - 通过装饰器(@manager、@model、@view)和字符串标识实现自动依赖注入
+
 ## 使用全局对象
 
 框架提供了全局对象 `mf` 用于访问所有功能：
 
 ```typescript
 // 访问 Manager
-mf.core.getManager(ManagerNames.GameManager);
+mf.core.getManager('GameManager');
 
 // 访问 Model
-mf.core.getModel(ModelNames.UserModel);
+mf.core.getModel('UserModel');
 
 // UI 管理
-mf.gui.open(ViewNames.HomeView);
+mf.gui.open('HomeView');
 
 // 事件系统
 mf.event.dispatch('gameStart');

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/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,183 @@
-import { Component } from "cc";
+import { Component, Node, Color } from "cc";
 import { IUIManager, IView } from "../core";
-type ICocosView = IView & Component;
+/**
+ * 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;
+}
+interface IInternalView extends IView {
+    __group__: string | undefined;
+    __isIView__: boolean;
+}
+type ICocosView = IInternalView & 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 {};