@vvfx/sdk 0.2.8 → 0.2.10

package/dist/sdk-item/frame-item.js

@@ -0,0 +1,217 @@
+import { FrameLayoutMode } from '../types';
+import { SDKItemType } from './types';
+import { BaseItem } from './base-item';
+import { deepClone } from '../utils/common-utils';
+import { generateGUID } from '../shared';
+/**
+ * @description 画板/框架元素 SDKItem 类
+ * @description 支持自动布局和自由布局两种模式
+ * @description 底层以 composition 形式渲染
+ */
+export class FrameItem extends BaseItem {
+    /**
+     * @description 元素类型
+     */
+    type = SDKItemType.FRAME;
+    /**
+     * @description 预合成元素ID
+     */
+    subCompositionItemId;
+    /**
+     * @description 元素属性
+     */
+    property;
+    constructor(options) {
+        super(options);
+        this.subCompositionItemId = '';
+        // 初始化属性
+        this.property = {
+            position: options.property?.position ?? [0, 0],
+            rotation: options.property?.rotation ?? [0, 0, 0],
+            width: options.property?.width ?? 0,
+            height: options.property?.height ?? 0,
+            scale: options.property?.scale ?? [1, 1],
+            layoutMode: options.property?.layoutMode ?? FrameLayoutMode.FREE,
+            children: [...options.children ?? []],
+            autoLayoutConfig: options.property?.autoLayoutConfig,
+            layoutInfos: options.property?.layoutInfos ?? {},
+        };
+    }
+    // ==================== 便捷访问器 ====================
+    /**
+     * @description 子元素ID列表（只读）
+     */
+    get children() {
+        return this.property.children;
+    }
+    /**
+     * @description 布局模式
+     */
+    get layoutMode() {
+        return this.property.layoutMode;
+    }
+    set layoutMode(value) {
+        this.property.layoutMode = value;
+    }
+    /**
+     * @description 布局信息
+     */
+    get layoutInfos() {
+        return this.property.layoutInfos;
+    }
+    set layoutInfos(info) {
+        this.property.layoutInfos = info;
+    }
+    /**
+     * @description 位置
+     */
+    get position() {
+        return this.property.position;
+    }
+    set position(value) {
+        this.property.position = value;
+    }
+    /**
+     * @description 宽度
+     */
+    get width() {
+        return this.property.width;
+    }
+    set width(value) {
+        this.property.width = value;
+    }
+    /**
+     * @description 高度
+     */
+    get height() {
+        return this.property.height;
+    }
+    set height(value) {
+        this.property.height = value;
+    }
+    /**
+     * @description 缩放
+     */
+    get scale() {
+        return this.property.scale;
+    }
+    set scale(value) {
+        this.property.scale = value;
+    }
+    /**
+     * @description 旋转（二维旋转角度）
+     */
+    get rotation() {
+        return this.property.rotation[2];
+    }
+    set rotation(value) {
+        this.property.rotation[2] = value;
+    }
+    /**
+     * @description 完整旋转（包含 x, y, z）
+     */
+    get fullRotation() {
+        return this.property.rotation;
+    }
+    set fullRotation(value) {
+        this.property.rotation = value;
+    }
+    // ==================== 子元素管理接口 ====================
+    /**
+     * @description 添加子元素
+     * @param itemId 子元素ID
+     * @returns 是否添加成功
+     */
+    addChild(itemId) {
+        if (this.property.children.includes(itemId)) {
+            return false;
+        }
+        this.property.children.push(itemId);
+        return true;
+    }
+    /**
+     * @description 批量添加子元素
+     * @param itemIds 子元素ID列表
+     */
+    addChildren(itemIds) {
+        itemIds.map(id => this.addChild(id));
+    }
+    /**
+     * @description 移除子元素
+     * @param itemId 子元素ID
+     * @returns 是否移除成功
+     */
+    removeChild(itemId) {
+        const index = this.property.children.indexOf(itemId);
+        if (index === -1) {
+            return false;
+        }
+        this.property.children.splice(index, 1);
+        return true;
+    }
+    /**
+     * @description 批量移除子元素
+     * @param itemIds 子元素ID列表
+     */
+    removeChildren(itemIds) {
+        this.property.children = this.property.children.filter(id => !itemIds.includes(id));
+    }
+    /**
+     * @description 是否包含指定子元素
+     * @param itemId 子元素ID
+     */
+    hasChild(itemId) {
+        return this.property.children.includes(itemId);
+    }
+    /**
+     * @description 清空所有子元素
+     */
+    clearChildren() {
+        this.property.children = [];
+    }
+    // ==================== 实现抽象方法 ====================
+    /**
+     * @description 转换为 FrameCreateInfo
+     * @param withParent 是否包含父节点ID
+     */
+    toCreateInfo(withParent) {
+        const createInfo = {
+            type: SDKItemType.FRAME,
+            id: this.id,
+            name: this.name,
+            property: deepClone(this.property)
+        };
+        if (withParent && this.parentId) {
+            createInfo.parentId = this.parentId;
+        }
+        // 添加扩展属性
+        const extension = this.getAllExtension();
+        if (Object.keys(extension).length > 0) {
+            createInfo.extension = extension;
+        }
+        return createInfo;
+    }
+    /**
+     * @description 克隆 SDKItem
+     */
+    clone() {
+        return new FrameItem({
+            id: generateGUID(),
+            name: this.name,
+            parentId: this.parentId,
+            duration: this.duration,
+            delay: this.delay,
+            endBehavior: this.endBehavior,
+            isLocked: this.isLocked,
+            isCoreEditable: this.isCoreEditable,
+            property: deepClone(this.property),
+            extension: this.getAllExtension()
+        });
+    }
+}
+/**
+ * @description 类型守卫：检查是否是 FrameItem
+ */
+export function isFrameItem(obj) {
+    return obj instanceof FrameItem;
+}

package/dist/sdk-item/generator-item.js

@@ -0,0 +1,188 @@
+import { SDKItemType } from './types';
+import { BaseItem } from './base-item';
+import { deepClone } from '../utils/common-utils';
+import { generateGUID } from '../shared';
+/**
+ * @description 资源生成器元素 SDKItem 类
+ * @description 支持 image 和 video 两种生成器类型
+ * @description 在 Player 中以透明 SpriteItem 形式渲染
+ * @description 支持属性扩展，可转换为 SpriteItem 或 VideoItem
+ */
+export class GeneratorItem extends BaseItem {
+    /**
+     * @description 元素类型（独立类型，不属于 spec.ItemType）
+     */
+    type = SDKItemType.GENERATOR;
+    /**
+     * @description 元素属性（包含 generatorType）
+     */
+    property;
+    constructor(options) {
+        super(options);
+        // 初始化属性（包含 generatorType）
+        this.property = {
+            position: options.property?.position ?? [0, 0],
+            rotation: options.property?.rotation ?? [0, 0, 0],
+            width: options.property?.width ?? 0,
+            height: options.property?.height ?? 0,
+            scale: options.property?.scale ?? [1, 1],
+            generatorType: options.property?.generatorType ?? 'video',
+        };
+    }
+    // ==================== generatorType 访问器 ====================
+    /**
+     * @description 生成器类型
+     */
+    get generatorType() {
+        return this.property.generatorType;
+    }
+    set generatorType(value) {
+        this.property.generatorType = value;
+    }
+    // ==================== 便捷访问器 ====================
+    /**
+     * @description 图片地址（生成器返回空）
+     */
+    get image() {
+        return '';
+    }
+    set image(_value) {
+        // 生成器不设置图片
+    }
+    /**
+     * @description 位置
+     */
+    get position() {
+        return this.property.position;
+    }
+    set position(value) {
+        this.property.position = value;
+    }
+    /**
+     * @description 宽度
+     */
+    get width() {
+        return this.property.width;
+    }
+    set width(value) {
+        this.property.width = value;
+    }
+    /**
+     * @description 高度
+     */
+    get height() {
+        return this.property.height;
+    }
+    set height(value) {
+        this.property.height = value;
+    }
+    /**
+     * @description 旋转（二维旋转角度）
+     */
+    get rotation() {
+        return this.property.rotation[2];
+    }
+    set rotation(value) {
+        this.property.rotation[2] = value;
+    }
+    /**
+     * @description 完整旋转（包含 x, y, z）
+     */
+    get fullRotation() {
+        return this.property.rotation;
+    }
+    set fullRotation(value) {
+        this.property.rotation = value;
+    }
+    /**
+     * @description 是否正在编辑关键属性
+     * @deprecated 该属性即将废弃，使用 isCoreEditable 代替
+     */
+    get keyPropertyEditing() {
+        return this.isCoreEditable;
+    }
+    set keyPropertyEditing(value) {
+        this.isCoreEditable = value;
+    }
+    // ==================== 实现抽象方法 ====================
+    /**
+     * @description 转换为 GeneratorCreateInfo
+     * @param withParent 是否包含父节点ID
+     */
+    toCreateInfo(withParent) {
+        const extension = this.getAllExtension();
+        return {
+            type: SDKItemType.GENERATOR,
+            id: this.id,
+            name: this.name,
+            parentId: withParent ? this.parentId : undefined,
+            extension: Object.keys(extension).length > 0 ? extension : undefined,
+            property: deepClone(this.property)
+        };
+    }
+    /**
+     * @description 转换为 VideoCreateInfo（用于转换为视频元素）
+     * @param videoUrl 视频资源地址
+     * @param withParent 是否包含父节点ID
+     */
+    toVideoCreateInfo(videoUrl, withParent) {
+        const extension = this.getAllExtension();
+        const property = deepClone(this.property);
+        delete property.generatorType; // 转换为视频元素时不需要 generatorType
+        return {
+            type: SDKItemType.VIDEO,
+            id: this.id, // 复用相同 ID
+            name: this.name,
+            parentId: withParent ? this.parentId : undefined,
+            extension: Object.keys(extension).length > 0 ? extension : undefined,
+            property: {
+                video: videoUrl,
+                ...property
+            }
+        };
+    }
+    /**
+     * @description 转换为 SpriteCreateInfo（用于转换为图片元素）
+     * @param imageUrl 图片资源地址
+     * @param withParent 是否包含父节点ID
+     */
+    toSpriteCreateInfo(imageUrl, withParent) {
+        const extension = this.getAllExtension();
+        const property = deepClone(this.property);
+        delete property.generatorType; // 转换为视频元素时不需要 generatorType
+        return {
+            type: SDKItemType.SPRITE,
+            id: this.id, // 复用相同 ID
+            name: this.name,
+            parentId: withParent ? this.parentId : undefined,
+            extension: Object.keys(extension).length > 0 ? extension : undefined,
+            property: {
+                image: imageUrl,
+                ...property
+            }
+        };
+    }
+    /**
+     * @description 克隆 SDKItem
+     */
+    clone() {
+        return new GeneratorItem({
+            id: generateGUID(),
+            name: this.name,
+            parentId: this.parentId,
+            duration: this.duration,
+            delay: this.delay,
+            endBehavior: this.endBehavior,
+            isLocked: this.isLocked,
+            isCoreEditable: this.isCoreEditable,
+            property: deepClone(this.property),
+            extension: this.getAllExtension()
+        });
+    }
+}
+/**
+ * @description 类型守卫：检查是否是 GeneratorItem
+ */
+export function isGeneratorItem(obj) {
+    return obj instanceof GeneratorItem;
+}

package/dist/sdk-item/group-item.js

@@ -0,0 +1,116 @@
+import { SDKItemType } from './types';
+import { generateGUID } from '../shared';
+import { BaseItem } from './base-item';
+import { deepClone } from '../utils/common-utils';
+/**
+ * @description 空节点/组 SDKItem 类
+ * @description 支持属性扩展
+ */
+export class GroupItem extends BaseItem {
+    /**
+     * @description 元素类型
+     */
+    type = SDKItemType.GROUP;
+    /**
+     * @description 元素属性
+     */
+    property;
+    constructor(options) {
+        super(options);
+        // 初始化属性
+        this.property = {
+            position: options.property?.position ?? [0, 0],
+            rotation: options.property?.rotation ?? [0, 0, 0],
+            width: options.property?.width ?? 0,
+            height: options.property?.height ?? 0,
+            children: [...options.children ?? []],
+            scale: options.property?.scale ?? [1, 1]
+        };
+    }
+    // ==================== 便捷访问器 ====================
+    /**
+     * @description 位置
+     */
+    get position() {
+        return this.property.position;
+    }
+    set position(value) {
+        this.property.position = value;
+    }
+    /**
+     * @description 大小
+     */
+    get scale() {
+        return this.property.scale;
+    }
+    set scale(value) {
+        this.property.scale = value;
+    }
+    /**
+     * @description 旋转（二维旋转角度）
+     */
+    get rotation() {
+        return this.property.rotation[2];
+    }
+    set rotation(value) {
+        this.property.rotation[2] = value;
+    }
+    /**
+     * @description 完整旋转（包含 x, y, z）
+     */
+    get fullRotation() {
+        return this.property.rotation;
+    }
+    set fullRotation(value) {
+        this.property.rotation = value;
+    }
+    /**
+     * @description 是否正在编辑关键属性
+     * @deprecated 该属性即将废弃，使用 isCoreEditable 代替
+     */
+    get keyPropertyEditing() {
+        return this.isCoreEditable;
+    }
+    set keyPropertyEditing(value) {
+        this.isCoreEditable = value;
+    }
+    // ==================== 实现抽象方法 ====================
+    /**
+     * @description 转换为 CreateInfo
+     * @param withParent 是否包含父节点ID
+     */
+    toCreateInfo(withParent) {
+        const extension = this.getAllExtension();
+        return {
+            type: this.type,
+            id: this.id,
+            name: this.name,
+            parentId: withParent ? this.parentId : undefined,
+            extension: Object.keys(extension).length > 0 ? extension : undefined,
+            property: deepClone(this.property)
+        };
+    }
+    /**
+     * @description 克隆 SDKItem
+     */
+    clone() {
+        return new GroupItem({
+            id: generateGUID(),
+            name: this.name,
+            parentId: this.parentId,
+            duration: this.duration,
+            delay: this.delay,
+            endBehavior: this.endBehavior,
+            isLocked: this.isLocked,
+            isCoreEditable: this.isCoreEditable,
+            property: deepClone(this.property),
+            extension: this.getAllExtension()
+        });
+    }
+}
+/**
+ * @description 类型守卫：检查是否是 GroupItem
+ */
+export function isGroupItem(obj) {
+    return obj instanceof GroupItem;
+}

package/dist/sdk-item/index.js

@@ -0,0 +1,39 @@
+export { SDKItemType, } from './types';
+// ==================== 类导出 ====================
+export { BaseItem, isBaseItem } from './base-item';
+export { SpriteItem, isSpriteItem } from './sprite-item';
+export { TextItem, isTextItem } from './text-item';
+export { VideoItem, isVideoItem } from './video-item';
+export { GroupItem, isGroupItem } from './group-item';
+export { GeneratorItem, isGeneratorItem } from './generator-item';
+export { EffectsItem, isEffectsItem } from './effects-item';
+export { FrameItem, isFrameItem } from './frame-item';
+export { CardItem, isCardItem } from './card-item';
+// ==================== 工厂函数 ====================
+import { spec } from '../shared';
+import { SpriteItem } from './sprite-item';
+import { GroupItem } from './group-item';
+import { TextItem } from './text-item';
+import { VideoItem } from './video-item';
+/**
+ * @description 根据 item type 创建对应的 SDKItem 实例
+ * @param type 元素类型
+ * @param options SDKItem 选项
+ * @returns SDKItem 实例
+ */
+export function createSDKItem(type, options) {
+    switch (type) {
+        case spec.ItemType.sprite:
+            return new SpriteItem(options);
+        case spec.ItemType.null:
+            return new GroupItem(options);
+        case spec.ItemType.text:
+            return new TextItem(options);
+        case spec.ItemType.video:
+            return new VideoItem(options);
+        default:
+            // 对于未实现类型的回退，创建 GroupItem
+            console.warn(`SDKItem type ${type} not implemented, falling back to GroupItem`);
+            return new GroupItem(options);
+    }
+}

package/dist/sdk-item/sprite-item.js

@@ -0,0 +1,147 @@
+import { generateGUID } from '../shared';
+import { SDKItemType } from './types';
+import { BaseItem } from './base-item';
+import { deepClone } from '../utils/common-utils';
+/**
+ * @description 图片元素 SDKItem 类
+ * @description 支持属性扩展
+ */
+export class SpriteItem extends BaseItem {
+    /**
+     * @description 元素类型
+     */
+    type = SDKItemType.SPRITE;
+    /**
+     * @description 元素属性
+     */
+    property;
+    constructor(options) {
+        super(options);
+        // 初始化属性
+        this.property = {
+            position: options.property?.position ?? [0, 0],
+            rotation: options.property?.rotation ?? [0, 0, 0],
+            width: options.property?.width ?? 0,
+            height: options.property?.height ?? 0,
+            scale: options.property?.scale ?? [1, 1],
+            image: options.property?.image ?? ''
+        };
+    }
+    // ==================== 便捷访问器 ====================
+    /**
+     * @description 图片地址
+     */
+    get image() {
+        return this.property.image;
+    }
+    set image(value) {
+        this.property.image = value;
+    }
+    /**
+     * @description 位置
+     */
+    get position() {
+        return this.property.position;
+    }
+    set position(value) {
+        this.property.position = value;
+    }
+    get width() {
+        return this.property.width;
+    }
+    set width(value) {
+        this.property.width = value;
+    }
+    get height() {
+        return this.property.height;
+    }
+    set height(value) {
+        this.property.height = value;
+    }
+    /**
+     * @description 旋转（二维旋转角度）
+     */
+    get rotation() {
+        return this.property.rotation[2];
+    }
+    set rotation(value) {
+        this.property.rotation[2] = value;
+    }
+    /**
+     * @description 完整旋转（包含 x, y, z）
+     */
+    get fullRotation() {
+        return this.property.rotation;
+    }
+    set fullRotation(value) {
+        this.property.rotation = value;
+    }
+    /**
+     * @description 是否正在编辑关键属性
+     * @deprecated 该属性即将废弃，使用 isCoreEditable 代替
+     */
+    get keyPropertyEditing() {
+        return this.isCoreEditable;
+    }
+    set keyPropertyEditing(value) {
+        this.isCoreEditable = value;
+    }
+    // ==================== 实现抽象方法 ====================
+    /**
+     * @description 转换为 CreateInfo
+     * @param withParent 是否包含父节点ID
+     */
+    toCreateInfo(withParent) {
+        const extension = this.getAllExtension();
+        const property = deepClone(this.property);
+        Object.assign(property, {
+            width: property.size[0],
+            height: property.size[1]
+        });
+        delete property.size;
+        return {
+            type: SDKItemType.SPRITE,
+            id: this.id,
+            name: this.name,
+            parentId: withParent ? this.parentId : undefined,
+            extension: Object.keys(extension).length > 0 ? extension : undefined,
+            property
+        };
+    }
+    /**
+     * @description 克隆 SDKItem
+     */
+    clone() {
+        return new SpriteItem({
+            id: generateGUID(),
+            name: this.name,
+            parentId: this.parentId,
+            duration: this.duration,
+            delay: this.delay,
+            endBehavior: this.endBehavior,
+            isLocked: this.isLocked,
+            isCoreEditable: this.isCoreEditable,
+            property: deepClone(this.property),
+            extension: this.getAllExtension()
+        });
+    }
+    /**
+     * @description 创建包含扩展属性的 CreateInfo
+     * @param withParent 是否包含父节点ID
+     * @param extraProps 额外的属性
+     */
+    toCreateInfoWithExtensions(withParent, extraProps) {
+        const createInfo = this.toCreateInfo(withParent);
+        // 添加额外属性
+        if (extraProps) {
+            Object.assign(createInfo, extraProps);
+        }
+        return createInfo;
+    }
+}
+/**
+ * @description 类型守卫：检查是否是 SpriteItem
+ */
+export function isSpriteItem(obj) {
+    return obj instanceof SpriteItem;
+}