@vvfx/sdk 0.2.2 → 0.2.4

package/dist/layer-order.d.ts

@@ -0,0 +1,7 @@
+export type SDKCanvasLayers = {
+    container: HTMLElement;
+    playerContainer?: HTMLElement;
+    htmlOverlayLayer?: HTMLElement;
+    gestureCanvas?: HTMLElement;
+};
+export declare function orderSDKCanvasLayers({ container, playerContainer, htmlOverlayLayer, gestureCanvas, }: SDKCanvasLayers): void;

package/dist/sdk-item/card-item.d.ts

@@ -1,4 +1,4 @@
-import type { CardItemProperty, CardCreateInfo, CardHTML } from '../types';
+import type { CardItemProperty, CardCreateInfo } from '../types';
 import { SDKItemType, type CardItemOptions } from './types';
 import { BaseItem } from './base-item';
 /**
@@ -21,16 +21,12 @@ export declare class CardItem extends BaseItem {
      */
     get cardType(): string;
     set cardType(value: string);
-    /**
-     * @description HTML 覆盖层配置
-     */
-    get html(): CardHTML | undefined;
-    set html(value: CardHTML | undefined);
     /**
      * @description 位置
      */
     get position(): [number, number];
     set position(value: [number, number]);
+    get isAutoScale(): boolean;
     /**
      * @description 宽度
      */

package/dist/sdk.d.ts

@@ -1,5 +1,5 @@
 import { Player, spec } from './shared';
-import type { SDKInputParam, PageConfig, PageData, SetItemPropertyParam, ViewProperty, ViewParam, ExportParam, SDKBackgroundType, SpriteCreateInfo, GroupCreateInfo, ItemCreateInfo, TextCreateInfo, ViewportFitShiftParam, SceneCreaetInfo, VideoCreateInfo, GeneratorCreateInfo, GeneratorResource, VideoGeneratorResource, SpriteGeneratorResource, EffectsCreateInfo, FrameCreateInfo, CardCreateInfo, CardItemTransformInfo, PageAutoLayoutParam } from './types';
+import type { SDKInputParam, PageConfig, PageData, SetItemPropertyParam, ViewProperty, ViewParam, ExportParam, SDKBackgroundType, SpriteCreateInfo, GroupCreateInfo, ItemCreateInfo, TextCreateInfo, ViewportFitShiftParam, SceneCreaetInfo, VideoCreateInfo, GeneratorCreateInfo, GeneratorResource, VideoGeneratorResource, SpriteGeneratorResource, EffectsCreateInfo, FrameCreateInfo, CardCreateInfo, CardHTML, CardItemTransformInfo, PageAutoLayoutParam } from './types';
 import { SDKItemType } from './sdk-item/types';
 import type { CardTypeConfig } from './config';
 import { ItemOrderAction } from './types';
@@ -10,7 +10,7 @@ import { Box2, Vector2 } from './math';
 import { GizmoOperation, Operation, UndoRedo } from './service/UndoRedo';
 import { GestureHandlerInteractType, GizmoType, ItemCreateType, SpriteTextInitParam } from './gesture-handler/gizmo';
 import { AlignType, DistributeType } from './utils/types';
-import { SDKItem } from './sdk-item';
+import { SDKItem, type CardItem } from './sdk-item';
 import type { LoadingGizmoItemOptions, LoadingGizmoTip } from './gesture-handler/gizmo/loading-gizmo';
 import type { MaskUndoRedoData } from './gesture-handler/gizmo/mask-gizmo';
 import type { PictureCutUndoRedoData } from './gesture-handler/gizmo/picture-cut-gizmo';
@@ -99,6 +99,7 @@ export declare class SDK {
     on: <E extends "progress" | "loadingItemChange" | "selectedItemChange" | "preSelectedItemChange" | "selectedViewChange" | "pageDataChange" | "zoomChange" | "itemPropertyChange" | "exportProgress" | "exportDone" | "exportComplete" | "sdkConfigChange" | "cutBoxChange" | "expandBoxChange" | "textInput" | "undoRedoChange" | "maskGizmoUndoRedoChange" | "pictureCutGizmoUndoRedoChange" | "viewportTransform" | "itemOnDragStart" | "itemOnDrag" | "itemOnDragEnd" | "spriteTextClick" | "videoPlay" | "itemCreate" | "cardItemTransformChange" | "viewLost" | "viewRebuildFinish">(eventName: E, listener: import("@galacean/effects").EventEmitterListener<SDKEvents[E]>, options?: import("@galacean/effects").EventEmitterOptions) => () => void;
     initPlayer(mode: SDKMode): void;
     setSDKMode(mode: SDKMode): void;
+    private syncCanvasLayerOrder;
     private getInitParam;
     private initExporter;
     private initSDK;
@@ -180,6 +181,7 @@ export declare class SDK {
     cancelExport(): void;
     loadPageData(data: PageData): Promise<void>;
     runByPageData(data: PageData): Promise<void>;
+    runByCreateInfos(createInfos: ItemCreateInfo[]): Promise<void>;
     reloadPageDataByScene(scene: string | spec.JSONScene): Promise<void>;
     /**
      * @description 新增视图数据
@@ -308,9 +310,9 @@ export declare class SDK {
     setMaskGizmoConfig(config: Partial<MaskGizmoConfig>): void;
     /**
      * @description 设置蒙版工具模式
-     * @param mode 模式类型：'paint' 表示涂抹，'erase' 表示擦除
+     * @param mode 模式类型：'paint' 笔刷涂抹、'erase' 笔刷逐笔擦除、'box-erase' 框选擦除、'box-paint' 框选涂抹
      */
-    setMaskGizmoMode(mode: 'paint' | 'erase'): void;
+    setMaskGizmoMode(mode: 'paint' | 'erase' | 'box-erase' | 'box-paint'): void;
     /**
      * 撤销蒙版操作
      * @returns 是否成功撤销
@@ -507,6 +509,49 @@ export declare class SDK {
      * @returns 是否已注册
      */
     isCardTypeRegistered(type: string): boolean;
+    /**
+     * @description 按 cardType 从注册表解析卡片的 HTML 渲染配置。
+     * @param item 卡片元素
+     * @returns HTML 渲染配置
+     */
+    resolveCardHTML(item: CardItem): CardHTML | undefined;
+    /**
+     * @description 按 cardType 从注册表解析卡片类型配置。
+     * @param item 卡片元素
+     * @returns 卡片类型配置
+     */
+    resolveCardTypeConfig(item: CardItem): CardTypeConfig | undefined;
+    /**
+     * @description 重新解析并挂载指定卡片的 HTML 内容。
+     * @description 当 inline/document 内容依赖 extension 或外部状态变化时，可调用此方法刷新 DOM。
+     * @param id 卡片元素 ID
+     * @returns 是否成功触发刷新
+     */
+    refreshCardHTML(id: string): boolean;
+    /**
+     * @description 获取指定 HTML 卡片当前 iframe 的 window。
+     * @description 仅 inline/document 或自行渲染 iframe 的 DOM 内容会返回 window。
+     * @param id 卡片元素 ID
+     * @returns HTML iframe window
+     */
+    getHtmlCardWindow(id: string): Window | null | undefined;
+    /**
+     * @description 向指定 HTML 卡片发送增量 patch。
+     * @description 当卡片内容配置了 CardHTMLPatchHandler 时，可用于局部更新 HTML，而不必整卡 refresh。
+     * @param id 卡片元素 ID
+     * @param patch patch 负载，由卡片内容自己的 patch handler 解释
+     * @returns 是否被 patch handler 处理
+     */
+    patchCardHTML(id: string, patch: unknown): boolean;
+    /**
+     * @description 向指定 HTML 卡片 iframe 派发事件。
+     * @description 通过 postMessage 投递事件，跨源/同源行为一致，消息 source 为 vvfx-card-html-event。
+     * @param id 卡片元素 ID
+     * @param type 事件名称
+     * @param detail 事件 detail
+     * @returns 是否成功派发或投递
+     */
+    dispatchHtmlCardEvent(id: string, type: string, detail?: unknown): boolean;
     /**
      * @description 创建卡片元素
      * @description 底层以透明 SpriteItem 形式渲染，支持 cardType 属性

package/dist/types.d.ts

@@ -82,6 +82,42 @@ export type CardHTMLContentCleanup = (container: HTMLElement) => void;
  * @description Card HTML 覆盖层 DOM 渲染函数。SDK 会传入 overlay 容器；卸载逻辑请使用 content.cleanup。
  */
 export type CardHTMLDOMRenderer = (container: HTMLElement) => void;
+export type CardHTMLPatchContext = {
+    /**
+     * @description 当前卡片元素 ID。
+     */
+    id: string;
+    /**
+     * @description 当前 HTML 覆盖层配置。
+     */
+    html: CardHTML;
+    /**
+     * @description 当前 HTML 内容配置。
+     */
+    content: CardHTMLContent;
+    /**
+     * @description 当前内容挂载容器；未完成挂载时可能不存在。
+     */
+    container?: HTMLElement;
+    /**
+     * @description 当前内容 iframe window；host DOM 内容或尚未完成 iframe 加载时可能不存在。
+     */
+    contentWindow?: Window | null;
+    /**
+     * @description 重新解析并挂载当前卡片 HTML。
+     */
+    refresh: () => void;
+};
+export type CardHTMLPatchHandler = (patch: unknown, context: CardHTMLPatchContext) => boolean | undefined;
+/**
+ * @description SDK#dispatchHtmlCardEvent 通过 postMessage 投递给 HTML iframe 的消息结构。
+ */
+export type CardHTMLWindowEventMessage = {
+    source: 'vvfx-card-html-event';
+    type: string;
+    detail?: unknown;
+    payload?: unknown;
+};
 /**
  * @description Card HTML 单文件字符串内容。SDK 会通过 iframe srcdoc 渲染。
  */
@@ -94,6 +130,18 @@ export type CardHTMLInlineContent = {
      * @description HTML 字符串内容
      */
     html: string;
+    /**
+     * @description iframe sandbox 配置；true/undefined 使用 SDK 默认沙箱 allow-scripts。
+     */
+    sandbox?: boolean | string;
+    /**
+     * @description 是否允许 iframe 内 a[href] 执行默认跳转；默认 false，会阻止 Agent 生成 HTML 中的链接把卡片导航走。
+     */
+    allowAnchorNavigation?: boolean;
+    /**
+     * @description 增量 patch 处理器。可用于将运行时事件派发给 iframe，或直接更新外部状态后触发刷新；返回 false 表示未处理，返回 true 或无返回值表示已接收。
+     */
+    patch?: CardHTMLPatchHandler;
     /**
      * @description 内容卸载时调用的清理函数；SDK 会传入当前内容挂载容器。
      */
@@ -115,6 +163,10 @@ export type CardHTMLDOMRendererContent = {
      * @description DOM 渲染函数
      */
     render: CardHTMLDOMRenderer;
+    /**
+     * @description 增量 patch 处理器。适合 React/Vue/原生 DOM 内容接收局部更新；返回 false 表示未处理，返回 true 或无返回值表示已接收。
+     */
+    patch?: CardHTMLPatchHandler;
     /**
      * @description 内容卸载时调用的清理函数；SDK 会传入 render 接收到的同一个容器。
      */
@@ -161,6 +213,10 @@ export type CardHTMLDocumentContent = {
      * @description iframe sandbox 配置；true/undefined 使用 SDK 默认沙箱 allow-scripts；false 不加 sandbox，风险较高，不建议用于不可信内容。
      */
     sandbox?: boolean | string;
+    /**
+     * @description 是否允许 iframe 内 a[href] 执行默认跳转；默认 false，会阻止 Agent 生成 HTML 中的链接把卡片导航走。
+     */
+    allowAnchorNavigation?: boolean;
     /**
      * @description 是否允许 iframe 通过 postMessage 与宿主通信；默认 false。
      */
@@ -169,6 +225,10 @@ export type CardHTMLDocumentContent = {
      * @description iframe 消息回调。仅接收来自当前 iframe 且 source 为 vvfx-card-html 的消息。
      */
     onMessage?: (message: CardHTMLDocumentMessage) => void;
+    /**
+     * @description 增量 patch 处理器。可结合 contentWindow.postMessage 投递给文档运行时；返回 false 表示未处理，返回 true 或无返回值表示已接收。
+     */
+    patch?: CardHTMLPatchHandler;
     /**
      * @description 内容卸载时调用的清理函数；SDK 会传入当前内容挂载容器。
      */
@@ -204,6 +264,17 @@ export type CardHTMLShellContent = {
      */
     render: CardHTMLShellRenderer;
 };
+export type CardHTMLRootStyle = Record<string, string | number | undefined>;
+export type CardHTMLRootConfig = {
+    /**
+     * @description 追加到 HTML 内容根节点的 className。
+     */
+    className?: string;
+    /**
+     * @description 应用到 HTML 内容根节点的内联样式。
+     */
+    style?: CardHTMLRootStyle;
+};
 /**
  * @description Card HTML 覆盖层配置。
  */
@@ -216,23 +287,19 @@ export type CardHTML = {
      * @description HTML 外壳，用于定制承载 content 的容器。
      */
     shell?: CardHTMLShellContent;
+    /**
+     * @description HTML 内容根节点样式配置，用于按内容实例设置 className 或内联 style。
+     */
+    root?: CardHTMLRootConfig;
 };
 /**
  * @description Card 卡片元素属性
  */
 export type CardItemProperty = BaseItemProperty & {
     /**
-     * @description 卡片类型（动态配置，需在 SDK.config.itemConfig.cardConfig.cardTypes 中注册）
+     * @description 卡片类型（动态配置，需通过 SDK.registerCardType/registerCardTypes 注册）
      */
     cardType: string;
-    /**
-     * @description 是否根据 HTML 挂载内容的自然高度自动更新卡片高度
-     */
-    autoHeight?: boolean;
-    /**
-     * @description HTML 覆盖层配置；存在该字段时由 DOM overlay 渲染
-     */
-    html?: CardHTML;
 };
 /**
  * @description Frame 画板元素布局模式
@@ -468,6 +535,10 @@ export type PageAutoLayoutParam = {
      * @description 自动布局间隔
      */
     gap?: number;
+    /**
+     * 视图自适应偏移参数
+     */
+    shift?: ViewportFitShiftParam;
 };
 /**
  * @description 页面配置
@@ -927,7 +998,7 @@ export type CardItemTransformInfo = {
     size: [number, number];
 };
 /**
- * @description 卡片类型（动态配置，需在 SDK.config.itemConfig.cardConfig.cardTypes 中注册）
+ * @description 卡片类型（动态配置，需通过 SDK.registerCardType/registerCardTypes 注册）
  */
 export type CardType = string;
 /**
@@ -970,10 +1041,6 @@ export type CardCreateInfo = {
          * @description 卡片元素像素高度
          */
         height: number;
-        /**
-         * @description 是否根据 HTML 挂载内容的自然高度自动更新卡片高度
-         */
-        autoHeight?: boolean;
         /**
          * @description 卡片元素位置
          */
@@ -986,10 +1053,6 @@ export type CardCreateInfo = {
          * @description 卡片元素缩放
          */
         scale?: [number, number];
-        /**
-         * @description HTML 覆盖层配置；存在该字段时由 DOM overlay 渲染
-         */
-        html?: CardHTML;
     };
 };
 /**

package/dist/utils/page-data-utils.d.ts

@@ -88,6 +88,10 @@ export declare class PageDataUtils {
      *   2. 单个元素多个属性: { itemId, type, property }
      */
     setItemProperty<T extends SDKItemType>(param: SetItemPropertyParam<T>): Promise<void>;
+    /**
+     * @description 设置元素extension字段
+     */
+    setItemExtension(itemId: string, extension: Record<string, any>): void;
     /**
      * @description 场景 1: 设置单个元素的单个属性
      */
@@ -284,6 +288,15 @@ export declare class PageDataUtils {
     setItemFontFamily(id: string, fontFamilyName: string, url: string): Promise<void>;
     changeItemPropertyByCreateInfo(itemCreateInfo: ItemCreateInfo | ItemCreateInfo[]): Promise<void>;
     getViewBoxByBox(box: Box2): Box2;
+    /**
+     * @description 快照当前所有视频元素的播放状态（播放/暂停 + 当前播放进度），用于属性刷新后恢复，
+     *  避免设置属性导致全量视频被自动播放或进度被重置回 0s
+     */
+    private snapshotVideoPlayStates;
+    /**
+     * @description 按快照恢复视频元素的播放状态（先 pause 再 seek，最后按原状态 play/pause，避免进度抖动）
+     */
+    private restoreVideoPlayStates;
     playVideoItem(id?: string): void;
     pauseVideoItem(id?: string): void;
     playEffectsItem(id?: string): void;
@@ -333,6 +346,13 @@ export declare class PageDataUtils {
      * @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 位置偏移补偿（可选，用于保持拖拽角点固定）
+     */
+    resizeCardItem(id: string, size: spec.vec2, translation?: Vector3): void;
     /**
      * @description 修改画板元素大小
      * @param id 元素id

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vvfx/sdk",
   "description": "TODO",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "main": "./dist/index.mjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -15,15 +15,6 @@
       "require": "./dist/index.mjs"
     }
   },
-  "scripts": {
-    "prebuild": "pnpm clean",
-    "build": "pnpm build:declaration && pnpm build:module",
-    "build:module": "rollup -c --bundleConfigAsCjs",
-    "build:declaration": "tsc -d --emitDeclarationOnly",
-    "clean": "rimraf dist *.tsbuildinfo",
-    "test": "vitest run",
-    "prepublishOnly": "pnpm build"
-  },
   "dependencies": {
     "@ffmpeg/ffmpeg": "0.12.15",
     "@ffmpeg/util": "0.12.2",
@@ -72,5 +63,13 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "prebuild": "pnpm clean",
+    "build": "pnpm build:declaration && pnpm build:module",
+    "build:module": "rollup -c --bundleConfigAsCjs",
+    "build:declaration": "tsc -p tsconfig.build.json",
+    "clean": "rimraf dist *.tsbuildinfo",
+    "test": "vitest run"
   }
-}
+}