@fenglimg/cocos-state-controller 0.1.0

package/assets/script/controller/StateControllerV2.ts.meta

@@ -0,0 +1,10 @@
+{
+  "ver": "1.1.0",
+  "uuid": "931dc519-4e18-4197-843c-50af732e8be6",
+  "importer": "typescript",
+  "isPlugin": false,
+  "loadPluginInWeb": true,
+  "loadPluginInNative": true,
+  "loadPluginInEditor": false,
+  "subMetas": {}
+}

package/assets/script/controller/StateEnumV2.ts

@@ -0,0 +1,165 @@
+/**
+ * 状态名枚举 (空骨架, 不要往里加值)。
+ *
+ * Cocos Creator 2.x 用 @property(EnumStateName) 把字段显示成枚举下拉。
+ * 下拉的实际选项不在这里静态声明 — StateControllerV2 在运行时通过
+ *   cc.Class.Attr.setClassAttr(this, "selectedIndex", "enumList", array)
+ * 把当前实例的 states 列表注入到这个枚举的下拉项。
+ */
+export enum EnumStateName {
+}
+
+/** 更新选择器的类型 */
+export enum EnumUpdateType {
+    /** 名字 */
+    Name = 1,
+    /** 可选状态 */
+    SelPage = 2,
+    /** 状态 */
+    State = 0,
+    /** 删除控制器 */
+    Delete = 4,
+    /** 初始化 */
+    Init = 3,
+    /** 更新选中的属性 */
+    Prop = 5,
+    /** 状态顺序变更 */
+    Move = 6,
+    /** 状态复制 (copySelectedState 触发, 通知 StateSelectV2 深拷贝 pageData) */
+    Copy = 7,
+    /** 录制开始 (StateControllerV2.startRecording 触发, 通知 StateSelectV2 拍 snapshot) */
+    RecordingStart = 8,
+    /** 录制结束 (StateControllerV2.stopRecording 触发, 通知 StateSelectV2 final commit + 清 snapshot) */
+    RecordingStop = 9,
+    /** 状态即将切换 (selectedIndex setter 触发, 录制中触发 diff commit) */
+    StateWillChange = 10,
+    /** 回收站硬删 (purgeDeletedState 触发, 通知 StateSelectV2 清掉 _ctrlData[stateId] 页数据), value = stateId */
+    PurgeStateId = 11,
+    /** 回收站预览进入 (previewDeletedState 触发, 通知 StateSelectV2 快照+apply 该 stateId 数据), value = stateId */
+    PreviewEnter = 12,
+    /** 回收站预览退出 (exitPreview 触发, 通知 StateSelectV2 按快照还原节点) */
+    PreviewExit = 13,
+}
+/**
+ * 控制器名字枚举 (空骨架, 不要往里加值)。
+ * 同 EnumStateName: 由 StateSelectV2 运行时把可见的控制器名字列表
+ * 注入为 currCtrlId 字段的 inspector 下拉项。
+ */
+export enum EnumCtrlName {
+}
+/**
+ * W6-4 排除清单下拉空骨架枚举 (不要往里加值)。
+ * 同 EnumStateName / EnumCtrlName: 由 StateSelectV2.refreshExcludeEnumLists 运行时
+ * 通过 cc.Class.Attr.setClassAttr(this, "addExcludeTrigger" | "removeExcludeTrigger", "enumList", array)
+ * 注入实际选项. cocos 2.x inspector 必须有 type:EnumXxx 才渲染下拉, type:cc.String 渲染输入框.
+ */
+export enum EnumExcludeSlot {
+}
+/**
+ * 🔧 核心枚举：属性名 - 定义所有支持的UI属性类型
+ *
+ * 这是整个状态控制器系统的基础枚举：
+ * 1. 每个枚举值对应一种UI属性类型
+ * 2. 枚举值的顺序决定了编辑器中的显示顺序
+ * 3. 添加新属性类型需要同步更新属性处理器
+ * 4. Non=0 是特殊值，表示"不选择任何属性"
+ *
+ * 扩展方式：
+ * 1. 在此枚举中添加新的属性类型
+ * 2. 在StatePropHandler.ts中实现对应的处理器
+ * 3. 在StateSelectV2.ts中的setDefaultProp方法中添加对应的case
+ */
+export enum EnumPropName {
+    /** 不选择 - 特殊值，表示未选择任何属性 */
+    Non = 0,
+
+    // 🔧 节点基础属性
+    /** 显示隐藏 */
+    Active = 1,
+    /** 位置 */
+    Position = 2,
+    /** 旋转、欧拉角 */
+    Euler = 6,
+    /** 缩放 */
+    Scale = 7,
+    /** 锚点 */
+    Anchor = 8,
+    /** 宽高 */
+    Size = 9,
+    /** 颜色 */
+    Color = 10,
+    /** 透明度 */
+    Opacity = 11,
+
+    // 🔧 组件相关属性
+    /** 文本 */
+    LabelString = 3,
+    /** 描边 */
+    LabelOutlineColor = 4,
+    /** 图片 */
+    SpriteFrame = 5,
+    /** 字体 */
+    Font = 12,
+    /** 滑动条 */
+    SliderProgress = 13,
+    /** 编辑框 */
+    EditboxString = 14,
+    /** 灰度 */
+    GrayScale = 15,
+    /** 按钮交互 */
+    ButtonInteractable = 16,
+
+    /** 进度条(ProgressBar) 进度 */
+    ProgressBarProgress = 17,
+    /** Toggle 选中状态 */
+    ToggleIsChecked = 18,
+    /** RichText 文本内容 */
+    RichTextString = 19,
+    /** ScrollView 启用状态 */
+    ScrollViewEnabled = 20,
+    /** Mask 组件启用状态 */
+    MaskEnabled = 21,
+
+    /** Label 字体大小 */
+    LabelFontSize = 22,
+    /** Label 行高 */
+    LabelLineHeight = 23,
+    /** Label 字符间距 (spacingX) */
+    LabelSpacingX = 24,
+    /** Label 自动换行开关 */
+    LabelWrapEnable = 25,
+    /** Sprite 填充范围 (fillRange) */
+    SpriteFillRange = 26,
+    /** Widget 启用状态 */
+    WidgetEnabled = 27,
+    /** Widget 对齐刷新模式 */
+    WidgetAlignMode = 28,
+    /** Widget 顶部对齐开关 */
+    WidgetIsAlignTop = 29,
+    /** Widget 底部对齐开关 */
+    WidgetIsAlignBottom = 30,
+    /** Widget 左侧对齐开关 */
+    WidgetIsAlignLeft = 31,
+    /** Widget 右侧对齐开关 */
+    WidgetIsAlignRight = 32,
+    /** Widget 水平居中开关 */
+    WidgetIsAlignHorizontalCenter = 33,
+    /** Widget 垂直居中开关 */
+    WidgetIsAlignVerticalCenter = 34,
+    /** Widget 顶部边距 */
+    WidgetTop = 35,
+    /** Widget 底部边距 */
+    WidgetBottom = 36,
+    /** Widget 左侧边距 */
+    WidgetLeft = 37,
+    /** Widget 右侧边距 */
+    WidgetRight = 38,
+    /** Widget 水平居中偏移 */
+    WidgetHorizontalCenter = 39,
+    /** Widget 垂直居中偏移 */
+    WidgetVerticalCenter = 40,
+
+    // 🔧 注意：旋转四元数暂时不支持，因为编辑器操作复杂
+    // /** 旋转、四元数*/
+    // Rotation,
+}

package/assets/script/controller/StateEnumV2.ts.meta

@@ -0,0 +1,10 @@
+{
+  "ver": "1.1.0",
+  "uuid": "4e415858-aa57-41a0-be08-9491363e1718",
+  "importer": "typescript",
+  "isPlugin": false,
+  "loadPluginInWeb": true,
+  "loadPluginInNative": true,
+  "loadPluginInEditor": false,
+  "subMetas": {}
+}

package/assets/script/controller/StateErrorManagerV2.ts

@@ -0,0 +1,217 @@
+/** 🔧 错误级别枚举 */
+export enum ErrorLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    FATAL = 4,
+    SILENT = 5, // 特殊级别：完全静音
+}
+
+/** 🔧 错误处理上下文接口 */
+export interface IErrorContext {
+    component?: string
+    method?: string
+    params?: unknown
+    node?: cc.Node
+}
+
+/**
+ * 🔧 统一错误处理类 - 为整个状态控制器系统提供统一的错误处理机制
+ *
+ * 核心功能：
+ * 1. 统一的日志格式和输出
+ * 2. 按级别分类的错误处理
+ * 3. 编辑器和运行时环境的适配
+ * 4. 优雅的降级处理机制
+ * 5. 常见错误场景的验证工具
+ * 6. 可配置的日志级别控制
+ */
+export class StateErrorManager {
+    private static readonly COMPONENT_NAME = "StateControllerV2";
+
+    /** 🔧 当前日志输出级别，只有高于或等于此级别的日志才会输出 */
+    private static _logLevel: ErrorLevel = ErrorLevel.WARN;
+
+    /** 🔧 设置日志输出级别 */
+    public static setLogLevel(level: ErrorLevel) {
+        this._logLevel = level;
+        this.info(`日志级别已设置为: ${ErrorLevel[level]}`);
+    }
+
+    /** 🔧 获取当前日志级别 */
+    public static getLogLevel(): ErrorLevel {
+        return this._logLevel;
+    }
+
+    /** 🔧 检查是否应该输出指定级别的日志 */
+    private static shouldLog(level: ErrorLevel): boolean {
+        return level >= this._logLevel;
+    }
+
+    /**
+     * 🔧 统一日志输出方法 - 根据不同错误级别和环境选择合适的输出方式
+     *
+     * @param level 错误级别
+     * @param message 错误消息
+     * @param context 错误上下文，包含组件、方法、参数等详细信息
+     */
+    private static log(level: ErrorLevel, message: string, context?: IErrorContext) {
+        // 🔧 级别检查：如果当前级别低于设定级别，则不输出
+        if (!this.shouldLog(level)) {
+            return;
+        }
+
+        const levelName = ErrorLevel[level];
+        const prefix = `[${this.COMPONENT_NAME}][${levelName}]`;
+        const fullMessage = context
+            ? `${prefix} ${message} | Context: ${JSON.stringify(context)}`
+            : `${prefix} ${message}`;
+
+        // 🔧 根据错误级别选择不同的输出方式
+        switch (level) {
+            case ErrorLevel.DEBUG:
+                // 🔧 调试信息：仅在开发模式下输出，使用较低的优先级
+                if (CC_EDITOR) {
+                    cc.log(`🔍 ${fullMessage}`);
+                }
+                else {
+                    // console.debug ? console.debug(fullMessage) : console.log(fullMessage);
+                }
+                break;
+            case ErrorLevel.INFO:
+                if (CC_EDITOR) {
+                    cc.log(fullMessage);
+                }
+                else {
+                    // console.log(fullMessage);
+                }
+                break;
+            case ErrorLevel.WARN:
+                // 🔧 编辑器环境使用cc.warn，运行时使用console.warn
+                if (CC_EDITOR) {
+                    cc.warn(fullMessage);
+                }
+                else {
+                    // console.warn(fullMessage);
+                }
+                break;
+            case ErrorLevel.ERROR:
+                // 🔧 编辑器环境使用cc.error，运行时使用console.error
+                if (CC_EDITOR) {
+                    cc.error(fullMessage);
+                }
+                else {
+                    // console.error(fullMessage);
+                }
+                break;
+            case ErrorLevel.FATAL:
+                // 🔧 致命错误：使用特殊标识符，便于快速定位严重问题
+                if (CC_EDITOR) {
+                    cc.error(`💥 FATAL: ${fullMessage}`);
+                }
+                else {
+                    // console.error(`💥 FATAL: ${fullMessage}`);
+                }
+                break;
+        }
+    }
+
+    /** 友好的用户提示 */
+    public static userFriendlyError(userMessage: string, technicalDetails?: string, context?: IErrorContext) {
+        this.log(ErrorLevel.ERROR, userMessage, context);
+        if (technicalDetails) {
+            this.log(ErrorLevel.INFO, `技术细节: ${technicalDetails}`, context);
+        }
+    }
+
+    /**
+     * 🔧 核心方法：优雅降级处理 - 在操作失败时提供安全的备选方案
+     *
+     * 这是系统稳定性的关键机制：
+     * 1. 捕获所有异常，避免系统崩溃
+     * 2. 提供合理的降级值，保证功能连续性
+     * 3. 记录错误信息，便于问题追踪
+     * 4. 对用户透明，不影响正常使用流程
+     *
+     * @param operation 要执行的操作函数
+     * @param fallbackValue 操作失败时的降级返回值
+     * @param errorMessage 自定义错误消息
+     * @returns 操作成功时返回原值，失败时返回降级值
+     */
+    public static gracefulFallback<T>(operation: () => T, fallbackValue: T, errorMessage?: string): T {
+        try {
+            return operation();
+        }
+        catch (error) {
+            // 🔧 记录错误并返回安全的降级值，确保系统继续运行
+            this.log(ErrorLevel.WARN, errorMessage || "操作失败，使用降级处理", { params: { error: error.message } });
+            return fallbackValue;
+        }
+    }
+
+    /**
+     * 🔧 节点有效性验证 - 防止对无效节点的操作导致系统错误
+     *
+     * 常见的节点无效场景：
+     * 1. 节点被删除但引用仍然存在
+     * 2. 节点在场景切换时被销毁
+     * 3. 节点引用为null或undefined
+     * 4. 节点的isValid属性为false
+     *
+     * @param node 要验证的节点
+     * @param context 验证上下文信息
+     * @returns 节点有效返回true，无效返回false
+     */
+    public static validateNode(node: cc.Node, context?: IErrorContext): boolean {
+        if (!node || !node.isValid) {
+            this.userFriendlyError(
+                "节点无效或已被销毁",
+                "请检查节点是否存在且未被删除",
+                context,
+            );
+            return false;
+        }
+        return true;
+    }
+
+    /** 验证属性类型 */
+    public static validatePropType(propType: unknown, context?: IErrorContext): boolean {
+        if (propType === undefined || propType === null) {
+            this.userFriendlyError(
+                "属性类型不能为空",
+                "请选择有效的属性类型",
+                context,
+            );
+            return false;
+        }
+        return true;
+    }
+
+    // 🔧 便捷方法：直接调用不同级别的日志
+
+    /** 调试日志 */
+    public static debug(message: string, context?: IErrorContext) {
+        this.log(ErrorLevel.DEBUG, message, context);
+    }
+
+    /** 信息日志 */
+    public static info(message: string, context?: IErrorContext) {
+        this.log(ErrorLevel.INFO, message, context);
+    }
+
+    /** 警告日志 */
+    public static warn(message: string, context?: IErrorContext) {
+        this.log(ErrorLevel.WARN, message, context);
+    }
+
+    /** 错误日志 */
+    public static error(message: string, context?: IErrorContext) {
+        this.log(ErrorLevel.ERROR, message, context);
+    }
+
+    /** 致命错误日志 */
+    public static fatal(message: string, context?: IErrorContext) {
+        this.log(ErrorLevel.FATAL, message, context);
+    }
+}

package/assets/script/controller/StateErrorManagerV2.ts.meta

@@ -0,0 +1,10 @@
+{
+  "ver": "1.1.0",
+  "uuid": "cf911d61-4a14-431a-9f41-f9ac38d712ba",
+  "importer": "typescript",
+  "isPlugin": false,
+  "loadPluginInWeb": true,
+  "loadPluginInNative": true,
+  "loadPluginInEditor": false,
+  "subMetas": {}
+}