@vvfx/sdk 0.1.19-alpha.8 → 0.2.0

package/dist/src/utils/background-manager.d.ts

@@ -0,0 +1,72 @@
+import { BackgroundGridConfig, BackgroundPreset } from './types';
+/**
+ * @description 背景管理器
+ * 负责管理画布背景的配置、渲染和跟随变换
+ */
+export declare class BackgroundManager {
+    /**
+     * @description 默认网格配置
+     */
+    static readonly DEFAULT_GRID_CONFIG: BackgroundGridConfig;
+    /**
+     * @description 背景预设配置
+     */
+    static readonly PRESETS: Record<string, BackgroundPreset>;
+    private container;
+    private config;
+    /**
+     * @description 当前背景位置（用于跟随移动）
+     */
+    private offsetX;
+    private offsetY;
+    constructor(config?: Partial<BackgroundGridConfig>);
+    /**
+     * @description 绑定容器元素
+     * @param element 画布容器元素
+     */
+    attach(element: HTMLElement): void;
+    /**
+     * @description 解绑容器元素
+     */
+    detach(): void;
+    /**
+     * @description 应用背景预设
+     * @param presetName 预设名称
+     * @param color 可选的背景色覆盖
+     */
+    applyPreset(presetName: string, color?: string): boolean;
+    /**
+     * @description 设置纯色背景
+     * @param color 颜色值
+     */
+    setColorBackground(color: string): void;
+    /**
+     * @description 设置图片背景
+     * @param url 图片 URL
+     */
+    setImageBackground(url: string): void;
+    /**
+     * @description 更新背景变换（跟随画布移动和缩放）
+     * @param shift 画布移动的偏移量
+     * @param zoom 当前缩放比例
+     */
+    updateTransform(shift: {
+        x: number;
+        y: number;
+    }, zoom: number): void;
+    /**
+     * @description 重置背景位置和大小
+     */
+    reset(): void;
+    /**
+     * @description 清除背景样式
+     */
+    private clearBackground;
+    /**
+     * @description 计算循环缩放比例
+     * zoom 在 [1, 2) 时，bgZoom = zoom
+     * zoom 在 [2, 4) 时，bgZoom = zoom / 2
+     * zoom 在 [0.5, 1) 时，bgZoom = zoom / 0.5
+     */
+    private calculateZoomCycle;
+}

package/dist/src/utils/common-utils.d.ts

@@ -0,0 +1,28 @@
+import { Vector2, Vector3 } from '../math';
+export declare function arrAdd<T>(arr: T[], item: T): void;
+export declare function isObj(item: any): item is object;
+export declare function deepEquals<T>(a: T, b: T): boolean;
+export declare function deepClone<T>(target: T): T;
+export declare function getColorByNormalizeColor(color: [number, number, number, number]): [number, number, number, number];
+export declare function getNormalizeColorByColor(color: [number, number, number, number]): [number, number, number, number];
+export declare function getTransformRatioByViewAndCamera(viewSize: Vector2, cameraPosition: Vector3, cameraFov: number, cameraNear: number, cameraFar: number, isReverse: boolean): {
+    xRatio: number;
+    yRatio: number;
+};
+export declare function assertExist<T>(item: T | undefined | null, msg?: string): asserts item is T;
+export declare function asserts(condition: any, msg?: string): asserts condition;
+/**
+ * @example
+ * Input: logger('log', ['VVFX', 'SDK'], 'xx is required');
+ * Output: [VVFX SDK] xx is required
+ */
+type Level = 'error' | 'info' | 'debug' | 'warn' | 'log';
+export declare function logger(level: Level, prefixs: string[], ...args: any[]): void;
+export declare function loadScriptAsync(src: string, attrs?: Record<string, string>): Promise<unknown>;
+export declare function downloadBlob(buffer: BlobPart | BlobPart[], filename: string, mimeType?: string): void;
+export declare function getUniqueName(name: string, names: string[]): string;
+/**
+ * 深度比较两个值是否相等
+ */
+export declare function isEqual(a: unknown, b: unknown): boolean;
+export {};

package/dist/src/utils/index.d.ts

@@ -0,0 +1,8 @@
+export * from './common-utils';
+export * from './background-manager';
+export * from './interaction-utils';
+export * from './json-data-utils';
+export * from './layout-utils';
+export * from './types';
+export * from './player-data-utils';
+export * from './page-data-utils';

package/dist/src/utils/interaction-utils.d.ts

@@ -0,0 +1,60 @@
+import { Ray, Euler, Plane, Vector2, Vector3 } from '../math';
+import type { PageDataUtils } from './page-data-utils';
+import type { CameraInteractionParam, ViewInteractionParam } from './types';
+export declare class InteractionUtils {
+    /**
+     * @description 交互平面
+     */
+    plane: Plane;
+    /**
+     * @description 交互射线
+     */
+    ray: Ray;
+    /**
+     * @description 交互状态视图信息
+     */
+    viewportParam: ViewInteractionParam;
+    /**
+     * @description 交互状态相机信息
+     */
+    cameraParam: CameraInteractionParam;
+    pageDataUtils: PageDataUtils;
+    constructor(utils: PageDataUtils);
+    refreshViewParam(): void;
+    refreshCameraParam(): void;
+    refrehCameraParamByCameraInfo(camera: any): void;
+    initInteractionPlane(position?: Vector3, rotation?: Euler): void;
+    /**
+     * @description 根据视图空间大小获取空间大小
+     * @param viewSize 视图空间大小
+     * @param isWorld 是否依赖于世界坐标系 - 世界坐标系下，以当前相机锁定平面为基准进行运算；本地坐标系下，以元素坐标系进行运算[用于决定交互平面]
+     * @param targetItem 目标元素
+     */
+    getWorldSizeByViewSize(viewSize: Vector2, isWorld?: boolean, itemId?: string): Vector3;
+    /**
+     * @description 获取 template 模式下视图与场景的缩放比 (viewportWidth / sceneWidth)
+     *              场景未就绪时回退到 1，并打印一次 warning
+     */
+    getTemplateViewScale(): number;
+    getViewSizeByPixelSize(pixelSize: Vector2): Vector2;
+    /**
+     * @description 对空间坐标进行投影
+     * @param point 空间坐标
+     * @param isGestureHandlerView 是否投影到辅助视图下 - 辅助试图与实际视图大小可能会有区别
+     */
+    projectPoint(point: Vector3): Vector2;
+    /**
+     * @description 通过屏幕坐标获取世界坐标
+     * @param point 屏幕坐标
+     * @returns 世界坐标
+     */
+    getWorldPositionByViewPoint(point: Vector2): Vector3 | undefined;
+    getNDCPositionByScreenPosition(point: Vector2): Vector2;
+    getNDCSizeByPixelSize(pixelSize: Vector2): Vector2;
+    getViewPositionWWithOutTransform(point: Vector2): Vector2;
+    getViewPositionByPixelPoint(point: Vector2): Vector2;
+    getPixelPositionByViewPoint(point: Vector2): Vector2;
+    getPixelSizeByWorldSize(worldSize: Vector3): Vector2;
+    getPixelSizeByNDCSize(ndcSize: Vector2): Vector2;
+    getPixelSizeByViewSize(viewSize: Vector2): Vector2;
+}

package/dist/src/utils/json-data-utils.d.ts

@@ -0,0 +1,165 @@
+import { Vector2, Vector3 } from '../math';
+import { spec } from '../shared';
+import { ItemJSONInfo } from './types';
+/**
+ * @description 创建 Frame 元素的内部合成场景
+ * @param frameId Frame 元素ID（用于标识）
+ * @param size 场景尺寸 [width, height]
+ * @param name 场景名称
+ * @returns Frame 内部的合成场景
+ */
+export declare function createFrameCompositionScene(frameId: string, size: spec.vec2, name: string): spec.JSONScene;
+/**
+ * @description 创建基础场景信息
+ * @param viewSize 画布大小
+ * @returns 场景信息
+ */
+export declare function getBasicScene(viewSize?: number[], name?: string): spec.JSONScene;
+export declare function createSpriteItemJSON(spriteId: string, position: Vector3, rotation: Vector3, size: Vector2, scale: Vector3, name: string, texture?: string): ItemJSONInfo;
+/**
+ * @description 创建视频生成器 Item JSON
+ * @description 以 SpriteItem 形式渲染，但设置透明颜色
+ * @description 在 content 中存储 isVideoGenerator 标记
+ */
+export declare function createVideoGeneratorItemJSON(id: string, position: Vector3, rotation: Vector3, size: Vector2, scale: Vector3, name: string): ItemJSONInfo;
+export declare function createNullItemJSON(nullId: string, name: string, position: Vector3, scale?: Vector2, rotation?: Vector3, worldSize?: Vector2): ItemJSONInfo;
+export declare function createTextItemJSON(textId: string, name: string, position: Vector3, rotation: Vector3, size: Vector2, fontInfo: spec.TextContentOptions): ItemJSONInfo;
+export declare function createVideoItemJSON(videoId: string, position: Vector3, rotation: Vector3, size: Vector2, scale: Vector3, name: string, isMuted?: boolean, transparent?: boolean, volume?: number, playbackRate?: number, texture?: string, video?: string): ItemJSONInfo;
+/**
+ * @description 创建预合成元素
+ * @param effectsId 预合成元素ID
+ * @param position 位置信息
+ * @param rotation 旋转信息
+ * @param scale 缩放信息
+ * @param name 名称
+ */
+export declare function createCompositionItemJSON(effectsId: string, position: Vector3, rotation: Vector3, scale: Vector3, name: string): {
+    item: spec.VFXItemData;
+    components: never[];
+    tracks: {
+        id: string;
+        dataType: spec.DataType;
+        children: never[];
+        clips: {
+            start: number;
+            duration: number;
+            endBehavior: spec.EndBehavior;
+            asset: {
+                id: string;
+            };
+        }[];
+    }[];
+    playableAssets: {
+        id: string;
+        dataType: spec.DataType;
+    }[];
+};
+/**
+ * @description 添加元素信息到JSON
+ * @param scene 场景信息
+ * @param itemInfo 元素信息
+ */
+export declare function addItemInfoToScene(scene: spec.JSONScene, itemInfo: ItemJSONInfo): void;
+/**
+ * @description 设置元素父节点信息
+ * @param scene 场景信息
+ * @param itemId 元素Id
+ * @param parentId 父节点Id
+ */
+export declare function setItemJSONParentId(scene: spec.JSONScene, itemId: string, parentId: string): void;
+/**
+ * @description 清理元素父节点信息
+ * @param scene 场景信息
+ * @param itemId 元素Id
+ */
+export declare function clearItemParentInfo(scene: spec.JSONScene, itemId: string): void;
+/**
+ * @description 删除元素信息
+ * @param scene 场景信息
+ * @param itemId 元素Id
+ */
+export declare function deleteItemInfoFromScene(scene: spec.JSONScene, itemId: string): spec.JSONScene | undefined;
+/**
+ * @description 从场景中移除并获取元素的完整 ItemJSONInfo
+ * @param scene 场景信息
+ * @param itemId 元素ID
+ * @returns ItemJSONInfo 或 undefined（如果元素不存在）
+ */
+export declare function removeItemInfoFromScene(scene: spec.JSONScene, itemId: string): ItemJSONInfo | undefined;
+export declare function getTextureUrlById(scene: spec.JSONScene, itemId: string): string | undefined;
+export declare function addCompositionItemByComposition(main: spec.JSONScene, inputChild: spec.JSONScene, compositionItemId: string, parentId?: string): spec.JSONScene;
+/**
+ * @description 删除预合成数据
+ * @param scene 场景数据
+ * @param itemId 预合成ID
+ * @returns 场景数据
+ */
+export declare function deleteCompositionItemFromScene(scene: spec.JSONScene, itemIds: string[]): spec.JSONScene;
+/**
+ * @description 删除合成信息
+ * @param scene 场景数据
+ * @param compositionId 合成ID
+ */
+export declare function deleteCompositionFromScene(scene: spec.JSONScene, compositionId: string): void;
+/**
+ * @description 重置元素ID - 加载时会新建guid，需要保持一致
+ * @param scene 场景数据
+ * @param idMap id名称列表
+ */
+export declare function resetSubCompositionItemId(scene: spec.JSONScene, idMap: Map<string, string>): void;
+/**
+ * @description 设置场景中元素名称
+ * @param scene 场景数据
+ * @param itemId 元素ID
+ * @param name 名称
+ */
+export declare function setJSONItemName(scene: spec.JSONScene, itemId: string, name: string): void;
+/**
+ * @description 元素变换选项
+ */
+export type MoveItemTransformOptions = {
+    position?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    size?: {
+        x: number;
+        y: number;
+    };
+    scale?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotation?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+};
+/**
+ * @description 将元素从一个合成移动到另一个合成
+ * @param scene 场景数据
+ * @param itemId 元素ID
+ * @param targetCompositionId 目标合成ID，为null时表示移动到主合成
+ * @param options 可选的位置、大小、缩放、旋转信息
+ * @returns 是否移动成功
+ */
+export declare function moveItemBetweenCompositions(scene: spec.JSONScene, itemId: string, targetCompositionId: string | null, options?: MoveItemTransformOptions): boolean;
+export declare function getCompositionIdByRefCompositionItemId(scene: spec.JSONScene, compositionItemId: string): any;
+/**
+ * @description 获取预合成元素所指向的合成数据
+ * @param scene 场景数据
+ * @param compositionItemId 预合成元素ID
+ * @returns 对应的合成数据 (CompositionData)，如果未找到则返回 undefined
+ */
+export declare function getCompositionDataByRefCompositionItemId(scene: spec.JSONScene, compositionItemId: string): spec.CompositionData | undefined;
+/**
+ * @description 提取子合成元素及其所有关联资源为独立的 JSONScene
+ * @param scene 主场景数据
+ * @param compositionItemId 预合成元素ID（子合成元素ID）
+ * @returns 独立的子合成场景 JSONScene，如果未找到则返回 undefined
+ */
+export declare function extractSubCompositionToScene(scene: spec.JSONScene, compositionItemId: string): spec.JSONScene | undefined;
+export declare function fixStandardJSON(scene: spec.JSONScene): void;

package/dist/src/utils/layout-utils.d.ts

@@ -0,0 +1,219 @@
+import { Box2 } from '../math/box2';
+import { Line2, Vector2 } from '../math';
+import type { AutoLayoutConfig, LayoutInfo } from '../types';
+import type { SDKItem, FrameItem } from '../sdk-item';
+/**
+ * @description 自动布局指示器数据
+ */
+export type AutoLayoutIndicator = {
+    frameId: string;
+    insertIndex: number;
+    insertDirection: 'before' | 'after';
+    targetSiblingId?: string;
+    line: Line2;
+    targetRow?: number;
+    targetColumn?: number;
+} | null;
+/**
+ * @description 布局位置信息
+ */
+export type LayoutPosition = {
+    row: number;
+    column: number;
+};
+/**
+ * @description 插入位置信息
+ */
+export type InsertPosition = {
+    index: number;
+    direction: 'before' | 'after';
+    siblingId?: string;
+    row: number;
+    column: number;
+    rowChange?: {
+        fromRow: number;
+        toRow: number;
+        rowBounds?: {
+            minY: number;
+            maxY: number;
+            minX: number;
+            maxX: number;
+        };
+        isRowChange: boolean;
+    };
+};
+/**
+ * @description 兄弟元素布局信息
+ */
+export type SiblingWithInfo = {
+    item: SDKItem;
+    box: Box2;
+    row: number;
+    column: number;
+    centerX: number;
+};
+/**
+ * @description 布局元素信息
+ */
+export type LayoutItem = {
+    id: string;
+    box: Box2;
+    row?: number;
+    column?: number;
+};
+/**
+ * @description 布局结果项
+ */
+export type LayoutResultItem = {
+    id: string;
+    position: [number, number];
+    row: number;
+    column: number;
+};
+/**
+ * @description 自动排布配置
+ */
+export type AutoLayoutOptions = {
+    padding?: number;
+    gap?: number;
+    config?: AutoLayoutConfig;
+};
+/**
+ * @description 自动排布结果
+ */
+export type AutoLayoutResult = {
+    items: LayoutResultItem[];
+    size: [number, number];
+};
+/**
+ * @description 全局自适应排布元素
+ */
+export type LayoutElement = {
+    id: string;
+    box: Box2;
+};
+/**
+ * @description 全局自适应排布结果
+ */
+export type GlobalAutoLayoutResult = {
+    items: {
+        id: string;
+        position: [number, number];
+    }[];
+    boundingBox: Box2;
+};
+/**
+ * @description 全局自适应排布配置
+ */
+export type GlobalAutoLayoutOptions = {
+    /**
+     * @description 元素间隔（默认10）
+     */
+    gap?: number;
+    /**
+     * @description 目标宽高比（默认1:1正方形）
+     */
+    targetAspectRatio?: number;
+    /**
+     * @description 排布模式
+     * - 'adaptive': 基于元素包围盒自适应排布（MaxRects算法，更紧凑）
+     * - 'ordered': 基于元素顺序的行列排布（保持输入顺序，流式行排布，行优先）
+     */
+    mode?: GlobalLayoutMode;
+};
+/**
+ * @description 全局自适应排布模式
+ */
+export type GlobalLayoutMode = 'adaptive' | 'ordered';
+/**
+ * @description 自动排布函数
+ * 根据元素信息中的行列数参数进行排布：
+ * - 如果元素有 row/column，则按指定行列排布
+ * - 如果元素没有 row/column，则使用 Shelf 算法自动生成行列数，再排布
+ *
+ * @param canvasBox 画布范围（Box2），min为左上角，max为右下角
+ * @param items 元素信息列表（包含 ID、Box2、可选的 row/column）
+ * @param options 可选配置（padding, gap）
+ * @returns 各元素的位置信息和整体尺寸
+ */
+export declare function autoLayout(items: LayoutItem[], options?: AutoLayoutOptions): AutoLayoutResult;
+/**
+ * @description 计算元素到目标位置的位移
+ * @param currentPosition 当前位置 [x, y]
+ * @param targetPosition 目标位置 [x, y]
+ * @returns 位移向量 [dx, dy]
+ */
+export declare function calculateDisplacement(currentPosition: [number, number], targetPosition: [number, number]): [number, number];
+/**
+ * @description 为 autoLayout 结果计算位移信息
+ * @param items 元素列表（包含当前位置）
+ * @param layoutResult autoLayout 的返回结果
+ * @returns 每个元素的位移信息
+ */
+export declare function calculateLayoutDisplacements(items: {
+    id: string;
+    currentPosition: [number, number];
+}[], layoutResult: AutoLayoutResult): {
+    id: string;
+    displacement: [number, number];
+    targetPosition: [number, number];
+}[];
+/**
+ * @description 计算自动布局指示线位置
+ * @param position 插入位置信息
+ * @param getViewBoxById 获取元素包围盒的函数
+ * @returns 主指示线
+ */
+export declare function calculateAutoLayoutIndicatorLine(position: InsertPosition, getViewBoxById: (id: string) => Box2): Line2;
+/**
+ * @description 基于鼠标位置计算布局位置（row 和 column）
+ * @param mousePoint 鼠标位置
+ * @param allItems 所有子元素
+ * @param getViewBoxById 获取元素包围盒的函数
+ * @param getLayoutInfo 获取元素布局信息的函数
+ * @param excludeItemId 需要排除的元素ID（被拖拽的元素）
+ * @returns 布局位置信息 { row: number, column: number }
+ */
+export declare function calculateAutoLayoutPositionByMouse(mousePoint: Vector2, allItems: SDKItem[], getViewBoxById: (id: string) => Box2, getLayoutInfo: (item: SDKItem) => LayoutInfo | undefined, excludeItemId: string): LayoutPosition | null;
+/**
+ * @description 基于鼠标位置计算插入位置（用于显示指示器）
+ * @param mousePoint 鼠标位置
+ * @param allItems 所有子元素
+ * @param excludeItemId 需要排除的元素ID（被拖拽的元素）
+ * @param parent 父画板
+ * @param originalRow 原始行号
+ * @param getSelectedItemsBox 获取选中项包围盒的函数
+ * @returns 插入位置信息和计算出的行列位置
+ */
+export declare function calculateInsertPositionFromLayout(mousePoint: Vector2, allItems: SDKItem[], excludeItemId: string, parent: FrameItem, originalRow: number, getViewBoxById: (id: string) => Box2, getSelectedItemsBox: () => Box2): InsertPosition;
+/**
+ * @description 更新元素的 layoutInfo
+ * @param item 要更新的元素
+ * @param parent 父画板
+ * @param layoutPosition 新的布局位置
+ */
+export declare function updateItemLayoutInfo(item: SDKItem, parent: FrameItem, layoutPosition: LayoutPosition): void;
+/**
+ * @description 全局自适应排布
+ * 支持两种模式：
+ * 1. 'adaptive'（默认）: 基于元素包围盒自适应排布（MaxRects算法，更紧凑）
+ * 2. 'ordered': 基于元素顺序的流式行排布（保持输入顺序，每行尽可能多放元素）
+ *
+ * @param elements 元素列表（包含ID和包围盒）
+ * @param options 配置选项
+ * @returns 各元素位置和整体包围盒
+ */
+export declare function globalAutoLayout(elements: LayoutElement[], options?: GlobalAutoLayoutOptions): GlobalAutoLayoutResult;
+/**
+ * @description 调整其他元素的行列信息
+ * 当被拖拽元素移动到新位置时，需要调整其他受影响的元素：
+ * 1. 同行内移动：原位置到新位置之间的元素需要相应调整列号
+ * 2. 跨行移动：原行中后面的元素前移，目标行中后面的元素后移
+ * @param parent 父画板
+ * @param draggedItemId 被拖拽的元素ID
+ * @param fromRow 原始行号
+ * @param fromColumn 原始列号
+ * @param toRow 目标行号
+ * @param toColumn 目标列号
+ */
+export declare function adjustOtherElementsLayoutInfo(parent: FrameItem, draggedItemId: string, fromRow: number, fromColumn: number, toRow: number, toColumn: number, getSDKItem: (id: string) => SDKItem | undefined): void;