@vvfx/sdk 0.1.19-alpha.12 → 0.1.19-alpha.13

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _galacean_effects from '@galacean/effects';
-import { math, spec, Player } from '@galacean/effects';
+import { math, spec, Player, EventEmitter, Composition, VFXItem, Constructor, Component } from '@galacean/effects';
 export { generateGUID, spec } from '@galacean/effects';
 import { Point } from '@pixi/constants';
 
@@ -290,6 +290,108 @@ declare class Box2 {
     rotate(angle: number, center?: Vector2): this;
 }
 
+declare class Quaternion extends math.Quaternion {
+}
+
+declare class Vector3 extends math.Vector3 {
+    clone(): Vector3;
+    /**
+     * 由空间变换矩阵保存三维分量
+     * @param {Matrix4} m 四维矩阵
+     * @param {number} index 下标
+     * @returns {Vec3} 指定三维分量
+     */
+    setFromMatrixColumn(m: Matrix4, index: number): this;
+    applyEuler(euler: Euler, _out?: Vector3): this;
+    /**
+     * 三维点根据四元数绕点的旋转
+     * @param {Quaternion} q 四元数
+     * @param {Vec3} [center=new Vec3()] 旋转中心
+     * @returns {Vec3} 旋转结果
+     */
+    applyQuaternion(q: Quaternion, center?: Vector3): this;
+    /**
+     * 由空间变换矩阵保存三维偏移值
+     * @param {Matrix4} m 四维矩阵
+     * @returns {Vec3} 偏移值
+     */
+    setFromMatrixPosition(m: Matrix4): this;
+    applyMatrix(matrix: Matrix4, center?: Vector3): this;
+}
+
+declare class Matrix4 extends math.Matrix4 {
+    /**
+     * 通过数组创建矩阵
+     * @param array - 数组
+     * @param [offset=0] - 起始偏移值
+     * @returns 矩阵
+     */
+    static fromArray(array: math.Matrix4DataType, offset?: number): Matrix4;
+    clone(): Matrix4;
+    compose(translation: Vector3, rotation: Quaternion, scale: Vector3, anchor?: math.Vector3): this;
+    /**
+     * 导出四维矩阵[三维空间变换矩阵]旋转部分
+     * @param {Matrix4} m 四维矩阵
+     * @returns {Matrix4} 导出结果
+     */
+    extractRotation(m: Matrix4): this;
+    /**
+     * 由欧拉角设置四维矩阵
+     * @param {Euler} euler 欧拉角
+     * @returns {Matrix4} 四维矩阵
+     */
+    makeRotationFromEuler(euler: Euler): this;
+    setPosition(position: Vector3): this;
+}
+
+declare class Euler extends math.Euler {
+    constructor(x?: number, y?: number, z?: number, order?: math.EulerOrder);
+    getInvertMatrixByEuler(): Matrix4;
+    /**
+     * 欧拉角保存于三维向量(应用于计算)
+     * @param {Vector3} [optionalResult] 目标保存对象
+     * @returns {Vector3} 保存结果
+     */
+    toDegreeVector3(optionalResult?: Vector3): Vector3;
+    /**
+     * 由角度三维向量构建欧拉角
+     * @param {Vector3} v 角度三维向量
+     * @param {EulerOrder} [order] 欧拉角顺序，默认为ZYX
+     * @returns {Euler} 欧拉角
+     */
+    setFromDegreeVector3(degree: Vector3, order?: math.EulerOrder): this;
+}
+
+declare class Plane {
+    distance: number;
+    normal: Vector3;
+    constructor(distance?: number, normal?: Vector3);
+    static set(distance: number, normal: Vector3): Plane;
+    set(distance: number, normal: Vector3): this;
+    static copy(target: Plane): Plane;
+    copy(target: Plane): this;
+    static setFromNormalAndCoplanarPoint(point: Vector3, normal: Vector3): Plane;
+    setFromNormalAndCoplanarPoint(point: Vector3, normal: Vector3): this;
+    clone(): Plane;
+    distanceToPoint(point: Vector3): number;
+}
+
+declare class Ray extends math.Ray {
+    origin: Vector3;
+    direction: Vector3;
+    constructor(origin?: Vector3, direction?: Vector3);
+    clone(): Ray;
+    rayCastPlane(plane: Plane, _target: Vector3): number;
+    at(t: number): Vector3;
+    /**
+     * 射线到平面的距离
+     * 当两个向量都是单位向量的时候，从a投影到b的距离等于从b投影到a的距离
+     * @param plane 平面
+     * @returns 射线到平面的距离
+     */
+    distanceToPlane(plane: Plane): number;
+}
+
 type SizeAdaptDirection = 'x' | 'y';
 
 declare const MEDIA_TYPE: {
@@ -2154,6 +2256,12 @@ type EffectsCreateInfo = {
      */
     extension?: Record<string, any>;
 };
+type AsyncSpriteCreateInfo = SpriteCreateInfo & {
+    textureId: string;
+};
+type AsyncVideoCreateInfo = VideoCreateInfo & {
+    textureId: string;
+};
 /**
  * @description Frame 画板元素创建信息
  */
@@ -2297,6 +2405,857 @@ declare class UndoRedo {
     clear(): void;
 }
 
+declare function arrAdd<T>(arr: T[], item: T): void;
+declare function isObj(item: any): item is object;
+declare function deepEquals<T>(a: T, b: T): boolean;
+declare function deepClone<T>(target: T): T;
+declare function getColorByNormalizeColor(color: [number, number, number, number]): [number, number, number, number];
+declare function getNormalizeColorByColor(color: [number, number, number, number]): [number, number, number, number];
+declare function getTransformRatioByViewAndCamera(viewSize: Vector2, cameraPosition: Vector3, cameraFov: number, cameraNear: number, cameraFar: number, isReverse: boolean): {
+    xRatio: number;
+    yRatio: number;
+};
+declare function assertExist<T>(item: T | undefined | null, msg?: string): asserts item is T;
+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';
+declare function logger(level: Level, prefixs: string[], ...args: any[]): void;
+declare function loadScriptAsync(src: string, attrs?: Record<string, string>): Promise<unknown>;
+declare function downloadBlob(buffer: BlobPart | BlobPart[], filename: string, mimeType?: string): void;
+declare function getUniqueName(name: string, names: string[]): string;
+/**
+ * 深度比较两个值是否相等
+ */
+declare function isEqual(a: unknown, b: unknown): boolean;
+
+/**
+ * @description 交互状态视图信息
+ */
+type ViewInteractionParam = {
+    /**
+     * @description 视口宽度 - 红框区域像素大小
+     */
+    width: number;
+    /**
+     * @description 视口高度 - 红框区域像素大小
+     */
+    height: number;
+    /**
+     * @description 视口缩放比例
+     */
+    scale: number;
+    /**
+     * @description 视口位移信息
+     */
+    translation: Vector2;
+    /**
+     * @description 标尺宽度
+     */
+    rulerWidth: number;
+};
+/**
+ * @description 交互状态相机信息
+ */
+type CameraInteractionParam = {
+    /**
+     * @description 位置
+     */
+    position: Vector3;
+    /**
+     * @description 旋转角度
+     */
+    rotation: Vector3;
+    /**
+     * @description 视野初始中心
+     */
+    focusPosition: Vector3;
+    /**
+     * @description 视野初始角度
+     */
+    focusRotation: Vector3;
+    /**
+     * @description 投影矩阵
+     */
+    viewProjectionMatrix: Matrix4;
+    /**
+     * @description 逆投影矩阵
+     */
+    inverseViewProjectionMatrix: Matrix4;
+};
+declare const SafeConstraint: {
+    topAdsorption: string;
+    leftAdsorption: string;
+    rightAdsorption: string;
+    bottomAdsorption: string;
+    centerAdsorption: string;
+    bottomCenterAdsorption: string;
+};
+type ItemJSONInfo = {
+    item: spec.VFXItemData;
+    components: spec.ComponentData[];
+    tracks: any[];
+    playableAssets: any[];
+};
+type AlignType = 'left' | 'right' | 'horizontal-center' | 'top' | 'bottom' | 'vertical-center';
+type DistributeType = 'vertical-spacing' | 'horizontal-spacing';
+/**
+ * @description 背景类型预设配置
+ */
+type BackgroundPreset = {
+    /**
+     * @description 背景颜色
+     */
+    color?: string;
+    /**
+     * @description 背景图片/渐变
+     */
+    image?: string;
+    /**
+     * @description 背景重复方式
+     */
+    repeat?: string;
+    /**
+     * @description 背景位置
+     */
+    position?: string;
+    /**
+     * @description 背景大小
+     */
+    size?: string;
+};
+/**
+ * @description 背景网格配置
+ */
+type BackgroundGridConfig = {
+    /**
+     * @description 基础网格大小（像素）
+     */
+    baseSize: number;
+    /**
+     * @description 缩放循环阈值（默认 2，即 2x 时重置）
+     */
+    zoomCycle: number;
+    /**
+     * @description 最小网格大小限制
+     */
+    minSize: number;
+};
+
+/**
+ * @description 背景管理器
+ * 负责管理画布背景的配置、渲染和跟随变换
+ */
+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;
+}
+
+/**
+ * @description 创建 Frame 元素的内部合成场景
+ * @param frameId Frame 元素ID（用于标识）
+ * @param size 场景尺寸 [width, height]
+ * @param name 场景名称
+ * @returns Frame 内部的合成场景
+ */
+declare function createFrameCompositionScene(frameId: string, size: spec.vec2, name: string): spec.JSONScene;
+/**
+ * @description 创建基础场景信息
+ * @param viewSize 画布大小
+ * @returns 场景信息
+ */
+declare function getBasicScene(viewSize?: number[], name?: string): spec.JSONScene;
+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 标记
+ */
+declare function createVideoGeneratorItemJSON(id: string, position: Vector3, rotation: Vector3, size: Vector2, scale: Vector3, name: string): ItemJSONInfo;
+declare function createNullItemJSON(nullId: string, name: string, position: Vector3, scale?: Vector2, rotation?: Vector3, worldSize?: Vector2): ItemJSONInfo;
+declare function createTextItemJSON(textId: string, name: string, position: Vector3, rotation: Vector3, size: Vector2, fontInfo: spec.TextContentOptions): ItemJSONInfo;
+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 名称
+ */
+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 元素信息
+ */
+declare function addItemInfoToScene(scene: spec.JSONScene, itemInfo: ItemJSONInfo): void;
+/**
+ * @description 设置元素父节点信息
+ * @param scene 场景信息
+ * @param itemId 元素Id
+ * @param parentId 父节点Id
+ */
+declare function setItemJSONParentId(scene: spec.JSONScene, itemId: string, parentId: string): void;
+/**
+ * @description 清理元素父节点信息
+ * @param scene 场景信息
+ * @param itemId 元素Id
+ */
+declare function clearItemParentInfo(scene: spec.JSONScene, itemId: string): void;
+/**
+ * @description 删除元素信息
+ * @param scene 场景信息
+ * @param itemId 元素Id
+ */
+declare function deleteItemInfoFromScene(scene: spec.JSONScene, itemId: string): spec.JSONScene | undefined;
+/**
+ * @description 从场景中移除并获取元素的完整 ItemJSONInfo
+ * @param scene 场景信息
+ * @param itemId 元素ID
+ * @returns ItemJSONInfo 或 undefined（如果元素不存在）
+ */
+declare function removeItemInfoFromScene(scene: spec.JSONScene, itemId: string): ItemJSONInfo | undefined;
+declare function getTextureUrlById(scene: spec.JSONScene, itemId: string): string | undefined;
+declare function addCompositionItemByComposition(main: spec.JSONScene, inputChild: spec.JSONScene, compositionItemId: string, parentId?: string): spec.JSONScene;
+/**
+ * @description 删除预合成数据
+ * @param scene 场景数据
+ * @param itemId 预合成ID
+ * @returns 场景数据
+ */
+declare function deleteCompositionItemFromScene(scene: spec.JSONScene, itemIds: string[]): spec.JSONScene;
+/**
+ * @description 删除合成信息
+ * @param scene 场景数据
+ * @param compositionId 合成ID
+ */
+declare function deleteCompositionFromScene(scene: spec.JSONScene, compositionId: string): void;
+/**
+ * @description 重置元素ID - 加载时会新建guid，需要保持一致
+ * @param scene 场景数据
+ * @param idMap id名称列表
+ */
+declare function resetSubCompositionItemId(scene: spec.JSONScene, idMap: Map<string, string>): void;
+/**
+ * @description 设置场景中元素名称
+ * @param scene 场景数据
+ * @param itemId 元素ID
+ * @param name 名称
+ */
+declare function setJSONItemName(scene: spec.JSONScene, itemId: string, name: string): void;
+/**
+ * @description 元素变换选项
+ */
+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 是否移动成功
+ */
+declare function moveItemBetweenCompositions(scene: spec.JSONScene, itemId: string, targetCompositionId: string | null, options?: MoveItemTransformOptions): boolean;
+declare function getCompositionIdByRefCompositionItemId(scene: spec.JSONScene, compositionItemId: string): any;
+/**
+ * @description 获取预合成元素所指向的合成数据
+ * @param scene 场景数据
+ * @param compositionItemId 预合成元素ID
+ * @returns 对应的合成数据 (CompositionData)，如果未找到则返回 undefined
+ */
+declare function getCompositionDataByRefCompositionItemId(scene: spec.JSONScene, compositionItemId: string): spec.CompositionData | undefined;
+/**
+ * @description 提取子合成元素及其所有关联资源为独立的 JSONScene
+ * @param scene 主场景数据
+ * @param compositionItemId 预合成元素ID（子合成元素ID）
+ * @returns 独立的子合成场景 JSONScene，如果未找到则返回 undefined
+ */
+declare function extractSubCompositionToScene(scene: spec.JSONScene, compositionItemId: string): spec.JSONScene | undefined;
+declare function fixStandardJSON(scene: spec.JSONScene): void;
+
+declare class PageDataUtils {
+    private sdk;
+    player: Player;
+    container: HTMLElement;
+    emitter: EventEmitter<SDKEvents>;
+    interactionUtils: InteractionUtils;
+    constructor(player: Player, container: HTMLElement, emitter: EventEmitter<SDKEvents>, sdk: SDK);
+    init(): void;
+    getPageData(): PageData | undefined;
+    getCurrentComposition(): Composition | undefined;
+    isItemSelected(id: string): boolean;
+    getItemEditEnable(id: string): boolean;
+    getItemShow(id: string): boolean;
+    addSelectedItems(ids: string[]): void;
+    removeSelectedItems(ids: string[]): void;
+    clearSelectedItems(emitChange?: boolean): void;
+    getSelectedItems(): SDKItem[];
+    addPreSelectedItem(id: string): void;
+    clearPreSelectedItem(): void;
+    getPreSelectedItem(): SDKItem | undefined;
+    addLoadingItems(ids: string[]): void;
+    removeLoadingItems(ids: string[]): void;
+    clearLoadingItems(): void;
+    getLoadingItems(): SDKItem[];
+    getSDKItem(id: string): SDKItem | undefined;
+    getPlayerSizeByParent(parentSize: [number, number], sceneSize: [number, number]): readonly [number, number];
+    loadScene(id: number): Promise<void>;
+    refreshPageTime(number: number): void;
+    pageZoom(shift: number, center?: Vector2, ignoreClamp?: boolean): void;
+    setPageZoom(targetZoom: number, center?: Vector2, ignoreClamp?: boolean): void;
+    refreshInteractionParam(): void;
+    pageMove(shift: Vector2): void;
+    setPageMove(targetTranslation: Vector2): void;
+    /**
+     * @description 设置当前相机视图矩阵
+     * @param matrix 视图矩阵
+     */
+    setCurrenCameraViewportMatrix(matrix: Matrix4): void;
+    rotateItem(id: string, shift: Vector3, ignoreEvent?: boolean): void;
+    moveItem(id: string, shift: Vector3, ignoreEvent?: boolean): void;
+    scaleItem(id: string, shift: Vector3, ignoreEvent?: boolean): void;
+    scaleTextItemWidth(id: string, scalar: number): void;
+    scaleTextItem(id: string, scalar: number): void;
+    getItemTransformById(id: string): {
+        matrix: Matrix4;
+        parentMatrix: Matrix4;
+    };
+    addSDKItemsByItems(result: SDKItem[], playerItems: VFXItem[], id?: string): void;
+    getFilterItemIds(): (string | undefined)[];
+    createSDKItemByPlayerItem(playerItem: VFXItem, parentId?: string): SDKItem;
+    /**
+     * @description 根据 spec.ItemType 创建 SDKItem（内部辅助方法）
+     * @param itemType spec.ItemType
+     * @param baseOptions 基础选项
+     * @param property 属性
+     * @returns SDKItem 实例
+     */
+    private createSDKItemBySpecType;
+    getViewBoxById(id: string): Box2;
+    getItemViewAnchor(id: string): Vector2 | undefined;
+    getChildrenPlayerItems(item?: VFXItem): VFXItem[];
+    getChildrenSceneItemIds(id: string, scene: spec.JSONScene): string[];
+    getViewBoxByPlayerItem(item: VFXItem, childrenItem: VFXItem[]): Box2;
+    getViewportLeftTopPosition(): Vector2;
+    getViewportByViewPoint(point: Vector2): Vector2;
+    /**
+     * @description 设置元素属性（支持单个元素的单/多属性设置）
+     * @param param 设置参数，支持两种场景：
+     *   1. 单个元素单个属性: { itemId, type, propertyName, propertyValue }
+     *   2. 单个元素多个属性: { itemId, type, property }
+     */
+    setItemProperty<T extends SDKItemType>(param: SetItemPropertyParam<T>): Promise<void>;
+    /**
+     * @description 场景 1: 设置单个元素的单个属性
+     */
+    private setSingleItemSingleProperty;
+    /**
+     * @description 场景 2: 设置单个元素的多个属性
+     */
+    private setSingleItemMultipleProperties;
+    /**
+     * @description 更新 PlayerItem 的属性
+     * @param itemId 元素ID
+     * @param propertyName 属性名
+     * @param propertyValue 属性值
+     */
+    private updatePlayerItemProperty;
+    /**
+     * @description 更新 PlayerItem 的基础属性
+     */
+    private updatePlayerItemBaseProperty;
+    /**
+     * @description 更新 PlayerItem 的 Property 属性
+     */
+    private updatePlayerItemPropertyAttribute;
+    /**
+     * @description 更新 JSON Scene 中 Item 的属性
+     * @param itemId 元素ID
+     * @param propertyName 属性名
+     * @param propertyValue 属性值
+     */
+    private updateJSONItemProperty;
+    /**
+     * @description 更新 Scene 中 Item 的基础属性
+     */
+    private updateSceneItemBaseProperty;
+    /**
+     * @description 更新 Scene 中 Item 的 Property 属性
+     */
+    updateSceneItemPropertyAttribute(scene: spec.JSONScene, itemId: string, propertyName: string, propertyValue: any): void;
+    setSpriteSize(id: string, size: [number, number]): void;
+    transformSceneItem(id: string, property: 'position' | 'rotation' | 'scale', shift: [number, number, number]): void;
+    refreshSDKItem(id: string): void;
+    /**
+     * @description 更新已有 SDKItem 的属性（而不是替换整个对象）
+     * @param sdkItem 需要更新的 SDKItem
+     * @param playerItem 对应的 Player VFXItem
+     */
+    updateSDKItemFromPlayerItem(sdkItem: SDKItem, playerItem: VFXItem): void;
+    getPlayerItemById(id?: string): VFXItem | undefined;
+    getPixelSizeByWorldSize(worldSize: spec.vec3, item: VFXItem): spec.vec2;
+    getWorldSizeByPixelSize(pixelSize: spec.vec2): spec.vec2;
+    /**
+     * @private
+     * @description 获取当前激活的场景
+     */
+    private getActiveTargetScene;
+    /**
+     * @private
+     * @description 刷新场景和页面数据
+     */
+    private refreshSceneAndPageData;
+    addSpriteItem(spriteInfo: AsyncSpriteCreateInfo, asyncMode: true, targetScene?: spec.JSONScene): Promise<string>;
+    addSpriteItem(spriteInfo: SpriteCreateInfo, asyncMode: false, targetScene?: spec.JSONScene): Promise<string>;
+    addGroupItem(groupInfo: GroupCreateInfo, targetScene?: spec.JSONScene): string | undefined;
+    addTextItem(textInfo: TextCreateInfo, targetScene?: spec.JSONScene): Promise<string | undefined>;
+    addVideoItem(videoInfo: AsyncVideoCreateInfo, asyncMode: true, targetScene?: spec.JSONScene): Promise<string>;
+    addVideoItem(videoInfo: VideoCreateInfo, asyncMode: false, targetScene?: spec.JSONScene): Promise<string>;
+    /**
+     * @description 添加生成器元素
+     * @param createInfo 生成器创建信息
+     * @param targetScene 目标场景
+     * @returns 元素ID
+     */
+    addGeneratorItem(createInfo: GeneratorCreateInfo, targetScene?: spec.JSONScene): string;
+    /**
+     * @description 设置生成器资源，将生成器转换为对应的元素（SpriteItem 或 VideoItem）
+     * @param id 生成器元素ID
+     * @param resourceUrl 资源地址
+     * @returns 新的元素ID
+     */
+    setGeneratorResource(id: string, resourceUrl: string): Promise<string>;
+    /**
+     * @description 将视频生成器转换为视频元素
+     * @param id 视频生成器元素ID
+     * @param videoUrl 视频资源地址
+     * @returns 新的视频元素ID
+     * @deprecated 使用 setGeneratorResource 替代
+     */
+    convertVideoGeneratorToVideo(id: string, videoUrl: string): Promise<string>;
+    /**
+     * @description 删除元素
+     * @param id 元素id
+     */
+    deleteItem(id: string): void;
+    setItemParent(id: string, parentId: string, targetScene?: spec.JSONScene): void;
+    deleteItemParent(id: string, parentId: string, targetScene?: spec.JSONScene): void;
+    /**
+     * @description 将元素移动到 Frame 中
+     * @param itemIds 要移动的元素ID列表
+     * @param frameId 目标 Frame ID
+     */
+    moveItemsToFrame(itemIds: string[], frameId: string): void;
+    /**
+     * @description 移动单个元素到 Frame（仅 JSON 层，Player 层在 reLoad 后重建）
+     * @private
+     */
+    private moveSingleJSONItemToFrame;
+    /**
+     * @description 移动单个元素到 Frame（保持 parentId）
+     * @param itemId 元素ID
+     * @param frameItem 目标 Frame
+     * @param options 变换选项
+     * @param mainScene 主场景
+     * @param parentId 要保持的父节点ID
+     * @private
+     */
+    private moveSingleJSONItemToFrameWithParent;
+    /**
+     * @description 收集元素及其所有子元素（递归处理嵌套组）
+     * @param itemIds 初始元素ID列表
+     * @returns 包含所有子元素的ID列表
+     * @private
+     */
+    private collectItemsWithChildren;
+    private moveSinglePlayerItemToFrame;
+    /**
+     * @description 将元素从 Frame 中移出到主场景
+     * @param itemIds 要移动的元素ID列表
+     * @param frameId 源 Frame ID（可选，如果不传则从第一个元素的 parentId 推断）
+     */
+    moveItemsOutOfFrame(itemIds: string[], frameId?: string): void;
+    /**
+     * @description 移动单个元素从 Frame 到主场景（仅 JSON 层）
+     * @private
+     */
+    private moveSingleJSONItemOutOfFrame;
+    private moveSinglePlayerItemOutOfFrame;
+    setItemName(id: string, name: string, targetScene?: spec.JSONScene): void;
+    get undoRedo(): UndoRedo;
+    saveUndoRedoOldData(): void;
+    pushUndoRedoData(): void;
+    getItemCreateInfo(id: string, withParent?: boolean): GroupCreateInfo | SpriteCreateInfo | TextCreateInfo | VideoCreateInfo | GeneratorCreateInfo | EffectsCreateInfo | FrameCreateInfo | undefined;
+    getChildrenIds(id: string): string[];
+    createScreenShotSceneByIds(idInfo: string | string[]): any;
+    createSceneByCreateInfos(createInfos: ItemCreateInfo[], sceneSize?: spec.vec2, name?: string, scenePosition?: spec.vec2): spec.JSONScene;
+    /**
+     * @description 更新元素在图片中的顺序（仅在同级元素之间）
+     * @param id 元素ID
+     * @param action 排序操作类型
+     */
+    updateItemOrder(id: string, action: ItemOrderAction): void;
+    private isPluginItem;
+    private refreshItemRenderOrder;
+    /**
+     * @description 根据 composition.items 的顺序重新排列 pageData.items
+     * @param composition 当前场景
+     */
+    private syncPageDataItemsOrder;
+    getViewProperty(id?: number): ViewProperty | undefined;
+    viewportFit(shiftParam?: ViewportFitShiftParam, box?: Box2): void;
+    getItemBoxById(idInfo: string): Box2;
+    getItemBoxById(idInfo: string[]): Box2[];
+    setItemFontFamily(id: string, fontFamilyName: string, url: string): Promise<void>;
+    changeItemPropertyByCreateInfo(itemCreateInfo: ItemCreateInfo | ItemCreateInfo[]): void;
+    getViewBoxByBox(box: Box2): Box2;
+    playVideoItem(id?: string): void;
+    pauseVideoItem(id?: string): void;
+    playEffectsItem(id?: string): void;
+    pauseEffectsItem(id?: string): void;
+    setEffectsResource(id: string, effects: string): void;
+    /**
+     * @description 根据元素创建信息获取包围盒
+     * @param createInfo 元素创建信息
+     * @returns 包围盒
+     */
+    getBoundingBoxByCreateInfo(createInfo: ItemCreateInfo): Box2;
+    /**
+     * @description 根据元素创建信息组获取包围盒
+     * @param createInfos 元素创建信息组
+     * @returns 包围盒
+     */
+    getBoundingBoxByCreateInfos(createInfos: ItemCreateInfo[]): Box2;
+    getVideoItemPlayTime(id: string): number;
+    setVideoItemPlayTime(id: string, time: number): void;
+    getEffectsItemPlayTime(id: string): number | undefined;
+    setEffectsItemPlayTime(id: string, time: number): void;
+    getPixelPositionByViewPosition(viewPosition: Vector2): Vector2;
+    getItemParentScale(id: string): Vector3;
+    getJSONItem(id: string): spec.VFXItemData | undefined;
+    getJSONComponent(id: string): spec.ComponentData | undefined;
+    getTextOriginSize(id: string): {
+        size: spec.vec2;
+        isPublishScene: boolean;
+    };
+    asyncAddItemByCreateInfos(createInfos: ItemCreateInfo[]): Promise<string[]>;
+    addItemByCreateInfos(createInfos: ItemCreateInfo[]): Promise<string[]>;
+    addEffectsItem(createInfo: EffectsCreateInfo, targetScene?: spec.JSONScene): Promise<string | undefined>;
+    /**
+     * @description 添加画板元素
+     * @param createInfo 画板创建信息
+     * @param targetScene 目标场景
+     * @returns 元素ID
+     */
+    addFrameItem(createInfo: FrameCreateInfo, targetScene?: spec.JSONScene): Promise<string>;
+    makeItemAlign(type: AlignType, ids?: string[]): void;
+    makeItemDistribute(type: DistributeType, ids?: string[]): void;
+    setItemLockState(id: string, state: boolean): void;
+    getItemLockState(id: string): boolean;
+    /**
+     * @description 计算元素在新父节点下保持世界绝对 transform 不变时所需的局部 transform
+     * @param itemId 要移动的元素 ID
+     * @param targetParentVFXItem 目标父 VFXItem（移入 Frame 时为 compositionItem，移出 Frame 时为 composition.rootItem）
+     */
+    getItemTransformUnderParent(itemId: string, targetParentVFXItem: VFXItem): MoveItemTransformOptions | undefined;
+    /**
+     * @description 修改画板元素大小
+     * @param id 元素id
+     * @param size 目标大小 [width, height]
+     * @param translation 位置偏移补偿（可选，用于保持拖拽角点固定）
+     */
+    resizeFrameItem(id: string, size: spec.vec2, translation?: Vector3): void;
+    /**
+     * @description 对 FrameItem 执行自动布局（Shelf 算法）
+     * @param frameId Frame 元素 ID
+     */
+    applyFrameAutoLayout(frameId: string): void;
+    /**
+     * @description 将 layout-utils 的 AutoLayoutResult 结果记录到 layoutInfos
+     * @param frameId Frame 元素 ID
+     * @param layoutResult autoLayout 函数返回的结果
+     */
+    private recordLayoutInfosFromAutoLayoutResult;
+    refreshFrameChildren(id: string): void;
+}
+
+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;
+    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;
+}
+
+/**
+ * @description 布局元素信息
+ */
+type LayoutItem = {
+    /**
+     * @description 元素ID
+     */
+    id: string;
+    /**
+     * @description 元素包围盒（用于获取宽高）
+     */
+    box: Box2;
+    /**
+     * @description 所在行号（可选）
+     */
+    row?: number;
+    /**
+     * @description 所在列号（可选）
+     */
+    column?: number;
+};
+/**
+ * @description 布局结果项
+ */
+type LayoutResultItem = {
+    /**
+     * @description 元素ID
+     */
+    id: string;
+    /**
+     * @description 目标位置（相对画布左上角的像素坐标）
+     */
+    position: [number, number];
+    /**
+     * @description 实际分配的行号
+     */
+    row: number;
+    /**
+     * @description 实际分配的列号
+     */
+    column: number;
+};
+/**
+ * @description 自动排布配置
+ */
+type AutoLayoutOptions = {
+    /**
+     * @description 边距（默认20）
+     */
+    padding?: number;
+    /**
+     * @description 元素间隔（默认5）
+     */
+    gap?: number;
+    /**
+     * @description 自动布局高级配置（可选）
+     */
+    config?: AutoLayoutConfig;
+};
+/**
+ * @description 自动排布结果
+ */
+type AutoLayoutResult = {
+    /**
+     * @description 各元素的位置信息
+     */
+    items: LayoutResultItem[];
+    /**
+     * @description 排布后的整体尺寸 [width, height]
+     */
+    size: [number, number];
+};
+/**
+ * @description 自动排布函数
+ * 根据元素信息中的行列数参数进行排布：
+ * - 如果元素有 row/column，则按指定行列排布
+ * - 如果元素没有 row/column，则使用 Shelf 算法自动生成行列数，再排布
+ *
+ * @param canvasBox 画布范围（Box2），min为左上角，max为右下角
+ * @param items 元素信息列表（包含 ID、Box2、可选的 row/column）
+ * @param options 可选配置（padding, gap）
+ * @returns 各元素的位置信息和整体尺寸
+ */
+declare function autoLayout(items: LayoutItem[], options?: AutoLayoutOptions): AutoLayoutResult;
+/**
+ * @description 计算元素到目标位置的位移
+ * @param currentPosition 当前位置 [x, y]
+ * @param targetPosition 目标位置 [x, y]
+ * @returns 位移向量 [dx, dy]
+ */
+declare function calculateDisplacement(currentPosition: [number, number], targetPosition: [number, number]): [number, number];
+/**
+ * @description 为 autoLayout 结果计算位移信息
+ * @param items 元素列表（包含当前位置）
+ * @param layoutResult autoLayout 的返回结果
+ * @returns 每个元素的位移信息
+ */
+declare function calculateLayoutDisplacements(items: {
+    id: string;
+    currentPosition: [number, number];
+}[], layoutResult: AutoLayoutResult): {
+    id: string;
+    displacement: [number, number];
+    targetPosition: [number, number];
+}[];
+
+declare class DefaultVFXItems {
+    static createEmpty(composition: Composition, parent?: null, name?: string): VFXItem;
+    static createSprite(composition: Composition, parent?: null, name?: string): VFXItem;
+    static createText(composition: Composition, parent?: null, name?: string): VFXItem;
+    static createVideo(composition: Composition, parent?: null, name?: string): VFXItem;
+    static createEffects(composition: Composition, effects: string | spec.JSONScene, parent?: null, urlname?: string): Promise<VFXItem>;
+}
+declare class VFXItemFactory {
+    static createVFXItem(composition: Composition, parent?: null, name?: string, ...types: Constructor<Component>[]): VFXItem;
+}
+
 type SDKMode = 'editor' | 'template';
 /**
  * @description SDK功能配置
@@ -2834,6 +3793,18 @@ type TextGizmoConfig = {
      * @description 触发边缩放交互的距离
      */
     widthScaleInteractionDistance: number;
+    /**
+     * @description 画板线框颜色
+     */
+    wireframeColor: number;
+    /**
+     * @description 画板线框透明度
+     */
+    wireframeAlpha: number;
+    /**
+     * @description 画板线框线宽
+     */
+    wireframeWidth: number;
 };
 /**
  * @description 蒙版参数
@@ -3082,9 +4053,6 @@ type ItemCreateType = 'none' | 'text' | 'video-generator' | 'sprite-generator' |
 type GizmoType = 'null' | 'selector' | 'transform' | 'control' | 'adsorption' | 'preference' | 'picture-cut' | 'text' | 'mask' | 'loading' | 'picture-expand' | 'sprite-text-edit' | 'video-play' | 'item-create';
 type GestureHandlerInteractType = 'select' | 'hand';
 
-type AlignType = 'left' | 'right' | 'horizontal-center' | 'top' | 'bottom' | 'vertical-center';
-type DistributeType = 'vertical-spacing' | 'horizontal-spacing';
-
 declare module '@pixi/graphics' {
     interface Graphics {
         fillBox(box: Box2): void;
@@ -3190,10 +4158,12 @@ declare class SDK {
     private disposables;
     private _isSwitchScene;
     private _undoRedo;
+    private _backgroundManager;
     player: Player;
     _container: HTMLElement;
     private _playerContainer;
     constructor(container: HTMLElement, mode?: SDKMode);
+    get backgroundManager(): BackgroundManager;
     get container(): HTMLElement;
     get pageData(): PageData | undefined;
     private get initExporterEnabled();
@@ -3654,4 +4624,4 @@ declare class SDK {
     applyFrameAutoLayout(frameId: string): void;
 }
 
-export { type ActiveData, BaseItem, type BaseItemProperty, type BaseItemPropertyKey, type BaseItemPropertyValueMap, Box2, type CreateOperation, type DeleteOperation, type EffectsCreateInfo, EffectsItem, type EffectsItemOptions, type FrameCreateInfo, FrameItem, type FrameItemOptions, type FrameItemProperty, FrameLayoutMode, type GeneratorCreateInfo, GeneratorItem, type GeneratorItemOptions, type GeneratorItemProperty, type GizmoType, type GroupCreateInfo, GroupItem, type GroupItemOptions, type ItemCreateInfo, ItemOrderAction, type ItemPropertyMap, type Operation, type PageData, type PageProperty, SDK, type SDKEvents, type SDKInputParam, type SDKItem, type SDKItemOptions, SDKItemType, type SDKOptions, type SetItemPropertyParam, type SetSingleItemMultiplePropertiesParam, type SetSingleItemSinglePropertyParam, type SpriteCreateInfo, SpriteItem, type SpriteItemOptions, type SpriteItemProperty, type TextCreateInfo, TextItem, type TextItemOptions, type TextItemProperty, type UpdateOperation, Vector2, type VideoCreateInfo, VideoItem, type VideoItemOptions, type VideoItemProperty, type ViewParam, type ViewProperty, createSDKItem, isBaseItem, isEffectsItem, isFrameItem, isGeneratorItem, isGroupItem, isSpriteItem, isTextItem, isVideoItem };
+export { type ActiveData, type AlignType, type AutoLayoutOptions, type AutoLayoutResult, type BackgroundGridConfig, BackgroundManager, type BackgroundPreset, BaseItem, type BaseItemProperty, type BaseItemPropertyKey, type BaseItemPropertyValueMap, Box2, type CameraInteractionParam, type CreateOperation, DefaultVFXItems, type DeleteOperation, type DistributeType, type EffectsCreateInfo, EffectsItem, type EffectsItemOptions, type FrameCreateInfo, FrameItem, type FrameItemOptions, type FrameItemProperty, FrameLayoutMode, type GeneratorCreateInfo, GeneratorItem, type GeneratorItemOptions, type GeneratorItemProperty, type GizmoType, type GroupCreateInfo, GroupItem, type GroupItemOptions, InteractionUtils, type ItemCreateInfo, type ItemJSONInfo, ItemOrderAction, type ItemPropertyMap, type LayoutItem, type LayoutResultItem, type MoveItemTransformOptions, type Operation, type PageData, PageDataUtils, type PageProperty, SDK, type SDKEvents, type SDKInputParam, type SDKItem, type SDKItemOptions, SDKItemType, type SDKOptions, SafeConstraint, type SetItemPropertyParam, type SetSingleItemMultiplePropertiesParam, type SetSingleItemSinglePropertyParam, type SpriteCreateInfo, SpriteItem, type SpriteItemOptions, type SpriteItemProperty, type TextCreateInfo, TextItem, type TextItemOptions, type TextItemProperty, type UpdateOperation, VFXItemFactory, Vector2, type VideoCreateInfo, VideoItem, type VideoItemOptions, type VideoItemProperty, type ViewInteractionParam, type ViewParam, type ViewProperty, addCompositionItemByComposition, addItemInfoToScene, arrAdd, assertExist, asserts, autoLayout, calculateDisplacement, calculateLayoutDisplacements, clearItemParentInfo, createCompositionItemJSON, createFrameCompositionScene, createNullItemJSON, createSDKItem, createSpriteItemJSON, createTextItemJSON, createVideoGeneratorItemJSON, createVideoItemJSON, deepClone, deepEquals, deleteCompositionFromScene, deleteCompositionItemFromScene, deleteItemInfoFromScene, downloadBlob, extractSubCompositionToScene, fixStandardJSON, getBasicScene, getColorByNormalizeColor, getCompositionDataByRefCompositionItemId, getCompositionIdByRefCompositionItemId, getNormalizeColorByColor, getTextureUrlById, getTransformRatioByViewAndCamera, getUniqueName, isBaseItem, isEffectsItem, isEqual, isFrameItem, isGeneratorItem, isGroupItem, isObj, isSpriteItem, isTextItem, isVideoItem, loadScriptAsync, logger, moveItemBetweenCompositions, removeItemInfoFromScene, resetSubCompositionItemId, setItemJSONParentId, setJSONItemName };