@fenglimg/cocos-state-controller 0.1.0

package/assets/script/controller/StatePropHandlerV2.ts

@@ -0,0 +1,316 @@
+/**
+ * 属性处理器系统
+ *
+ * Phase 2.1 重构: 把原 41 个手写 PropHandler class (~822 行) 改成表驱动:
+ *   - 1 个通用 PropHandlerManager (3 个静态方法 + 注册 Map)
+ *   - 2 个辅助 factory: nodeProp / compProp
+ *   - 一张注册表枚举所有 prop ↔ accessor 映射
+ *
+ * 设计要点:
+ * - null node 守卫集中在 PropHandlerManager 三个静态方法
+ *   单 handler 内不再重复 null 检查
+ * - 组件依赖 prop 走 compProp(compType, fieldName), 自带"缺组件 -> undefined"
+ * - 节点直接 prop / 需要 clone 复合类型的特殊 case 走 nodeProp(get, set)
+ * - 扩展新 prop: 加一行 PropHandlerManager.register(...) 即可, 不再写新 class
+ */
+
+import { EnumPropName } from "./StateEnumV2";
+import { StateErrorManager } from "./StateErrorManagerV2";
+
+/** 属性值统一类型 */
+export type TPropValue
+    = | number
+      | boolean
+      | string
+      | cc.Vec3
+      | cc.Vec2
+      | cc.Color
+      | cc.Size
+      | cc.Quat
+      | cc.SpriteFrame
+      | cc.Font
+      | undefined;
+
+/** 属性处理器接口 */
+export interface IPropHandler {
+    /** 读取节点 / 组件当前属性值; 假定 node 非 null (manager 已做守卫) */
+    getValue(node: cc.Node): TPropValue | undefined
+    /** 写入节点 / 组件属性值; 假定 node 非 null */
+    setValue(node: cc.Node, value: TPropValue): void
+    /** 默认值, 通常等同 getValue */
+    getDefaultValue(node: cc.Node): TPropValue | undefined
+    /**
+     * 录制 diff 用: 判断两个值是否等同.
+     *  - 基础类型 (number/string/boolean): ===
+     *  - 复合类型 (Vec/Color/Size): 按字段值比 (含 alpha)
+     *  - 资源类型 (SpriteFrame/Font): 引用比 (===)
+     *  - undefined/null 双方为 nil 即 true
+     * 默认实现见 PropHandlerManager 注册路径 (factory 自带 isEqual)。
+     */
+    isEqual(a: TPropValue, b: TPropValue): boolean
+}
+
+/**
+ * 属性处理器统一管理类
+ *
+ * 三个静态访问方法集中做 null node 守卫, 之后委派给注册的 handler。
+ */
+export class PropHandlerManager {
+    private static handlers = new Map<EnumPropName, IPropHandler>();
+
+    public static register(propType: EnumPropName, handler: IPropHandler): void {
+        this.handlers.set(propType, handler);
+    }
+
+    public static getHandler(propType: EnumPropName): IPropHandler | undefined {
+        return this.handlers.get(propType);
+    }
+
+    /** 列出所有已注册 prop type (供录制全 prop snapshot 等扫描场景). */
+    public static listRegisteredPropTypes(): EnumPropName[] {
+        const out: EnumPropName[] = [];
+        this.handlers.forEach((_, k) => out.push(k));
+        return out;
+    }
+
+    public static getValue(propType: EnumPropName, node: cc.Node): TPropValue | undefined {
+        if (!node) return undefined;
+        const handler = this.getHandler(propType);
+        return handler ? handler.getValue(node) : undefined;
+    }
+
+    public static setValue(propType: EnumPropName, node: cc.Node, value: TPropValue): void {
+        if (!node) return;
+        const handler = this.getHandler(propType);
+        if (handler) handler.setValue(node, value);
+    }
+
+    public static getDefaultValue(propType: EnumPropName, node: cc.Node): TPropValue | undefined {
+        if (!node) return undefined;
+        const handler = this.getHandler(propType);
+        return handler ? handler.getDefaultValue(node) : undefined;
+    }
+
+    /**
+     * 录制 diff 用: 判断两个值是否等同. 未注册的 propType 视为 false (保守, 视为有变化)。
+     * 双方均为 nil (undefined / null) 视为 true。
+     */
+    public static isEqual(propType: EnumPropName, a: TPropValue, b: TPropValue): boolean {
+        const aNil = a === undefined || a === null;
+        const bNil = b === undefined || b === null;
+        if (aNil && bNil) return true;
+        if (aNil !== bNil) return false;
+        const handler = this.getHandler(propType);
+        if (!handler) return false;
+        return handler.isEqual(a, b);
+    }
+}
+
+// ============================== isEqual helpers ==============================
+
+/** 默认 isEqual: ===, 用于基础类型与资源引用比 */
+function eqStrict(a: TPropValue, b: TPropValue): boolean {
+    return a === b;
+}
+
+/** Vec3 按值比 (x/y/z) */
+function eqVec3(a: TPropValue, b: TPropValue): boolean {
+    const av = a as cc.Vec3;
+    const bv = b as cc.Vec3;
+    return av.x === bv.x && av.y === bv.y && av.z === bv.z;
+}
+
+/** Vec2 按值比 (x/y) */
+function eqVec2(a: TPropValue, b: TPropValue): boolean {
+    const av = a as cc.Vec2;
+    const bv = b as cc.Vec2;
+    return av.x === bv.x && av.y === bv.y;
+}
+
+/** Color 按值比 (r/g/b/a) */
+function eqColor(a: TPropValue, b: TPropValue): boolean {
+    const ac = a as cc.Color;
+    const bc = b as cc.Color;
+    return ac.r === bc.r && ac.g === bc.g && ac.b === bc.b && ac.a === bc.a;
+}
+
+/** Size 按值比 (width/height) */
+function eqSize(a: TPropValue, b: TPropValue): boolean {
+    const as = a as cc.Size;
+    const bs = b as cc.Size;
+    return as.width === bs.width && as.height === bs.height;
+}
+
+/** 节点直接属性 (cc.Node 上的字段或方法访问); 需自定 get/set 控制复合类型 clone */
+function nodeProp<T extends TPropValue>(
+    get: (n: cc.Node) => T | undefined,
+    set: (n: cc.Node, v: T) => void,
+    isEqual: (a: TPropValue, b: TPropValue) => boolean = eqStrict,
+): IPropHandler {
+    return {
+        getValue: get as (n: cc.Node) => TPropValue | undefined,
+        setValue: (n, v) => set(n, v as T),
+        getDefaultValue: get as (n: cc.Node) => TPropValue | undefined,
+        isEqual,
+    };
+}
+
+/** 组件依赖属性 (节点上挂载的 cc.Component, 直接 field 读写); 缺组件返回 undefined */
+function compProp(
+    compType: typeof cc.Component | any,
+    fieldName: string,
+    isEqual: (a: TPropValue, b: TPropValue) => boolean = eqStrict,
+): IPropHandler {
+    return {
+        getValue: (node) => {
+            const c = node.getComponent(compType);
+            return c ? (c as any)[fieldName] : undefined;
+        },
+        setValue: (node, value) => {
+            const c = node.getComponent(compType);
+            if (c) (c as any)[fieldName] = value;
+        },
+        getDefaultValue: (node) => {
+            const c = node.getComponent(compType);
+            return c ? (c as any)[fieldName] : undefined;
+        },
+        isEqual,
+    };
+}
+
+// ============================== 注册表 ==============================
+
+// ---- 节点直接属性 ----
+PropHandlerManager.register(EnumPropName.Active,
+    nodeProp<boolean>(n => n.active, (n, v) => {
+        n.active = v;
+    }));
+
+PropHandlerManager.register(EnumPropName.Position,
+    nodeProp<cc.Vec3>(n => cc.v3(n.position), (n, v) => {
+        n.position = v;
+    }, eqVec3));
+
+PropHandlerManager.register(EnumPropName.Euler,
+    nodeProp<cc.Vec3>(n => cc.v3(n.eulerAngles), (n, v) => {
+        n.eulerAngles = v;
+    }, eqVec3));
+
+PropHandlerManager.register(EnumPropName.Scale,
+    nodeProp<number>(n => n.scale, (n, v) => {
+        n.scale = v;
+    }));
+
+PropHandlerManager.register(EnumPropName.Anchor,
+    nodeProp<cc.Vec2>(
+        n => cc.v2(n.anchorX, n.anchorY),
+        (n, v) => n.setAnchorPoint(v),
+        eqVec2,
+    ));
+
+PropHandlerManager.register(EnumPropName.Size,
+    nodeProp<cc.Size>(
+        (n) => {
+            const s = n.getContentSize();
+            return cc.size(s.width, s.height);
+        },
+        (n, v) => {
+            n.setContentSize(v);
+        },
+        eqSize,
+    ));
+
+PropHandlerManager.register(EnumPropName.Color,
+    nodeProp<cc.Color>(
+        (n) => {
+            const c = n.color;
+            return cc.color(c.r, c.g, c.b, c.a);
+        },
+        (n, v) => {
+            n.color = v;
+        },
+        eqColor,
+    ));
+
+PropHandlerManager.register(EnumPropName.Opacity,
+    nodeProp<number>(n => n.opacity, (n, v) => {
+        n.opacity = v;
+    }));
+
+// ---- Label 组件 ----
+PropHandlerManager.register(EnumPropName.LabelString, compProp(cc.Label, "string"));
+PropHandlerManager.register(EnumPropName.LabelFontSize, compProp(cc.Label, "fontSize"));
+PropHandlerManager.register(EnumPropName.LabelLineHeight, compProp(cc.Label, "lineHeight"));
+PropHandlerManager.register(EnumPropName.LabelSpacingX, compProp(cc.Label, "spacingX"));
+PropHandlerManager.register(EnumPropName.LabelWrapEnable, compProp(cc.Label, "enableWrapText"));
+PropHandlerManager.register(EnumPropName.Font, compProp(cc.Label, "font"));
+
+// ---- LabelOutline (颜色需 clone) ----
+PropHandlerManager.register(EnumPropName.LabelOutlineColor, {
+    getValue: (node) => {
+        const c = node.getComponent(cc.LabelOutline);
+        if (!c) return undefined;
+        const col = c.color;
+        return cc.color(col.r, col.g, col.b, col.a);
+    },
+    setValue: (node, value) => {
+        const c = node.getComponent(cc.LabelOutline);
+        if (c) c.color = value as cc.Color;
+    },
+    getDefaultValue: (node) => {
+        const c = node.getComponent(cc.LabelOutline);
+        if (!c) return undefined;
+        const col = c.color;
+        return cc.color(col.r, col.g, col.b, col.a);
+    },
+    isEqual: eqColor,
+});
+
+// ---- Sprite ----
+PropHandlerManager.register(EnumPropName.SpriteFrame, compProp(cc.Sprite, "spriteFrame"));
+PropHandlerManager.register(EnumPropName.SpriteFillRange, compProp(cc.Sprite, "fillRange"));
+
+// ---- 其他单字段组件 ----
+PropHandlerManager.register(EnumPropName.SliderProgress, compProp(cc.Slider, "progress"));
+PropHandlerManager.register(EnumPropName.EditboxString, compProp(cc.EditBox, "string"));
+PropHandlerManager.register(EnumPropName.ButtonInteractable, compProp(cc.Button, "interactable"));
+PropHandlerManager.register(EnumPropName.ProgressBarProgress, compProp(cc.ProgressBar, "progress"));
+PropHandlerManager.register(EnumPropName.ToggleIsChecked, compProp(cc.Toggle, "isChecked"));
+PropHandlerManager.register(EnumPropName.RichTextString, compProp(cc.RichText, "string"));
+PropHandlerManager.register(EnumPropName.ScrollViewEnabled, compProp(cc.ScrollView, "enabled"));
+PropHandlerManager.register(EnumPropName.MaskEnabled, compProp(cc.Mask, "enabled"));
+
+// ---- GrayScale (Cocos 2.x 需要走材质, 这里保留 stub 行为) ----
+PropHandlerManager.register(EnumPropName.GrayScale, {
+    getValue: (node) => {
+        const sprite = node.getComponent(cc.Sprite);
+        return sprite ? false : undefined;
+    },
+    setValue: (node, _value) => {
+        const sprite = node.getComponent(cc.Sprite);
+        if (sprite) {
+            StateErrorManager.warn("GrayScale属性在Cocos Creator 2.x中需要通过材质实现");
+        }
+    },
+    getDefaultValue: (node) => {
+        const sprite = node.getComponent(cc.Sprite);
+        return sprite ? false : undefined;
+    },
+    isEqual: eqStrict,
+});
+
+// ---- Widget (14 个统一 field 风格) ----
+PropHandlerManager.register(EnumPropName.WidgetEnabled, compProp(cc.Widget, "enabled"));
+PropHandlerManager.register(EnumPropName.WidgetAlignMode, compProp(cc.Widget, "alignMode"));
+PropHandlerManager.register(EnumPropName.WidgetIsAlignTop, compProp(cc.Widget, "isAlignTop"));
+PropHandlerManager.register(EnumPropName.WidgetIsAlignBottom, compProp(cc.Widget, "isAlignBottom"));
+PropHandlerManager.register(EnumPropName.WidgetIsAlignLeft, compProp(cc.Widget, "isAlignLeft"));
+PropHandlerManager.register(EnumPropName.WidgetIsAlignRight, compProp(cc.Widget, "isAlignRight"));
+PropHandlerManager.register(EnumPropName.WidgetIsAlignHorizontalCenter, compProp(cc.Widget, "isAlignHorizontalCenter"));
+PropHandlerManager.register(EnumPropName.WidgetIsAlignVerticalCenter, compProp(cc.Widget, "isAlignVerticalCenter"));
+PropHandlerManager.register(EnumPropName.WidgetTop, compProp(cc.Widget, "top"));
+PropHandlerManager.register(EnumPropName.WidgetBottom, compProp(cc.Widget, "bottom"));
+PropHandlerManager.register(EnumPropName.WidgetLeft, compProp(cc.Widget, "left"));
+PropHandlerManager.register(EnumPropName.WidgetRight, compProp(cc.Widget, "right"));
+PropHandlerManager.register(EnumPropName.WidgetHorizontalCenter, compProp(cc.Widget, "horizontalCenter"));
+PropHandlerManager.register(EnumPropName.WidgetVerticalCenter, compProp(cc.Widget, "verticalCenter"));

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

@@ -0,0 +1,10 @@
+{
+  "ver": "1.1.0",
+  "uuid": "1f8859ca-725f-4313-bf0d-1838a23cbc84",
+  "importer": "typescript",
+  "isPlugin": false,
+  "loadPluginInWeb": true,
+  "loadPluginInNative": true,
+  "loadPluginInEditor": false,
+  "subMetas": {}
+}

package/assets/script/controller/StatePropertyControlService.ts

@@ -0,0 +1,148 @@
+/**
+ * 属性控制服务 (Phase 5.2)
+ *
+ * 从 StateSelectV2 抽出的 stateless 服务, 负责回答三个问题:
+ *   1. 节点上是否有挂支持某 prop 类型的组件? (isPropertyAvailable)
+ *   2. propData 中某 prop 是否处于受控状态? (isPropertyControlled)
+ *   3. 列出节点上当前所有可用的 prop. (scanAvailableProperties)
+ *
+ * 设计点:
+ * - 全部为静态方法, 状态从外部传入 (node / propData), 不持有任何实例状态
+ * - 组件依赖检查改为注册表驱动 (原 56 行 switch → 14 行 register),
+ *   插件可通过 registerComponentProp 注入自定义 prop 类型 ↔ 组件 的关联
+ *
+ * 不在本服务范围:
+ *   - togglePropertyControl / addPropertyControl / removePropertyControl /
+ *     autoConfigureAllProperties — 这些紧耦合 StateSelectV2 内部状态 (propData
+ *     的写入 + setPropValue + sync 链路), 留在 StateSelectV2.
+ */
+
+import { EnumPropName } from "./StateEnumV2";
+import { TProp } from "./StateSelectV2";
+
+/** 组件可用性检查函数: 给一个节点, 回答 "节点上是否挂了支持本 prop 的组件?" */
+export type ComponentAvailabilityCheck = (node: cc.Node) => boolean;
+
+export class PropertyControlService {
+    /** 节点基础属性 — 任何节点上都可用, 与组件无关. */
+    private static nodeBasicProps: ReadonlySet<EnumPropName> = new Set([
+        EnumPropName.Active,
+        EnumPropName.Position,
+        EnumPropName.Scale,
+        EnumPropName.Color,
+        EnumPropName.Size,
+        EnumPropName.Euler,
+        EnumPropName.Anchor,
+        EnumPropName.Opacity,
+    ]);
+
+    /** 组件依赖 prop 的可用性检查注册表. 插件扩展点. */
+    private static componentAvailability = new Map<EnumPropName, ComponentAvailabilityCheck>();
+
+    /**
+     * 注册一个组件依赖的 prop ↔ 组件 关联.
+     *
+     * 调用形如:
+     *   PropertyControlService.registerComponentProp(EnumPropName.LabelString,
+     *       node => !!node.getComponent(cc.Label));
+     *
+     * 后续 isPropertyAvailable / scanAvailableProperties 自动识别该 prop.
+     */
+    public static registerComponentProp(propType: EnumPropName, check: ComponentAvailabilityCheck): void {
+        this.componentAvailability.set(propType, check);
+    }
+
+    /** 节点上是否可以使用某 prop 类型. */
+    public static isPropertyAvailable(node: cc.Node, propType: EnumPropName): boolean {
+        if (!node || !node.isValid) {
+            return false;
+        }
+        if (this.nodeBasicProps.has(propType)) {
+            return true;
+        }
+        const check = this.componentAvailability.get(propType);
+        return check ? check(node) : false;
+    }
+
+    /** propData 中某 prop 是否标记为受控. */
+    public static isPropertyControlled(propData: TProp | null | undefined, propType: EnumPropName): boolean {
+        if (!propData) {
+            return false;
+        }
+        const controlledProps = propData.$$controlledProps$$ || {};
+        const propName = EnumPropName[propType];
+        if (controlledProps[propName] !== undefined) {
+            return true;
+        }
+        // 兼容旧 $$changedProp$$ 结构 (迁移期遗留)
+        const changedProp = propData.$$changedProp$$ || {};
+        return !!changedProp[propName];
+    }
+
+    /** 列出当前节点上所有可用的 prop. */
+    public static scanAvailableProperties(node: cc.Node): EnumPropName[] {
+        if (!node || !node.isValid) {
+            return [];
+        }
+        const out: EnumPropName[] = [];
+        // cc.Enum(EnumPropName) 把数字反向映射 key 设为不可枚举, for-in 只剩名字 key,
+        // 通过名字反查数字值 (与 StateSelectV2.scanAvailableProperties Phase 4.3 修复对应).
+        for (const propKey in EnumPropName) {
+            const propType = (EnumPropName as any)[propKey];
+            if (typeof propType !== "number" || propType === EnumPropName.Non) {
+                continue;
+            }
+            if (this.isPropertyAvailable(node, propType as EnumPropName)) {
+                out.push(propType as EnumPropName);
+            }
+        }
+        return out;
+    }
+}
+
+// ============================== 内置组件 prop 注册 ==============================
+// 等价于原 StateSelectV2.checkNodeHasComponentForProp 的 switch 表, 改为表驱动.
+
+PropertyControlService.registerComponentProp(EnumPropName.LabelString, n => !!n.getComponent(cc.Label));
+PropertyControlService.registerComponentProp(EnumPropName.Font, n => !!n.getComponent(cc.Label));
+PropertyControlService.registerComponentProp(EnumPropName.LabelFontSize, n => !!n.getComponent(cc.Label));
+PropertyControlService.registerComponentProp(EnumPropName.LabelLineHeight, n => !!n.getComponent(cc.Label));
+PropertyControlService.registerComponentProp(EnumPropName.LabelSpacingX, n => !!n.getComponent(cc.Label));
+PropertyControlService.registerComponentProp(EnumPropName.LabelWrapEnable, n => !!n.getComponent(cc.Label));
+
+PropertyControlService.registerComponentProp(EnumPropName.LabelOutlineColor, n => !!n.getComponent(cc.LabelOutline));
+
+PropertyControlService.registerComponentProp(EnumPropName.SpriteFrame, n => !!n.getComponent(cc.Sprite));
+PropertyControlService.registerComponentProp(EnumPropName.SpriteFillRange, n => !!n.getComponent(cc.Sprite));
+
+PropertyControlService.registerComponentProp(EnumPropName.SliderProgress, n => !!n.getComponent(cc.Slider));
+PropertyControlService.registerComponentProp(EnumPropName.EditboxString, n => !!n.getComponent(cc.EditBox));
+// GrayScale 是项目自定义组件, 用字符串名查
+PropertyControlService.registerComponentProp(EnumPropName.GrayScale, n => !!n.getComponent("GrayScale"));
+PropertyControlService.registerComponentProp(EnumPropName.ButtonInteractable, n => !!n.getComponent(cc.Button));
+PropertyControlService.registerComponentProp(EnumPropName.ProgressBarProgress, n => !!n.getComponent(cc.ProgressBar));
+PropertyControlService.registerComponentProp(EnumPropName.ToggleIsChecked, n => !!n.getComponent(cc.Toggle));
+PropertyControlService.registerComponentProp(EnumPropName.RichTextString, n => !!n.getComponent(cc.RichText));
+PropertyControlService.registerComponentProp(EnumPropName.ScrollViewEnabled, n => !!n.getComponent(cc.ScrollView));
+PropertyControlService.registerComponentProp(EnumPropName.MaskEnabled, n => !!n.getComponent(cc.Mask));
+
+// Widget 14 个字段都依赖 cc.Widget
+const widgetProps = [
+    EnumPropName.WidgetEnabled,
+    EnumPropName.WidgetAlignMode,
+    EnumPropName.WidgetIsAlignTop,
+    EnumPropName.WidgetIsAlignBottom,
+    EnumPropName.WidgetIsAlignLeft,
+    EnumPropName.WidgetIsAlignRight,
+    EnumPropName.WidgetIsAlignHorizontalCenter,
+    EnumPropName.WidgetIsAlignVerticalCenter,
+    EnumPropName.WidgetTop,
+    EnumPropName.WidgetBottom,
+    EnumPropName.WidgetLeft,
+    EnumPropName.WidgetRight,
+    EnumPropName.WidgetHorizontalCenter,
+    EnumPropName.WidgetVerticalCenter,
+];
+for (const p of widgetProps) {
+    PropertyControlService.registerComponentProp(p, n => !!n.getComponent(cc.Widget));
+}

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

@@ -0,0 +1,10 @@
+{
+  "ver": "1.1.0",
+  "uuid": "d86a41dd-958a-4c5c-9b14-69e851b9892d",
+  "importer": "typescript",
+  "isPlugin": false,
+  "loadPluginInWeb": true,
+  "loadPluginInNative": true,
+  "loadPluginInEditor": false,
+  "subMetas": {}
+}