@vvfx/sdk 0.2.7 → 0.2.9

package/dist/sdk.js

@@ -0,0 +1,1903 @@
+import { merge } from 'lodash-es';
+import { assertExist, EventEmitter, Player } from './shared';
+import { SDKItemType } from './sdk-item/types';
+import { FrameLayoutMode } from './types';
+import { GestureHandler } from './gesture-handler/src/gesture-handler';
+import { PageDataUtils } from './utils/page-data-utils';
+import { Exporter } from './exporter';
+import { BackgroundManager, getUniqueName } from './utils';
+import { clearPlayerAssets } from './exporter/utils';
+import { ScreenShot } from './screen-shot';
+import { SizeAdapt } from './size-adapte';
+import { BaseConfig } from './config';
+import { arrAdd } from './utils/common-utils';
+import { getBasicScene } from './utils/json-data-utils';
+import { Vector2, Vector3 } from './math';
+import { UndoRedo } from './service/UndoRedo';
+import { isCardItem, isEffectsItem, isFrameItem } from './sdk-item';
+import { HTMLOverlayManager } from './html-overlay';
+import { orderSDKCanvasLayers } from './layer-order';
+const HTML_CARD_EDITING_VIEWPORT_PADDING = 48;
+export class SDK {
+    static config = BaseConfig;
+    _eventEmitter = new EventEmitter();
+    _pageData;
+    _screenShot;
+    _exporter;
+    _htmlOverlayManager;
+    _pageDataUtils;
+    _sizeAdapt;
+    _gestureHandler;
+    disposables = [];
+    _isSwitchScene = false;
+    _undoRedo = new UndoRedo();
+    _backgroundManager = new BackgroundManager();
+    player;
+    _container;
+    _playerContainer;
+    constructor(container, mode = 'template') {
+        this._container = container;
+        SDK.config.mode = mode;
+        this.initPlayer(mode);
+        this._eventEmitter.on('pageDataChange', (pageDate) => {
+            this._pageData = pageDate;
+            this._gestureHandler.render();
+        });
+        this._eventEmitter.on('preSelectedItemChange', (id) => {
+            assertExist(this._pageData, 'You must call SDK#run() first');
+            this._pageData.activeData.preSelectedItem = id;
+            this._gestureHandler.render();
+        });
+        this._eventEmitter.on('selectedViewChange', (id) => {
+            assertExist(this._pageData, 'You must call SDK#run() first');
+            this._pageData.activeData.view = id;
+            const targetView = this.getViewProperty(id);
+            this._gestureHandler.ignoreInteraction = !!targetView?.ignoreInteraction;
+        });
+        this._eventEmitter.on('sdkConfigChange', (_, curSDKConfig) => {
+            this.setExportConfig(curSDKConfig.exportConfig);
+        });
+        this._eventEmitter.on('itemCreate', () => {
+            this._gestureHandler.closeItemCreateGizmo();
+        });
+        this._pageDataUtils = new PageDataUtils(this.player, this._playerContainer, this._eventEmitter, this);
+        this._backgroundManager.attach(this._playerContainer);
+        this._gestureHandler = new GestureHandler(container);
+        this._screenShot = new ScreenShot();
+        this._sizeAdapt = new SizeAdapt();
+        const resizeObserver = new ResizeObserver(() => {
+            if (!this._pageData) {
+                return;
+            }
+            const parentSize = [container.offsetWidth, container.offsetHeight];
+            const viewProperty = this.getViewProperty(this._pageData.activeData.view ?? 0);
+            if (!viewProperty) {
+                return;
+            }
+            if (SDK.config.mode === 'template') {
+                const { size } = viewProperty;
+                const [width, height] = this._pageDataUtils.getPlayerSizeByParent(parentSize, size);
+                this._playerContainer.style.width = `${width}px`;
+                this._playerContainer.style.height = `${height}px`;
+                this.player.resize();
+            }
+            this._pageDataUtils.refreshInteractionParam();
+            this._gestureHandler.resize();
+            this._htmlOverlayManager?.scheduleRender();
+        });
+        resizeObserver.observe(container);
+        this.disposables.push(() => {
+            resizeObserver.disconnect();
+        });
+        this._htmlOverlayManager = new HTMLOverlayManager({
+            container,
+            emitter: this._eventEmitter,
+            getItems: () => this.getSDKItems(),
+            getViewBoxById: (id) => this.getViewBoxById(id),
+            getViewport: () => {
+                const { zoom, translation } = this.getPageConfig();
+                return {
+                    zoom,
+                    translation: [...translation],
+                };
+            },
+            setViewport: ({ zoom, translation }) => {
+                this.setPageZoom(zoom, undefined, true);
+                this.setPageMove(new Vector2(...translation));
+            },
+            viewportFit: (box) => {
+                this.viewportFit({
+                    left: HTML_CARD_EDITING_VIEWPORT_PADDING,
+                    right: HTML_CARD_EDITING_VIEWPORT_PADDING,
+                    top: HTML_CARD_EDITING_VIEWPORT_PADDING,
+                    bottom: HTML_CARD_EDITING_VIEWPORT_PADDING,
+                }, box);
+            },
+            setCardItemHeight: (id, height, options) => {
+                const item = this.getSDKItem(id);
+                if (!isCardItem(item) || options.anchor === 'center') {
+                    void this.setItemProperty({
+                        itemId: id,
+                        type: SDKItemType.CARD,
+                        propertyName: 'height',
+                        propertyValue: height,
+                    });
+                    return;
+                }
+                const [x, y] = item.property.position;
+                const deltaY = (height - options.previousHeight) / 2;
+                void this.setItemProperty({
+                    itemId: id,
+                    type: SDKItemType.CARD,
+                    property: {
+                        height,
+                        position: [x, y + deltaY],
+                    },
+                });
+            },
+            getSelectedItemIds: () => this._pageData?.activeData.selectedItems ?? [],
+            setSelectedItemIds: (ids) => {
+                this.setSelectedItems(ids);
+            },
+            getPreSelectedItemId: () => this._pageData?.activeData.preSelectedItem,
+            getSelectionEdgeStyle: () => {
+                const { wireframeColor, wireframeAlpha, wireframeWidth, } = SDK.config.gestureHandlerConfig.transformGizmoConfig;
+                return {
+                    color: wireframeColor,
+                    alpha: wireframeAlpha,
+                    width: wireframeWidth,
+                };
+            },
+            getPreSelectionEdgeStyle: () => {
+                const { preSelectedColor, preSelectedWidth, } = SDK.config.gestureHandlerConfig.selectorGizmoConfig;
+                return {
+                    color: preSelectedColor,
+                    alpha: 1,
+                    width: preSelectedWidth,
+                };
+            },
+            getCanvasEventTarget: () => this._gestureHandler?.wireframeApplication.view,
+            resolveCardHTML: item => isCardItem(item) ? this.resolveCardHTML(item) : undefined,
+            resolveCardTypeConfig: item => isCardItem(item) ? this.resolveCardTypeConfig(item) : undefined,
+        });
+        this._htmlOverlayManager.attach();
+        this.syncCanvasLayerOrder();
+    }
+    get backgroundManager() {
+        return this._backgroundManager;
+    }
+    get container() {
+        return this._container;
+    }
+    get pageData() {
+        return this._pageData;
+    }
+    get initExporterEnabled() {
+        return SDK.config.mode === 'template' && SDK.config.exportConfig.enabled;
+    }
+    get exportStatus() {
+        return this?._exporter?.status;
+    }
+    get undoRedo() {
+        return this._undoRedo;
+    }
+    get exportOptions() {
+        if (!this.pageData) {
+            return [];
+        }
+        const viewProperties = this.pageData.viewProperties.filter((vp) => !vp.ignoreInteraction);
+        const folderName = viewProperties[0]?.scene?.compositions?.[0]?.name ?? 'videos';
+        const names = [];
+        return viewProperties.map((viewProperty, idx) => {
+            const { size, scene, export: { name: videoName, ...restViewProperty }, } = viewProperty;
+            const sizeInfo = size?.[0] && size?.[1] ? ` (${idx + 1})_${size[0]}×${size[1]}` : ` (${idx + 1})`;
+            // 如果用户传视频名称，则使用用户传的名称，否则使用 合成+size 名称
+            let newName = '';
+            if (videoName) {
+                newName = getUniqueName(videoName, names);
+            }
+            else {
+                newName = `${folderName}${sizeInfo}`;
+            }
+            names.push(newName);
+            return {
+                folderName,
+                name: newName,
+                size,
+                scene: JSON.parse(JSON.stringify(scene)),
+                ...restViewProperty,
+            };
+        });
+    }
+    dispose() {
+        this._htmlOverlayManager?.dispose();
+        this.player?.dispose();
+        this._screenShot?.dispose();
+        this._pageData = undefined;
+        this._playerContainer.remove();
+        this?._exporter?.dispose();
+        this._screenShot.dispose();
+        this._gestureHandler.dispose();
+        this.disposables.forEach((dispose) => {
+            dispose();
+        });
+    }
+    on = this._eventEmitter.on;
+    initPlayer(mode) {
+        const playerContainer = document.createElement('div');
+        const [width, height] = mode === 'template' ? [this._container.offsetWidth, this._container.offsetHeight] : [document.documentElement.clientWidth, document.documentElement.clientHeight];
+        this._playerContainer = playerContainer;
+        this._playerContainer.id = 'player-container';
+        this._playerContainer.style.position = 'absolute';
+        this._playerContainer.style.width = `${width}px`;
+        this._playerContainer.style.height = `${height}px`;
+        if (mode === 'editor') {
+            this._playerContainer.style.left = '0px';
+            this._playerContainer.style.top = '0px';
+        }
+        this._container.appendChild(playerContainer);
+        this.player = new Player({
+            container: this._playerContainer,
+            pixelRatio: 2,
+            interactive: true,
+            env: 'editor'
+        });
+        this.player.on('update', () => {
+            assertExist(this._pageData, 'You must call SDK#run() first');
+            if (this._isSwitchScene) {
+                return;
+            }
+            const time = this.player.getCompositions()[0]?.time;
+            if (this._pageData.playing) {
+                if (time !== undefined) {
+                    if (this._pageData.time === time) {
+                        this.player.pause();
+                    }
+                    this._pageData.time = time;
+                    this._pageDataUtils.refreshPageTime(time);
+                }
+                else {
+                    this._pageData.playing = false;
+                    void this.setPlayProgress(100);
+                    const scene = this.getViewProperty(this._pageData.activeData.view ?? 0)?.scene;
+                    const targetComposition = scene?.compositions.find(c => c.id === scene.compositionId);
+                    this._pageData.time = targetComposition?.duration ?? 2;
+                    this._pageDataUtils.refreshPageTime(this._pageData.time);
+                }
+            }
+            this._eventEmitter.emit('progress', {
+                duration: this.player.getCompositions()[0]?.getDuration() ?? 2,
+                time: this._pageData.time,
+                end: this.player.getCompositions()[0]?.isDestroyed ?? false,
+                paused: !this._pageData.playing,
+            });
+        });
+        this.player.on('rendererror', (error) => {
+            console.error('player render error ', error);
+        });
+        this.player.on('webglcontextlost', () => {
+            this._eventEmitter.emit('viewLost');
+            const canvas = this.player?.canvas;
+            if (canvas) {
+                canvas.parentElement?.removeChild(canvas);
+            }
+            this.player.pause();
+            this.player.dispose();
+            this._gestureHandler.dispose();
+            setTimeout(async () => {
+                this.initPlayer(SDK.config.mode);
+                this._pageDataUtils = new PageDataUtils(this.player, this._playerContainer, this._eventEmitter, this);
+                this._gestureHandler = new GestureHandler(this._container);
+                this.syncCanvasLayerOrder();
+                const itemExtension = {};
+                if (SDK.config.mode === 'template') {
+                    this.pageData?.items.forEach(item => {
+                        itemExtension[item.id] = item.getAllExtension();
+                    });
+                    await this.runByPageData(this.pageData);
+                    this.pageData?.items.forEach(item => {
+                        const extension = itemExtension[item.id];
+                        if (extension) {
+                            item.setExtensions(extension);
+                        }
+                    });
+                }
+                else {
+                    const createInfos = this.getItemCreateInfos();
+                    await this.runByCreateInfos(createInfos);
+                }
+                this._eventEmitter.emit('viewRebuildFinish');
+            }, 300);
+        });
+    }
+    setSDKMode(mode) {
+        if (mode === SDK.config.mode) {
+            return;
+        }
+        SDK.config.mode = mode;
+        const [width, height] = mode === 'template' ? [this._container.offsetWidth, this._container.offsetHeight] : [document.documentElement.clientWidth, document.documentElement.clientHeight];
+        if (!this._playerContainer) {
+            const playerContainer = document.createElement('div');
+            this._container.appendChild(playerContainer);
+            this._playerContainer = playerContainer;
+            this._playerContainer.id = 'player-container';
+            this._playerContainer.style.position = 'absolute';
+        }
+        if (mode === 'editor') {
+            this._playerContainer.style.left = '0px';
+            this._playerContainer.style.top = '0px';
+        }
+        this._playerContainer.style.width = `${width}px`;
+        this._playerContainer.style.height = `${height}px`;
+        this.player ??= new Player({
+            container: this._playerContainer,
+            interactive: true,
+            pixelRatio: 2,
+            env: 'editor'
+        });
+        this.player.resize();
+        this.syncCanvasLayerOrder();
+    }
+    syncCanvasLayerOrder() {
+        orderSDKCanvasLayers({
+            container: this._container,
+            playerContainer: this._playerContainer,
+            htmlOverlayLayer: this._htmlOverlayManager?.layerElement,
+            gestureCanvas: this._gestureHandler?.wireframeApplication.view,
+        });
+    }
+    async getInitParam(param) {
+        const loadParam = JSON.parse(JSON.stringify(param));
+        if (loadParam.mode === 'editor') {
+            const viewSize = [this._playerContainer.offsetWidth, this._playerContainer.offsetHeight];
+            return {
+                scene: getBasicScene(viewSize),
+                viewParams: [
+                    {
+                        size: viewSize,
+                        export: {
+                            audioEnable: false,
+                        },
+                    },
+                ],
+                options: {
+                    asyncMode: false,
+                    safeAreaPreview: false,
+                    adsorption: true,
+                },
+            };
+        }
+        else {
+            if (typeof loadParam.scene === 'string') {
+                try {
+                    const response = await fetch(loadParam.scene, {
+                        mode: 'cors',
+                        credentials: 'omit',
+                        headers: {
+                            Accept: 'application/json',
+                        },
+                    });
+                    if (!response.ok) {
+                        throw new Error(`HTTP error! status: ${response.status}, statusText: ${response.statusText}`);
+                    }
+                    const scene = (await response.json());
+                    const mainComposition = scene.compositions.find((c) => c.id === scene.compositionId) ?? scene.compositions[0];
+                    const viewParams = !loadParam.viewParams?.length
+                        ? [
+                            {
+                                size: mainComposition.previewSize ?? [750, 1624],
+                                export: {
+                                    audioEnable: false,
+                                },
+                            },
+                        ]
+                        : loadParam.viewParams;
+                    return {
+                        ...loadParam,
+                        scene,
+                        viewParams,
+                    };
+                }
+                catch (error) {
+                    // 重新抛出错误，让 sdk#run 方法能够捕获并处理
+                    throw new Error(`Failed to fetch scene data from ${loadParam.scene}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            const mainComposition = loadParam.scene.compositions.find((c) => c.id === loadParam.scene.compositionId) ?? loadParam.scene.compositions[0];
+            const viewParams = !loadParam.viewParams?.length
+                ? [
+                    {
+                        size: mainComposition.previewSize ?? [750, 1624],
+                        export: {
+                            audioEnable: false,
+                        },
+                    },
+                ]
+                : loadParam.viewParams;
+            return {
+                ...loadParam,
+                scene: loadParam.scene,
+                viewParams,
+            };
+        }
+    }
+    initExporter(params) {
+        if (!this.initExporterEnabled) {
+            return;
+        }
+        this._exporter = new Exporter(params);
+        this._exporter.on('progress', (progress) => {
+            this._eventEmitter.emit('exportProgress', progress);
+        });
+        this._exporter.on('done', (item, success, buffer) => {
+            this._eventEmitter.emit('exportDone', item, success, buffer);
+        });
+        this._exporter.on('complete', (success, taskInfos, buffers, extras) => {
+            this._eventEmitter.emit('exportComplete', success, taskInfos, buffers, extras);
+        });
+    }
+    async initSDK(param) {
+        const { scene, viewParams, options } = param;
+        const result = [];
+        // add static scene
+        if (SDK.config.pageConfig.staticPreview) {
+            const staticScene = JSON.parse(JSON.stringify(scene));
+            const mainComposition = staticScene.compositions.find((composition) => composition.id === staticScene.compositionId) ??
+                staticScene.compositions[0];
+            if (mainComposition) {
+                const [width, height] = mainComposition.previewSize ?? [1080, 1920];
+                const tick = mainComposition.duration ?? 0;
+                result.push({
+                    size: [width, height],
+                    safeArea: [0, 0, 0, 0],
+                    previewSafeAreas: [],
+                    id: 0,
+                    scene: staticScene,
+                    ignoreInteraction: true,
+                    export: {
+                        time: tick,
+                        audioEnable: false,
+                    },
+                });
+            }
+        }
+        for (let i = 0; i < viewParams.length; i++) {
+            const viewProperty = viewParams[i];
+            if (!viewProperty) {
+                continue;
+            }
+            let resultScene = JSON.parse(JSON.stringify(scene));
+            const mainComposition = resultScene.compositions.find((composition) => composition.id === resultScene.compositionId) ??
+                resultScene.compositions[0];
+            assertExist(mainComposition);
+            const previewSize = mainComposition.previewSize ?? [750, 1624];
+            const originSize = previewSize;
+            const resultSize = viewProperty.size ?? previewSize;
+            mainComposition.previewSize = resultSize;
+            const tick = mainComposition.duration ?? 0;
+            const safeArea = viewProperty.safeArea ?? [0, 0, 0, 0];
+            if (SDK.config.sizeAdaptConfig.enabled) {
+                resultScene = await this._sizeAdapt.adjustment(resultScene, tick, originSize, resultSize, safeArea, viewProperty.adaptionDirection);
+            }
+            viewProperty.export.time ??= tick;
+            result.push({
+                ...viewProperty,
+                size: resultSize,
+                safeArea,
+                previewSafeAreas: [...(viewProperty.previewSafeAreas ?? [])],
+                id: i + 1,
+                scene: resultScene,
+                ignoreInteraction: false,
+            });
+        }
+        const activeScene = result[0]?.scene;
+        if (!activeScene) {
+            console.warn('SDK need one view property at least.');
+            return;
+        }
+        const mainComposition = activeScene.compositions.find((composition) => composition.id === activeScene.compositionId) ??
+            activeScene.compositions[0];
+        const property = { ...options, zoom: 1, translation: [0, 0], asyncMode: options.asyncMode ?? false };
+        const time = (mainComposition?.duration ?? 0) - 0.1;
+        const targetIndex = SDK.config.pageConfig.staticPreview ? 1 : 0;
+        this._pageData = {
+            scene: JSON.parse(JSON.stringify(scene)),
+            time,
+            property,
+            activeData: {
+                view: result[targetIndex].id,
+                selectedItems: [],
+            },
+            items: [],
+            viewProperties: result,
+            playing: false,
+        };
+        this._pageDataUtils.init();
+        await this._gestureHandler.init(this._pageDataUtils, this._eventEmitter);
+        this._gestureHandler.ignoreInteraction = result[1]?.ignoreInteraction ?? false;
+        SDK.config.gestureHandlerConfig.preferenceGizmoConfig.safeAreaEnabled = property.safeAreaPreview;
+        this._eventEmitter.emit('progress', {
+            duration: time,
+            time: time,
+            end: this.player.getCompositions()[0]?.isDestroyed ?? false,
+            paused: !this._pageData.playing,
+        });
+        await this._pageDataUtils.loadScene(this._pageData.activeData.view);
+        this._pageDataUtils.refreshPageTime(time);
+    }
+    async run(param) {
+        this.setSDKMode(param.mode);
+        SDK.config.pageConfig.staticPreview = param.mode === 'template' && SDK.config.pageConfig.staticPreview;
+        const initPram = await this.getInitParam(param);
+        await this.initSDK(initPram);
+        this._eventEmitter.emit('pageDataChange', this.pageData);
+        this.initExporter(SDK.config.exportConfig);
+    }
+    getActiveItems() {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        return this._pageData.activeData.selectedItems;
+    }
+    setPreSelectedItem(id) {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        this._pageData.activeData.preSelectedItem = id;
+    }
+    getPreSelectedItem() {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        return this._pageData.activeData.preSelectedItem ?? '';
+    }
+    setSelectedItems(itemIds) {
+        this._pageDataUtils.clearPreSelectedItem();
+        this._pageDataUtils.clearSelectedItems();
+        this._pageDataUtils.addSelectedItems([...itemIds]);
+    }
+    /**
+     * @description 设置元素属性（支持单个元素的单/多属性设置）
+     * @param param 设置参数，支持两种场景：
+     *   1. 单个元素单个属性: { itemId, type, propertyName, propertyValue }
+     *   2. 单个元素多个属性: { itemId, type, property }
+     */
+    async setItemProperty(param) {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        const ignoreInteraction = this.getViewProperty(this._pageData.activeData.view ?? 0)?.ignoreInteraction;
+        if (ignoreInteraction) {
+            console.warn('Static scene cannot change.');
+            return;
+        }
+        await this._pageDataUtils.setItemProperty(param);
+        this._gestureHandler.render();
+        this._eventEmitter.emit('pageDataChange', this.pageData);
+    }
+    async generateScreenShot(id, size = [300, 400], tick, backgroundColor) {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        const viewProperty = this.getViewProperty(id);
+        if (!viewProperty) {
+            return '';
+        }
+        const { scene, size: [width, height], } = viewProperty;
+        const compositionId = scene.compositionId;
+        const composition = scene.compositions.find((comp) => comp.id === compositionId);
+        tick ??= composition?.duration ?? 0;
+        const targetScene = JSON.parse(JSON.stringify(scene));
+        const result = await this._screenShot.generate(targetScene, [width, height], size, tick, backgroundColor);
+        return result;
+    }
+    /**
+     * @description 切换场景
+     * @param index 场景索引
+     */
+    async switchScene(index) {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        // 相同合成不做切换
+        if (index === this._pageData.activeData.view) {
+            return;
+        }
+        this._isSwitchScene = true;
+        const targetView = this._pageData.viewProperties[index];
+        if (!targetView) {
+            console.warn('target scene does not exist.');
+        }
+        else {
+            const isPlaying = this._pageData.playing;
+            this._pageData.activeData = {
+                view: targetView.id,
+                selectedItems: [],
+                preSelectedItem: undefined,
+            };
+            await this._pageDataUtils.loadScene(targetView.id);
+            if (isPlaying) {
+                this._pageData.playing = isPlaying;
+                this.player.gotoAndPlay(this._pageData.time);
+            }
+        }
+        this._eventEmitter.emit('selectedViewChange', index);
+        this._eventEmitter.emit('pageDataChange', this.pageData);
+        this._isSwitchScene = false;
+    }
+    /**
+     * @description 获取页面的 safeAreaPreview、zoom、adsorption、translation 值
+     * @returns 页面的 safeAreaPreview、zoom、adsorption、translation 值
+     */
+    getPageConfig() {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        return {
+            safeAreaPreview: this._pageData.property.safeAreaPreview,
+            zoom: this._pageData.property.zoom,
+            adsorption: this._pageData.property.adsorption,
+            asyncMode: this._pageData.property.asyncMode,
+            translation: this._pageData.property.translation
+        };
+    }
+    /**
+     * 设置页面的 safeAreaPreview、zoom、adsorption 值
+     * @param pageProperty 设置
+     */
+    setPageConfig(pageConfig) {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        const { adsorption, safeAreaPreview, zoom } = this._pageData.property;
+        this._pageData.property = {
+            ...this._pageData.property,
+            ...pageConfig,
+        };
+        if (this._pageData.property.zoom !== zoom) {
+            this._pageDataUtils.setPageZoom(this._pageData.property.zoom);
+        }
+        if (adsorption !== pageConfig.adsorption) {
+            SDK.config.gestureHandlerConfig.adsorptionGizmoEnabled = pageConfig.adsorption;
+        }
+        if (safeAreaPreview !== pageConfig.safeAreaPreview) {
+            SDK.config.gestureHandlerConfig.preferenceGizmoConfig.safeAreaEnabled = pageConfig.safeAreaPreview;
+        }
+        this._gestureHandler.render();
+    }
+    /**
+     * @description 设置播放进度
+     * @param progress 播放进度 0-100
+     */
+    async setPlayProgress(progress) {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        const duration = this.player.getCompositions()[0]?.getDuration() ?? 2;
+        const time = (duration * progress) / 100;
+        this._pageData.time = time;
+        const hasCleared = !this.player.getCompositions().length;
+        if (hasCleared) {
+            clearPlayerAssets(this.player);
+            await this._pageDataUtils.loadScene(this._pageData.activeData.view ?? 0);
+        }
+        const playing = this._pageData.playing;
+        if (playing) {
+            this.player.gotoAndPlay(time);
+        }
+        else {
+            this.player.gotoAndStop(time);
+            this._eventEmitter.emit('progress', {
+                duration: this.player.getCompositions()[0]?.getDuration() ?? 2,
+                time,
+                end: this.player.getCompositions()[0]?.isDestroyed ?? false,
+                paused: true,
+            });
+        }
+        this._pageDataUtils.refreshPageTime(time);
+    }
+    /**
+     * @description 获取元素
+     * @param id 元素ID
+     * @returns 元素
+     * */
+    getSDKItem(id) {
+        return this._pageDataUtils.getSDKItem(id);
+    }
+    /**
+     * @description 获取元素数组
+     * @param id 元素ID数组
+     * @returns 元素数组
+     * */
+    getSDKItems(ids) {
+        if (!ids) {
+            return this.pageData?.items ?? [];
+        }
+        return ids.map(id => this.getSDKItem(id)).filter((v) => !!v);
+    }
+    async setPlayState(playState) {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        const playing = playState === 'play';
+        if (this._pageData.playing === playing) {
+            return;
+        }
+        this._pageData.playing = playing;
+        this._gestureHandler.ignoreInteraction = playing;
+        if (playing) {
+            const compositions = this.player.getCompositions();
+            const acitveViewProperty = this.getViewProperty(this._pageData.activeData.view ?? 0);
+            const playScene = JSON.parse(JSON.stringify(acitveViewProperty.scene));
+            await this.player.loadScene(playScene, { autoplay: false });
+            this.player.gotoAndPlay(this._pageData.time);
+            this.destroyCompositions(compositions);
+        }
+        else {
+            this.player.gotoAndStop(this._pageData.time);
+        }
+        this._gestureHandler.render();
+    }
+    /**
+     * @description 获取场景预览图
+     * @returns 视图预览图
+     */
+    getViewThumbnail() {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        return this._pageData.viewProperties.map(async (property) => {
+            return {
+                id: property.id,
+                thumbnail: await this.generateScreenShot(property.id)
+            };
+        });
+    }
+    /**
+     * @description 获取视图JSON产物
+     * @returns 当前所有视图JSON产物
+     */
+    getViewScene() {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        return this._pageData.viewProperties.map((property) => {
+            return {
+                id: property.id,
+                thumbnail: property.scene,
+            };
+        });
+    }
+    destroyCompositions(compositions) {
+        compositions.forEach((comp) => {
+            comp.dispose();
+            const currentCompositions = this.player.getCompositions();
+            const index = currentCompositions.indexOf(comp);
+            if (index > -1) {
+                currentCompositions.splice(index, 1);
+            }
+        });
+    }
+    /**
+     * @description 以媒体格式 buffer 下载
+     */
+    downloadByMediaBuffersOfExporter(params, buffers, extras) {
+        assertExist(this._exporter, 'You must init exporter first');
+        this._exporter.downloadByMediaBuffers(params, buffers, extras);
+    }
+    /**
+     * @description 导出
+     * 支持导出媒体或其他，如MP4，未来支持 JSON 等；
+     */
+    onExport() {
+        if (!SDK.config.exportConfig.enabled) {
+            return;
+        }
+        assertExist(this.pageData, 'You must call SDK#run() first');
+        assertExist(this._exporter, 'You must init exporter first');
+        this._exporter.onExport(this.exportOptions);
+    }
+    /**
+     * @description 取消导出
+     */
+    cancelExport() {
+        assertExist(this._exporter, 'You must init exporter first');
+        this._exporter.onCancel();
+    }
+    async loadPageData(data) {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        this._pageData.activeData = {
+            view: this._pageData.viewProperties[this._pageData.viewProperties.length - 1].id,
+            selectedItems: [],
+            preSelectedItem: undefined,
+        };
+        this._pageData.viewProperties.push(...data.viewProperties);
+        this._pageDataUtils.init();
+        await this._gestureHandler.init(this._pageDataUtils, this._eventEmitter);
+        await this._pageDataUtils.loadScene(this.pageData?.activeData.view ?? 0);
+        this._eventEmitter.emit('pageDataChange', this.pageData);
+    }
+    async runByPageData(data) {
+        const loadData = JSON.parse(JSON.stringify(data));
+        loadData.property.zoom = 1;
+        loadData.property.translation = [0, 0];
+        this._pageData = loadData;
+        this._pageDataUtils.init();
+        await this._gestureHandler.init(this._pageDataUtils, this._eventEmitter);
+        await this._pageDataUtils.loadScene(this.pageData?.activeData.view ?? 0);
+        this._pageDataUtils.refreshPageTime(this._pageData.time);
+        this._eventEmitter.emit('pageDataChange', this.pageData);
+    }
+    async runByCreateInfos(createInfos) {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        this._pageData.property.zoom = 1;
+        this._pageData.property.translation = [0, 0];
+        this._pageDataUtils.init();
+        await this._gestureHandler.init(this._pageDataUtils, this._eventEmitter);
+        const viewSize = [this._playerContainer.offsetWidth, this._playerContainer.offsetHeight];
+        const scene = getBasicScene(viewSize);
+        const targetViewProperty = this.getViewProperty(this._pageData.activeData.view ?? 0);
+        if (targetViewProperty) {
+            targetViewProperty.scene = scene;
+        }
+        await this._pageDataUtils.loadScene(this._pageData.activeData.view ?? 0);
+        await this.addItemByCreateInfos(createInfos);
+        this._pageDataUtils.refreshPageTime(this._pageData.time);
+        this._eventEmitter.emit('pageDataChange', this.pageData);
+    }
+    async reloadPageDataByScene(scene) {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        let loadScene = JSON.parse(JSON.stringify(scene));
+        if (typeof loadScene === 'string') {
+            try {
+                const response = await fetch(loadScene, {
+                    mode: 'cors',
+                    credentials: 'omit',
+                    headers: {
+                        Accept: 'application/json',
+                    },
+                });
+                if (!response.ok) {
+                    throw new Error(`HTTP error! status: ${response.status}, statusText: ${response.statusText}`);
+                }
+                loadScene = await response.json();
+            }
+            catch (error) {
+                // 重新抛出错误，让 sdk#run 方法能够捕获并处理
+                throw new Error(`Failed to fetch scene data from ${loadScene}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        this._pageData.time =
+            loadScene.compositions.find((composition) => composition.id === loadScene.compositionId)
+                ?.duration ?? 2;
+        this._pageData.viewProperties.forEach((viewProperty) => {
+            viewProperty.scene = JSON.parse(JSON.stringify(loadScene));
+        });
+        this._pageDataUtils.init();
+        await this._gestureHandler.init(this._pageDataUtils, this._eventEmitter);
+        await this._pageDataUtils.loadScene(this._pageData.activeData.view ?? 0);
+        this._eventEmitter.emit('progress', {
+            duration: this.player.getCompositions()[0]?.getDuration() ?? 2,
+            time: this._pageData.time,
+            end: this.player.getCompositions()[0]?.isDestroyed ?? false,
+            paused: !this._pageData.playing,
+        });
+    }
+    /**
+     * @description 新增视图数据
+     * @param viewParams 视图参数
+     * @param scene 场景数据 - 无输入时为默认场景数据
+     */
+    async addViewParams(viewParams, scene) {
+        assertExist(this._pageData);
+        const result = [];
+        const originLength = this._pageData.viewProperties[this._pageData.viewProperties.length - 1]?.id ??
+            this._pageData.viewProperties.length - 1;
+        for (let i = 0; i < viewParams.length; i++) {
+            const viewProperty = viewParams[i];
+            if (!viewProperty) {
+                continue;
+            }
+            let resultScene = JSON.parse(JSON.stringify(scene ?? this._pageData.scene));
+            const mainComposition = resultScene.compositions.find((composition) => composition.id === resultScene.compositionId) ??
+                resultScene.compositions[0];
+            assertExist(mainComposition);
+            const { previewSize = [750, 1624] } = mainComposition;
+            const originSize = previewSize;
+            const resultSize = viewProperty.size ?? previewSize;
+            mainComposition.previewSize = resultSize;
+            const tick = mainComposition.duration ?? 0;
+            const safeArea = viewProperty.safeArea ?? [0, 0, 0, 0];
+            if (SDK.config.sizeAdaptConfig.enabled) {
+                resultScene = await this._sizeAdapt.adjustment(resultScene, tick, originSize, resultSize, safeArea, viewProperty.adaptionDirection);
+            }
+            viewProperty.export.time ??= tick;
+            result.push({
+                ...viewProperty,
+                size: resultSize,
+                safeArea,
+                previewSafeAreas: [...(viewProperty.previewSafeAreas ?? [])],
+                id: originLength + 1 + i,
+                scene: resultScene,
+                ignoreInteraction: false,
+            });
+        }
+        this._pageData.viewProperties.push(...result);
+        this._eventEmitter.emit('pageDataChange', this.pageData);
+    }
+    async deleteViewParams(ids) {
+        ids.sort((a, b) => a - b);
+        for (let index = 0; index < ids.length; index++) {
+            const id = ids[index];
+            assertExist(this._pageData);
+            const targetId = id - index;
+            const targetIndex = this._pageData.viewProperties.findIndex((vp) => vp.id === targetId);
+            if (this._pageData.viewProperties[targetIndex]?.ignoreInteraction) {
+                console.warn('target view ignore interaction, it can not be deleted.');
+                continue;
+            }
+            if (targetIndex < 0) {
+                console.warn('Target view is not existed.');
+                continue;
+            }
+            this._pageData.viewProperties.splice(targetIndex, 1);
+            const selectedView = this._pageData.activeData.view ?? 0;
+            if (targetId === selectedView) {
+                this._pageData.activeData.view = 0;
+                await this._pageDataUtils.loadScene(0);
+            }
+            else if (targetId < selectedView) {
+                this._pageData.activeData.view = selectedView - 1;
+            }
+            this._pageData.viewProperties.forEach((vp) => {
+                if (vp.id > targetId) {
+                    vp.id -= 1;
+                }
+            });
+        }
+        this._eventEmitter.emit('selectedViewChange', this._pageData?.activeData?.view ?? 0);
+        this._eventEmitter.emit('pageDataChange', this.pageData);
+    }
+    setExportParam(exportParam, id) {
+        assertExist(this._pageData);
+        this._pageData.viewProperties.forEach((viewPort) => {
+            if (id === undefined || viewPort.id === id) {
+                Object.assign(viewPort.export, exportParam);
+            }
+        });
+    }
+    /**
+     * @description 设置视图缩放
+     * @param zoom 缩放值
+     * @param center 缩放中心
+     * @param ignoreClamp 是否忽视约束
+     */
+    setPageZoom(zoom, center, ignoreClamp) {
+        assertExist(this._pageData);
+        this._pageDataUtils.setPageZoom(zoom, center, ignoreClamp);
+        this._gestureHandler.render();
+    }
+    /**
+     * @description 设置元素移动
+     * @param targetTranslation 目标移动值
+     */
+    setPageMove(targetTranslation) {
+        assertExist(this._pageData);
+        this._pageData.property.translation = targetTranslation.toArray();
+        this._pageDataUtils.setPageMove(targetTranslation.clone());
+        this._gestureHandler.render();
+    }
+    /**
+     * @description 设置静态预览功能开关
+     * @param enabled 功能开关
+     */
+    setStaticPreviewEnabled(enabled) {
+        SDK.config.pageConfig.staticPreview = enabled;
+    }
+    /**
+     * @description 设置静态预览视图名称
+     * @param name 视图名称
+     */
+    setStaticPreviewName(name) {
+        SDK.config.pageConfig.staticPreviewName = name;
+    }
+    /**
+     * @description 设置同步修改功能开关
+     * @param enabled 功能开关
+     */
+    setAsyncEnabled(enabled) {
+        SDK.config.pageConfig.asncMode = enabled;
+    }
+    /**
+     * @description 设置 成组显影 开关
+     */
+    setGroupVisibleEnabled(enabled) {
+        SDK.config.pageConfig.groupVisible = enabled;
+    }
+    /**
+     * @description 新增过滤元素名称
+     * @param itemNames 过滤元素名称
+     */
+    addFilterItemNames(itemNames) {
+        if (typeof itemNames === 'string') {
+            arrAdd(SDK.config.pageConfig.filterItemNames, itemNames);
+        }
+        else {
+            itemNames.forEach((name) => {
+                arrAdd(SDK.config.pageConfig.filterItemNames, name);
+            });
+        }
+    }
+    /**
+     * @description 设置预览辅助层颜色
+     * @param color 色值
+     */
+    setPreferenceBackgroundColor(color) {
+        SDK.config.gestureHandlerConfig.preferenceGizmoConfig.markColor = (color[0] << 16) | (color[1] << 8) | color[2];
+        SDK.config.gestureHandlerConfig.preferenceGizmoConfig.markAlpha = color[3] ?? 0.3;
+        this._gestureHandler.render();
+    }
+    /**
+     * @description 设置出血区颜色
+     * @param color 色值
+     */
+    setSafeAreaColor(color) {
+        SDK.config.gestureHandlerConfig.preferenceGizmoConfig.safeAreaBoxColor =
+            (color[0] << 16) | (color[1] << 8) | color[2];
+        SDK.config.gestureHandlerConfig.preferenceGizmoConfig.safeAreaBoxAlpha = color[3] ?? 0.3;
+        this._gestureHandler.render();
+    }
+    /**
+     * @description 设置 尺寸自适应拓展 功能开关
+     * @param enabled 功能开关
+     */
+    setSizeAdaptEnabled(enabled) {
+        SDK.config.sizeAdaptConfig.enabled = enabled;
+    }
+    /**
+     * @description 设置 截图 功能开关
+     * @param enabled 功能开关
+     */
+    setScreenShotEnabled(enabled) {
+        SDK.config.screenShotConfig.enabled = enabled;
+    }
+    /**
+     * @description 设置导出功能初始化配置
+     * @param exportConfig
+     */
+    setExportConfig(exportConfig) {
+        const newExportConfig = merge({}, SDK.config.exportConfig, exportConfig);
+        SDK.config.exportConfig = newExportConfig;
+        if (this._exporter) {
+            this._exporter.setOptions(newExportConfig);
+        }
+        else {
+            this.initExporter(newExportConfig);
+        }
+    }
+    /**
+     * @description 设置预选框参数
+     * @param preSelectedColor 预选框颜色
+     * @param preSelectedWidth 预选框线框宽度
+     */
+    setSelectorGizmoPreSelectConfig(preSelectedColor, preSelectedWidth) {
+        if (preSelectedColor !== undefined) {
+            SDK.config.gestureHandlerConfig.selectorGizmoConfig.preSelectedColor = preSelectedColor;
+        }
+        if (preSelectedWidth !== undefined) {
+            SDK.config.gestureHandlerConfig.selectorGizmoConfig.preSelectedWidth = preSelectedWidth;
+        }
+        this._gestureHandler.render();
+    }
+    /**
+     * @description 设置 变换控制器 交互框参数
+     * @param config 参数
+     */
+    setTranformGizmoWireframeConfig(config) {
+        if (config.wireframeAlpha !== undefined) {
+            SDK.config.gestureHandlerConfig.transformGizmoConfig.wireframeAlpha = config.wireframeAlpha;
+        }
+        if (config.wireframeColor !== undefined) {
+            SDK.config.gestureHandlerConfig.transformGizmoConfig.wireframeColor = config.wireframeColor;
+        }
+        if (config.wireframeWidth !== undefined) {
+            SDK.config.gestureHandlerConfig.transformGizmoConfig.wireframeWidth = config.wireframeWidth;
+        }
+        this._gestureHandler.render();
+    }
+    /**
+     * @description 获取 SDK 配置参数
+     * @returns SDK 配置参数
+     */
+    getSDKConfig() {
+        return SDK.config;
+    }
+    /**
+     * @description 设置 SDK 配置参数
+     * @param config SDK 配置参数
+     */
+    setSDKConfig(config) {
+        const sdkConfig = Object.assign({}, SDK.config);
+        this._eventEmitter.emit('sdkConfigChange', sdkConfig, config);
+        SDK.config = config;
+    }
+    /**
+     * @description 设置SDK背景
+     * @param type 背景类型
+     * @param value 值
+     */
+    setSDKBackground(type, value) {
+        switch (type) {
+            case 'color': {
+                this.backgroundManager.setColorBackground(value ?? '');
+                break;
+            }
+            case 'image': {
+                if (value) {
+                    this.backgroundManager.setImageBackground(value);
+                }
+                break;
+            }
+            case 'chess-board':
+            case 'dot-board': {
+                this.backgroundManager.applyPreset(type, value);
+                break;
+            }
+        }
+    }
+    /**
+     * @description 创建图层元素
+     * @param spriteInfo 图层元素信息
+     */
+    async addSpriteItem(spriteInfo, scene) {
+        return await this._pageDataUtils.addSpriteItem(spriteInfo, false, scene);
+    }
+    async addVideoItem(videoInfo, scene) {
+        return await this._pageDataUtils.addVideoItem(videoInfo, false, scene);
+    }
+    openPictureCutGizmo() {
+        this._gestureHandler.openPictureCutGizmo();
+        this._gestureHandler.render();
+    }
+    closePictureCutGizmo() {
+        this._gestureHandler.closePictureCutGizmo();
+    }
+    getCutInfo() {
+        return this._gestureHandler.getCutInfo();
+    }
+    setCutBox(min, max) {
+        return this._gestureHandler.setCutBox(min, max);
+    }
+    openPictureExpandGizmo() {
+        this._gestureHandler.openPictureExpandGizmo();
+        this._gestureHandler.render();
+    }
+    closePictureExpandGizmo() {
+        this._gestureHandler.closePictureExpandGizmo();
+    }
+    getExpandInfo() {
+        return this._gestureHandler.getExpandInfo();
+    }
+    setExpandBox(min, max) {
+        return this._gestureHandler.setExpandBox(min, max);
+    }
+    openMaskGizmo(brushSize) {
+        this._gestureHandler.openMaskGizmo(brushSize);
+        this._gestureHandler.render();
+    }
+    clearMaskGizmo() {
+        this._gestureHandler.clearMaskGizmo();
+    }
+    closeMaskGizmo() {
+        this._gestureHandler.closeMaskGizmo();
+    }
+    getMask() {
+        return this._gestureHandler.getMask();
+    }
+    setMaskGizmoConfig(config) {
+        this._gestureHandler.setMaskGizmoConfig(config);
+    }
+    /**
+     * @description 设置蒙版工具模式
+     * @param mode 模式类型：'paint' 笔刷涂抹、'erase' 笔刷逐笔擦除、'box-erase' 框选擦除、'box-paint' 框选涂抹
+     */
+    setMaskGizmoMode(mode) {
+        this._gestureHandler.setMaskGizmoMode(mode);
+    }
+    /**
+     * 撤销蒙版操作
+     * @returns 是否成功撤销
+     */
+    undoMaskGizmo() {
+        return this._gestureHandler.maskGizmoUndo();
+    }
+    /**
+     * 重做蒙版操作
+     * @returns 是否成功重做
+     */
+    redoMaskGizmo() {
+        return this._gestureHandler.maskGizmoRedo();
+    }
+    /**
+     * 检查蒙版是否可以撤销
+     */
+    get canUndoMaskGizmo() {
+        return this._gestureHandler.maskGizmoCanUndo;
+    }
+    /**
+     * 检查蒙版是否可以重做
+     */
+    get canRedoMaskGizmo() {
+        return this._gestureHandler.maskGizmoCanRedo;
+    }
+    /**
+     * 清空蒙版 undoRedo 历史
+     */
+    clearMaskGizmoUndoRedo() {
+        this._gestureHandler.clearMaskGizmoUndoRedo();
+    }
+    /**
+     * 撤销图片裁切操作
+     * @returns 是否成功撤销
+     */
+    undoPictureCutGizmo() {
+        return this._gestureHandler.pictureCutGizmoUndo();
+    }
+    /**
+     * 重做图片裁切操作
+     * @returns 是否成功重做
+     */
+    redoPictureCutGizmo() {
+        return this._gestureHandler.pictureCutGizmoRedo();
+    }
+    /**
+     * 检查图片裁切是否可以撤销
+     */
+    get canUndoPictureCutGizmo() {
+        return this._gestureHandler.pictureCutGizmoCanUndo;
+    }
+    /**
+     * 检查图片裁切是否可以重做
+     */
+    get canRedoPictureCutGizmo() {
+        return this._gestureHandler.pictureCutGizmoCanRedo;
+    }
+    /**
+     * 清空图片裁切 undoRedo 历史
+     */
+    clearPictureCutGizmoUndoRedo() {
+        this._gestureHandler.clearPictureCutGizmoUndoRedo();
+    }
+    openLoadingGizmo(id, options) {
+        this._gestureHandler.openLoadingGizmo(id, options);
+    }
+    updateLoadingGizmo(id, options) {
+        this._gestureHandler.updateLoadingGizmo(id, options);
+    }
+    closeLoadingGizmo(id) {
+        this._gestureHandler.closeLoadingGizmo(id);
+    }
+    /**
+     * @description 元素打组
+     * @param children 子元素ID
+     */
+    groupItems(groupInfo, scene) {
+        return this._pageDataUtils.addGroupItem(groupInfo, scene);
+    }
+    setItemParent(id, parentId) {
+        this._pageDataUtils.setItemParent(id, parentId);
+    }
+    deleteItemParent(id, parentId) {
+        this._pageDataUtils.deleteItemParent(id, parentId);
+    }
+    async addTextItem(textInfo, scene) {
+        return await this._pageDataUtils.addTextItem(textInfo, scene);
+    }
+    async addItemByCreateInfos(createInfos, asyncMode = false) {
+        if (!asyncMode) {
+            const reuslt = await this._pageDataUtils.addItemByCreateInfos(createInfos);
+            return reuslt;
+        }
+        else {
+            const reuslt = await this._pageDataUtils.asyncAddItemByCreateInfos(createInfos);
+            return reuslt;
+        }
+    }
+    deleteItems(idInfo) {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        if (Array.isArray(idInfo)) {
+            idInfo.forEach((id) => {
+                this._pageDataUtils.deleteItem(id);
+            });
+            const resultSelectedIds = this._pageData.activeData.selectedItems.filter(id => !idInfo.includes(id));
+            this._pageData.activeData.selectedItems = [...resultSelectedIds];
+            this._eventEmitter.emit('selectedItemChange', resultSelectedIds);
+        }
+        else {
+            this._pageDataUtils.deleteItem(idInfo);
+            const resultSelectedIds = this._pageData.activeData.selectedItems.filter(id => id !== idInfo);
+            this._pageData.activeData.selectedItems = [...resultSelectedIds];
+            this._eventEmitter.emit('selectedItemChange', resultSelectedIds);
+        }
+        this._pageDataUtils.interactionUtils.refreshViewParam();
+        this._pageDataUtils.interactionUtils.refreshCameraParam();
+        const composition = this._pageDataUtils.getCurrentComposition();
+        this._pageDataUtils.addSDKItemsByItems(this._pageData.items, composition.items);
+        this._eventEmitter.emit('pageDataChange', this._pageData);
+    }
+    getItemCreateInfo(id) {
+        const createInfo = this._pageDataUtils.getItemCreateInfo(id, false);
+        return createInfo;
+    }
+    getItemCreateInfos(ids) {
+        const createInfos = [];
+        ids ??= this._pageData?.items.map(item => item.id) ?? [];
+        ids.forEach((id) => {
+            const createInfo = this._pageDataUtils.getItemCreateInfo(id, true) ?? this.pageData?.items.find(item => item.id === id)?.toCreateInfo(true);
+            if (createInfo) {
+                createInfos.push(createInfo);
+            }
+        });
+        return createInfos;
+    }
+    async createScreenShotSceneByIds(idInfo, time = 0) {
+        const scene = await this._pageDataUtils.createScreenShotSceneByIds(idInfo, async (cardCreateInfo) => {
+            const id = cardCreateInfo.id;
+            if (!id) {
+                return undefined;
+            }
+            return this._htmlOverlayManager?.rasterizeCard(id, {
+                width: cardCreateInfo.property.width,
+                height: cardCreateInfo.property.height,
+                pixelRatio: 2,
+            });
+        });
+        if (!scene) {
+            return undefined;
+        }
+        const mainCompositionSize = scene?.compositions[0]?.previewSize ?? [750, 1624];
+        const thumbnail = await this._screenShot.generate(scene, mainCompositionSize, mainCompositionSize, time);
+        return thumbnail;
+    }
+    async createScreenShotByFrame(id) {
+        const frameItem = this.getSDKItem(id);
+        if (!isFrameItem(frameItem)) {
+            console.warn(`Item ${id} is not frame item, check your input.`);
+            return;
+        }
+        const itemBox = this.getItemBoxById(frameItem.id);
+        const childrenCreateInfos = this.getItemCreateInfos([...frameItem.children]);
+        const targetScene = this._pageDataUtils.createSceneByCreateInfos(childrenCreateInfos, itemBox.getSize().toArray(), '画板', itemBox.getCenter().toArray());
+        if (!targetScene) {
+            console.warn('Target scene is not existed.');
+            return;
+        }
+        const mainCompositionSize = targetScene?.compositions[0]?.previewSize ?? [750, 1624];
+        const thumbnail = await this._screenShot.generate(targetScene, mainCompositionSize, mainCompositionSize, 0);
+        return thumbnail;
+    }
+    async createScreenShotByEffects(id) {
+        const effectsItem = this.getSDKItem(id);
+        if (!isEffectsItem(effectsItem)) {
+            console.warn(`Item ${id} is not a effects item.`);
+            return;
+        }
+        const targetScene = effectsItem.effects;
+        const playerTime = this._pageDataUtils.getEffectsItemPlayTime(id) ?? 0;
+        const mainCompositionSize = [effectsItem.width, effectsItem.height];
+        const thumbnail = await this._screenShot.generate(targetScene, mainCompositionSize, mainCompositionSize, playerTime);
+        return thumbnail;
+    }
+    getChildrenIds(id) {
+        return this._pageDataUtils.getChildrenIds(id);
+    }
+    /**
+     * @description 更新元素在图层中的顺序
+     * @param id 元素ID
+     * @param action 排序操作：BringToFront（置于顶层）、SendToBack（置于底层）、BringForward（上移一层）、SendBackward（下移一层）
+     */
+    updateItemOrder(id, action) {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        const ignoreInteraction = this.getViewProperty(this._pageData.activeData.view ?? 0)?.ignoreInteraction;
+        if (ignoreInteraction) {
+            console.warn('Static scene cannot change.');
+            return;
+        }
+        this._pageDataUtils.updateItemOrder(id, action);
+        this._gestureHandler.render();
+    }
+    /**
+     * @description 导出JSON
+     * @param idInfo 视图序号信息
+     * @returns JSON数组
+     */
+    exportJSON(idInfo) {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        const result = [];
+        if (Array.isArray(idInfo)) {
+            idInfo.forEach(id => {
+                const targetView = this.getViewProperty(id);
+                if (targetView) {
+                    result.push(targetView.scene);
+                }
+                else {
+                    console.warn(`view id ${id} is not existed.`);
+                }
+            });
+        }
+        else if (idInfo !== undefined) {
+            const targetView = this.getViewProperty(idInfo);
+            if (targetView) {
+                result.push(targetView.scene);
+            }
+            else {
+                console.warn(`view id ${idInfo} is not existed.`);
+            }
+        }
+        else {
+            result.push(...this._pageData.viewProperties.map(viewProperty => viewProperty.scene));
+        }
+        return result;
+    }
+    getViewBoxById(id) {
+        return this._pageDataUtils.getViewBoxById(id);
+    }
+    /**
+     * @description 批量设置元素扩展属性
+     * @param id 元素ID
+     * @param extensions 扩展属性对象（支持同时设置多个）
+     * @returns 是否设置成功
+     */
+    setItemExtension(id, extension) {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        const item = this._pageDataUtils.getSDKItem(id);
+        if (!item) {
+            console.warn(`Item ${id} not found`);
+            return false;
+        }
+        Object.entries(extension).forEach(([key, value]) => {
+            item.setExtension(key, value);
+        });
+        this._eventEmitter.emit('pageDataChange', this.pageData);
+        return true;
+    }
+    /**
+     * @description 批量获取元素扩展属性
+     * @param id 元素ID
+     * @param keys 扩展属性名称列表（不传则返回所有扩展属性）
+     * @returns 扩展属性对象
+     */
+    getItemExtension(id, keys) {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        const item = this._pageDataUtils.getSDKItem(id);
+        if (!item) {
+            console.warn(`Item ${id} not found`);
+            return undefined;
+        }
+        if (!keys || keys.length === 0) {
+            return item.getAllExtension();
+        }
+        const result = {};
+        keys.forEach(key => {
+            if (item.hasExtension(key)) {
+                result[key] = item.getExtension(key);
+            }
+        });
+        return result;
+    }
+    /**
+     * @description 删除元素扩展属性（支持批量删除）
+     * @param id 元素ID
+     * @param keys 扩展属性名称列表
+     * @returns 是否删除成功
+     */
+    deleteItemExtensions(id, keys) {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        const item = this._pageDataUtils.getSDKItem(id);
+        if (!item) {
+            console.warn(`Item ${id} not found`);
+            return false;
+        }
+        keys.forEach(key => {
+            item.deleteExtension(key);
+        });
+        this._eventEmitter.emit('pageDataChange', this.pageData);
+        return true;
+    }
+    /**
+     * @description 检查元素是否有指定扩展属性
+     * @param id 元素ID
+     * @param key 扩展属性名称
+     * @returns 是否存在
+     */
+    hasItemExtension(id, key) {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        const item = this._pageDataUtils.getSDKItem(id);
+        if (!item) {
+            return false;
+        }
+        return item.hasExtension(key);
+    }
+    /**
+     * @description 获取元素所有扩展属性的键名列表
+     * @param id 元素ID
+     * @returns 键名数组
+     */
+    getItemExtensionKeys(id) {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        const item = this._pageDataUtils.getSDKItem(id);
+        if (!item) {
+            console.warn(`Item ${id} not found`);
+            return undefined;
+        }
+        return item.getExtensionKeys();
+    }
+    getViewProperty(id) {
+        return this._pageDataUtils.getViewProperty(id);
+    }
+    pageMove(shift) {
+        this._pageDataUtils.pageMove(new Vector2(...shift));
+    }
+    pageZoom(shift, center) {
+        this._pageDataUtils.pageZoom(shift, center ? new Vector2(...center) : undefined);
+    }
+    /**
+     * @description 设置视图缩放工具锁定缩放比例开关
+     * @param state 缩放比例开关
+     */
+    setPictureCutGizmoLockScale(state) {
+        this._gestureHandler.setPictureCutGizmoLockScale(state);
+    }
+    /**
+     * @description 设置视图扩展工具锁定缩放比例开关
+     * @param state 缩放比例开关
+     */
+    setPictureExpandGizmoLockScale(state) {
+        this._gestureHandler.setPictureExpandGizmoLockScale(state);
+    }
+    /**
+     * @description 视图缩放函数
+     * @param shiftParam 视图偏移值
+     */
+    viewportFit(shiftParam, box) {
+        this._pageDataUtils.viewportFit(shiftParam, box);
+    }
+    /**
+     * @description 获取元素包围盒
+     * @param idInfo 元素Id
+     * @returns 元素包围盒
+     */
+    getItemBoxById(idInfo) {
+        return this._pageDataUtils.getItemBoxById(idInfo);
+    }
+    /**
+     * @description 设置元素字体
+     * @param id 元素Id
+     * @param fontFamilyName 字体名称
+     * @param url 字体地址
+     */
+    async setItemFontFamily(id, fontFamilyName, url) {
+        await this._pageDataUtils.setItemFontFamily(id, fontFamilyName, url);
+        this._eventEmitter.emit('itemPropertyChange', { id, propertyKeys: ['fontFamily', 'fontUrl'] });
+    }
+    createSceneByCreateInfos(createInfos, sceneInfo) {
+        return this._pageDataUtils.createSceneByCreateInfos(createInfos, sceneInfo.size, sceneInfo.name);
+    }
+    // 设置图层大小 - 临时方法，用于修改图层元素大小，后续删除 @赤芍
+    setSpriteSize(id, size) {
+        this._pageDataUtils.setSpriteSize(id, size);
+        this._gestureHandler.render();
+    }
+    async setItemPropertyByCreateInfo(createInfo) {
+        await this._pageDataUtils.changeItemPropertyByCreateInfo(createInfo);
+        this._gestureHandler.render();
+    }
+    setTransformGizmoLockScale(state) {
+        this._gestureHandler.setTransformGizmoLockScale(state);
+    }
+    getViewBoxByBox(box) {
+        return this._pageDataUtils.getViewBoxByBox(box);
+    }
+    openSpriteTextEditGizmo(initParam) {
+        this._gestureHandler.openSpriteTextGizmo(initParam);
+        this._gestureHandler.render();
+    }
+    closeSpriteTextEditGizmo() {
+        this._gestureHandler.closeSpriteTextEditGizmo();
+    }
+    setSpriteTextSelectedIndex(id, index) {
+        this._gestureHandler.setSpriteTextSelectedIndex(id, index);
+    }
+    setSpriteTextSelectedText(id, index, text) {
+        this._gestureHandler.setSpriteTextSelectedText(id, index, text);
+    }
+    getBoundingBoxByItemCreateInfo(createInfo) {
+        return this._pageDataUtils.getBoundingBoxByCreateInfo(createInfo);
+    }
+    getBoundingBoxByItemCreateInfos(createInfos) {
+        return this._pageDataUtils.getBoundingBoxByCreateInfos(createInfos);
+    }
+    setSpriteTextChangedState(id, index, hasChanged) {
+        this._gestureHandler.setSpriteTextChangedState(id, index, hasChanged);
+    }
+    setSpriteTextEditState(id, index, isEditing) {
+        this._gestureHandler.setSpriteTextEditState(id, index, isEditing);
+    }
+    getVideoItemPlayTime(id) {
+        return this._pageDataUtils.getVideoItemPlayTime(id);
+    }
+    setVideoItemPlayTime(id, time) {
+        this._pageDataUtils.setVideoItemPlayTime(id, time);
+    }
+    getEffectsItemPlayTime(id) {
+        return this._pageDataUtils.getEffectsItemPlayTime(id);
+    }
+    setEffectsItemPlayTime(id, time) {
+        this._pageDataUtils.setEffectsItemPlayTime(id, time);
+    }
+    setEffectsResource(id, effects) {
+        this._pageDataUtils.setEffectsResource(id, effects);
+    }
+    getPixelPositionByViewPosition(viewPosition) {
+        return this._pageDataUtils.getPixelPositionByViewPosition(viewPosition);
+    }
+    hitTest(x, y) {
+        return this._gestureHandler.selectorGizmo?.hitTest(new Vector2(x, y));
+    }
+    setInteractType(type) {
+        this._gestureHandler.setInteractType(type);
+        this._gestureHandler.render();
+    }
+    getInteractType() {
+        return this._gestureHandler.interactType;
+    }
+    makeItemAlign(type, ids) {
+        this._pageDataUtils.makeItemAlign(type, ids);
+        this._gestureHandler.render();
+    }
+    makeItemDistribute(type, ids) {
+        this._pageDataUtils.makeItemDistribute(type, ids);
+        this._gestureHandler.render();
+    }
+    /**
+     * @description 注册新的卡片类型
+     * @param cardTypeConfig 卡片类型配置（type、label、iconUrl）
+     * @returns 是否注册成功（type 已存在时返回 false）
+     */
+    registerCardType(cardTypeConfig) {
+        const cardTypes = SDK.config.itemConfig.cardConfig.cardTypes;
+        const exists = cardTypes.some(t => t.type === cardTypeConfig.type);
+        if (exists) {
+            console.warn(`CardType "${cardTypeConfig.type}" is already registered.`);
+            return false;
+        }
+        cardTypes.push(cardTypeConfig);
+        return true;
+    }
+    /**
+     * @description 批量注册卡片类型
+     * @param configs 卡片类型配置数组
+     * @returns 成功注册的类型数量
+     */
+    registerCardTypes(configs) {
+        let count = 0;
+        configs.forEach(config => {
+            if (this.registerCardType(config)) {
+                count++;
+            }
+        });
+        return count;
+    }
+    /**
+     * @description 注销卡片类型
+     * @param type 卡片类型标识
+     * @returns 是否注销成功（type 不存在时返回 false）
+     */
+    unregisterCardType(type) {
+        const { cardTypes } = SDK.config.itemConfig.cardConfig;
+        const index = cardTypes.findIndex(t => t.type === type);
+        if (index === -1) {
+            console.warn(`CardType "${type}" is not registered.`);
+            return false;
+        }
+        cardTypes.splice(index, 1);
+        return true;
+    }
+    /**
+     * @description 获取所有已注册的卡片类型
+     * @returns 卡片类型配置数组（只读副本）
+     */
+    getRegisteredCardTypes() {
+        return [...SDK.config.itemConfig.cardConfig.cardTypes];
+    }
+    /**
+     * @description 判断卡片类型是否已注册
+     * @param type 卡片类型标识
+     * @returns 是否已注册
+     */
+    isCardTypeRegistered(type) {
+        return SDK.config.itemConfig.cardConfig.cardTypes.some(t => t.type === type);
+    }
+    /**
+     * @description 按 cardType 从注册表解析卡片的 HTML 渲染配置。
+     * @param item 卡片元素
+     * @returns HTML 渲染配置
+     */
+    resolveCardHTML(item) {
+        const cardTypeConfig = this.resolveCardTypeConfig(item);
+        return cardTypeConfig?.html?.(item);
+    }
+    /**
+     * @description 按 cardType 从注册表解析卡片类型配置。
+     * @param item 卡片元素
+     * @returns 卡片类型配置
+     */
+    resolveCardTypeConfig(item) {
+        return SDK.config.itemConfig.cardConfig.cardTypes.find(t => t.type === item.cardType);
+    }
+    /**
+     * @description 重新解析并挂载指定卡片的 HTML 内容。
+     * @description 当 inline/document 内容依赖 extension 或外部状态变化时，可调用此方法刷新 DOM。
+     * @param id 卡片元素 ID
+     * @returns 是否成功触发刷新
+     */
+    refreshCardHTML(id) {
+        const item = this.getSDKItem(id);
+        if (!isCardItem(item)) {
+            console.warn(`CardItem "${id}" not found.`);
+            return false;
+        }
+        if (!this.resolveCardHTML(item)) {
+            console.warn(`CardItem "${id}" has no registered HTML renderer.`);
+            return false;
+        }
+        this._htmlOverlayManager?.invalidateCardHTML(id);
+        this._htmlOverlayManager?.scheduleRender();
+        return true;
+    }
+    /**
+     * @description 获取指定 HTML 卡片当前 iframe 的 window。
+     * @description 仅 inline/document 或自行渲染 iframe 的 DOM 内容会返回 window。
+     * @param id 卡片元素 ID
+     * @returns HTML iframe window
+     */
+    getHtmlCardWindow(id) {
+        return this._htmlOverlayManager?.getHtmlCardWindow(id);
+    }
+    /**
+     * @description 向指定 HTML 卡片发送增量 patch。
+     * @description 当卡片内容配置了 CardHTMLPatchHandler 时，可用于局部更新 HTML，而不必整卡 refresh。
+     * @param id 卡片元素 ID
+     * @param patch patch 负载，由卡片内容自己的 patch handler 解释
+     * @returns 是否被 patch handler 处理
+     */
+    patchCardHTML(id, patch) {
+        return this._htmlOverlayManager?.patchCardHTML(id, patch) ?? false;
+    }
+    /**
+     * @description 向指定 HTML 卡片 iframe 派发事件。
+     * @description 通过 postMessage 投递事件，跨源/同源行为一致，消息 source 为 vvfx-card-html-event。
+     * @param id 卡片元素 ID
+     * @param type 事件名称
+     * @param detail 事件 detail
+     * @returns 是否成功派发或投递
+     */
+    dispatchHtmlCardEvent(id, type, detail) {
+        return this._htmlOverlayManager?.dispatchHtmlCardEvent(id, type, detail) ?? false;
+    }
+    /**
+     * @description 创建卡片元素
+     * @description 底层以透明 SpriteItem 形式渲染，支持 cardType 属性
+     * @param createInfo 卡片创建信息
+     * @returns 卡片元素ID
+     */
+    addCardItem(createInfo) {
+        return this._pageDataUtils.addCardItem(createInfo);
+    }
+    /**
+     * @description 创建生成器元素
+     * @param createInfo 生成器创建信息
+     * @returns 生成器元素ID
+     */
+    addGeneratorItem(createInfo) {
+        return this._pageDataUtils.addGeneratorItem(createInfo);
+    }
+    /**
+     * @description 创建动效元素
+     * @param effectsInfo 动效创建信息
+     */
+    async addEffectsItem(effectsInfo) {
+        return await this._pageDataUtils.addEffectsItem(effectsInfo);
+    }
+    /**
+     * @description 创建画板元素
+     * @param createInfo 画板创建信息
+     * @returns 画板元素ID
+     */
+    async addFrameItem(createInfo) {
+        return await this._pageDataUtils.addFrameItem(createInfo);
+    }
+    /**
+     * @description 将元素移动到 Frame 中
+     * @param itemIds 要移动的元素ID列表
+     * @param frameId 目标 Frame ID
+     */
+    moveItemsToFrame(itemIds, frameId) {
+        this._pageDataUtils.moveItemsToFrame(itemIds, frameId);
+    }
+    /**
+     * @description 将元素从 Frame 中移出到主场景
+     * @param itemIds 要移动的元素ID列表
+     * @param frameId 源 Frame ID（可选，如果不传则从元素的 parentId 推断）
+     */
+    moveItemsOutOfFrame(itemIds) {
+        this._pageDataUtils.moveItemsOutOfFrame(itemIds);
+    }
+    /**
+     * @description 设置生成器资源，将生成器转换为对应的元素
+     * @param id 生成器元素ID
+     * @param resourceUrl 资源地址
+     * @returns 新的元素ID
+     */
+    async setGeneratorResource(id, resourceUrl) {
+        assertExist(this._pageData, 'You must call SDK#run() first');
+        return this._pageDataUtils.setGeneratorResource(id, resourceUrl);
+    }
+    /**
+     * @description 设置生成器资源（使用 GeneratorResource 对象）
+     * @param resource 生成器资源信息
+     */
+    setGeneratorResourceFromObject(resource) {
+        void this.setGeneratorResource(resource.itemId, resource.url);
+    }
+    /**
+     * @description 设置视频生成器资源
+     * @param resource 视频生成器资源信息
+     */
+    setVideoGeneratorResource(resource) {
+        return this.setGeneratorResource(resource.itemId, resource.url);
+    }
+    /**
+     * @description 设置图层生成器资源
+     * @param resource 图层生成器资源信息
+     */
+    setSpriteGeneratorResource(resource) {
+        return this.setGeneratorResource(resource.itemId, resource.url);
+    }
+    setItemLockState(id, state) {
+        this._pageDataUtils.setItemLockState(id, state);
+    }
+    getItemLockState(id) {
+        return this._pageDataUtils.getItemLockState(id);
+    }
+    openItemCreateGizmo(type) {
+        this._gestureHandler.openItemCreateGizmo(type);
+        this._gestureHandler.render();
+    }
+    closeItemCreateGizmo() {
+        this._gestureHandler.closeItemCreateGizmo();
+    }
+    openTextGizmo(textItemId, mode) {
+        this._gestureHandler.openTextGizmo(textItemId, mode);
+    }
+    closeTextGizmo() {
+        this._gestureHandler.closeTextGizmo();
+    }
+    setItemName(id, name) {
+        this._pageDataUtils.setItemName(id, name);
+    }
+    setSafeAreaPreviewVisible(id, type, visible) {
+        const viewProperty = this.getViewProperty(id);
+        viewProperty?.previewSafeAreas.forEach(safeArea => {
+            if (type in safeArea) {
+                safeArea.visible = visible;
+            }
+        });
+        this._eventEmitter.emit('pageDataChange', this.pageData);
+    }
+    /**
+     * @description 修改画板元素大小
+     * @param id 元素id
+     * @param size 目标大小 [width, height]
+     * @param translation 位置偏移补偿（可选，用于保持拖拽角点固定）
+     */
+    resizeFrameItem(id, size, translation) {
+        const translationVec = translation
+            ? new Vector3(translation[0], translation[1], 0)
+            : undefined;
+        this._pageDataUtils.resizeFrameItem(id, size, translationVec);
+    }
+    /**
+     * @description 对 FrameItem 执行自动布局（当 layoutMode 为 AUTO 时使用）
+     * @param frameId Frame 元素 ID
+     */
+    applyFrameAutoLayout(frameId) {
+        this._pageDataUtils.applyFrameAutoLayout(frameId);
+        void this.setItemProperty({
+            itemId: frameId,
+            type: SDKItemType.FRAME,
+            propertyName: 'layoutMode',
+            propertyValue: FrameLayoutMode.AUTO,
+        });
+    }
+    async autoLayoutPage(param) {
+        await this._pageDataUtils.autoLayoutPage(param);
+        this._gestureHandler.render();
+    }
+}