@vvfx/sdk 0.1.19-alpha.8 → 0.2.0

package/dist/src/types.d.ts

@@ -0,0 +1,1298 @@
+import type { spec } from './shared';
+import { SizeAdaptDirection } from './size-adapte';
+import type { ExportMediaItemOptions } from './exporter';
+import { SDKItemType } from './sdk-item/types';
+import { SDKItem } from './sdk-item';
+import { GlobalLayoutMode } from './utils';
+export type BaseItemProperty = {
+    position: [number, number];
+    rotation: [number, number, number];
+    scale: [number, number];
+    width: number;
+    height: number;
+};
+export type SpriteItemProperty = BaseItemProperty & {
+    image: string;
+};
+export type GroupItemProperty = BaseItemProperty & {
+    children: string[];
+};
+export type TextItemProperty = BaseItemProperty & {
+    fontFamily: string;
+    color: [number, number, number, number];
+    fontWeight: spec.TextWeight;
+    text: string;
+    textAlign: spec.TextAlignment;
+    fontSize: number;
+    fontStyle: spec.FontStyle;
+    lineHeight: number;
+    outlineColor?: spec.vec4;
+    outlineWidth?: number;
+    /**
+     * @description 描边开关
+     */
+    outlineEnabled?: boolean;
+    /**
+     * @description 文本字间距
+     */
+    letterSpacing?: number;
+    fontUrl?: string;
+};
+export type VideoItemProperty = BaseItemProperty & {
+    video: string;
+    /**
+   * @description 是否静音
+   */
+    muted?: boolean;
+    /**
+     * @description 是否为透明视频
+     */
+    transparent?: boolean;
+    /**
+     * @description 播放速率
+     */
+    playbackRate?: number;
+    /**
+     * @description 音量
+     */
+    volume?: number;
+};
+/**
+ * @description Generator 表单属性
+ */
+export type GeneratorItemProperty = BaseItemProperty & {
+    /**
+     * @description 生成器类型
+     */
+    generatorType: 'image' | 'video';
+};
+export type EffectsItemProperty = BaseItemProperty & {
+    effects: string;
+    children?: string[];
+};
+/**
+ * @description Card HTML 覆盖层清理函数。
+ */
+export type CardHTMLRenderCleanup = () => void;
+/**
+ * @description Card HTML 内容清理函数。SDK 会传入当前内容挂载容器。
+ */
+export type CardHTMLContentCleanup = (container: HTMLElement) => void;
+/**
+ * @description Card HTML 覆盖层 DOM 渲染函数。SDK 会传入 overlay 容器；卸载逻辑请使用 content.cleanup。
+ */
+export type CardHTMLDOMRenderer = (container: HTMLElement) => void;
+/**
+ * @description Card HTML 单文件字符串内容。SDK 会通过 iframe srcdoc 渲染。
+ */
+export type CardHTMLInlineContent = {
+    /**
+     * @description 内容类型标识
+     */
+    kind: 'inline';
+    /**
+     * @description HTML 字符串内容
+     */
+    html: string;
+    /**
+     * @description 内容卸载时调用的清理函数；SDK 会传入当前内容挂载容器。
+     */
+    cleanup?: CardHTMLContentCleanup;
+};
+/**
+ * @description Card HTML DOM 渲染内容。用于挂载 React/Vue/原生 DOM 等组件。
+ */
+export type CardHTMLDOMRendererContent = {
+    /**
+     * @description 内容类型标识
+     */
+    kind: 'dom';
+    /**
+     * @description DOM 挂载目标。host 为宿主 DOM，iframe 为隔离文档 DOM；默认 host。
+     */
+    target?: 'host' | 'iframe';
+    /**
+     * @description DOM 渲染函数
+     */
+    render: CardHTMLDOMRenderer;
+    /**
+     * @description 内容卸载时调用的清理函数；SDK 会传入 render 接收到的同一个容器。
+     */
+    cleanup?: CardHTMLContentCleanup;
+};
+/**
+ * @description Card HTML 文档到宿主的消息。仅当 allowHostMessaging 为 true 时 SDK 才会接收。
+ */
+export type CardHTMLDocumentMessage = {
+    /**
+     * @description 消息来源标识，必须为 vvfx-card-html。
+     */
+    source: 'vvfx-card-html';
+    /**
+     * @description 业务消息类型。
+     */
+    type: string;
+    /**
+     * @description 业务消息负载。
+     */
+    payload?: unknown;
+};
+/**
+ * @description Card HTML 文档内容。用于承载完整 HTML 页面或多文件 HTML 产物。
+ */
+export type CardHTMLDocumentContent = {
+    /**
+     * @description 内容类型标识
+     */
+    kind: 'document';
+    /**
+     * @description 入口文件路径，例如 index.html
+     */
+    entry: string;
+    /**
+     * @description 文件内容表，key 为相对路径，value 为文件内容
+     */
+    files: Record<string, string>;
+    /**
+     * @description 资源解析基准路径，用于后续处理远程或本地资源引用
+     */
+    baseUrl?: string;
+    /**
+     * @description iframe sandbox 配置；true/undefined 使用 SDK 默认沙箱 allow-scripts；false 不加 sandbox，风险较高，不建议用于不可信内容。
+     */
+    sandbox?: boolean | string;
+    /**
+     * @description 是否允许 iframe 通过 postMessage 与宿主通信；默认 false。
+     */
+    allowHostMessaging?: boolean;
+    /**
+     * @description iframe 消息回调。仅接收来自当前 iframe 且 source 为 vvfx-card-html 的消息。
+     */
+    onMessage?: (message: CardHTMLDocumentMessage) => void;
+    /**
+     * @description 内容卸载时调用的清理函数；SDK 会传入当前内容挂载容器。
+     */
+    cleanup?: CardHTMLContentCleanup;
+};
+/**
+ * @description Card HTML 覆盖层内容。
+ */
+export type CardHTMLContent = CardHTMLInlineContent | CardHTMLDOMRendererContent | CardHTMLDocumentContent;
+export type CardHTMLShellRendererResult = HTMLElement | {
+    contentContainer: HTMLElement;
+    cleanup?: CardHTMLRenderCleanup;
+};
+export type CardHTMLShellRendererContext = {
+    /**
+     * @description 当前 shell 承载的 HTML 内容。
+     */
+    content: CardHTMLContent;
+};
+export type CardHTMLShellRenderer = (container: HTMLElement, context: CardHTMLShellRendererContext) => CardHTMLShellRendererResult;
+/**
+ * @description Card HTML 外壳内容。用于定制承载 HTML 内容的容器。
+ */
+export type CardHTMLShellContent = {
+    /**
+     * @description 内容类型标识
+     */
+    kind: 'dom';
+    /**
+     * @description DOM 外壳渲染函数，必须返回用于挂载 content 的容器。
+     * @description shell 内需要在非编辑态响应 hover/click 的控件，可标记 data-vvfx-html-shell-interactive="true"。
+     * @description SDK 会在该控件上同步 data-vvfx-html-shell-interactive-hover 与 data-vvfx-html-shell-interactive-active 状态；具体 UI 展示和业务行为由 shell 自行实现。
+     */
+    render: CardHTMLShellRenderer;
+};
+/**
+ * @description Card HTML 覆盖层配置。
+ */
+export type CardHTML = {
+    /**
+     * @description HTML 内容，承接 inline/dom/document 等内容类型。
+     */
+    content: CardHTMLContent;
+    /**
+     * @description HTML 外壳，用于定制承载 content 的容器。
+     */
+    shell?: CardHTMLShellContent;
+};
+/**
+ * @description Card 卡片元素属性
+ */
+export type CardItemProperty = BaseItemProperty & {
+    /**
+     * @description 卡片类型（动态配置，需在 SDK.config.itemConfig.cardConfig.cardTypes 中注册）
+     */
+    cardType: string;
+    /**
+     * @description 是否根据 HTML 挂载内容的自然高度自动更新卡片高度
+     */
+    autoHeight?: boolean;
+    /**
+     * @description HTML 覆盖层配置；存在该字段时由 DOM overlay 渲染
+     */
+    html?: CardHTML;
+};
+/**
+ * @description Frame 画板元素布局模式
+ */
+export declare enum FrameLayoutMode {
+    AUTO = "auto",
+    FREE = "free"
+}
+/**
+ * @description 自动布局配置
+ */
+export type AutoLayoutConfig = {
+    /**
+     * @description 单行最大宽度（像素），超过后自动换行。未设置时不限制
+     */
+    maxRowWidth?: number;
+    /**
+     * @description 最大行数限制。未设置时不限制
+     */
+    maxRowCount?: number;
+};
+/**
+ * @description 元素在自动布局中的位置信息
+ */
+export type LayoutInfo = {
+    /**
+     * @description 所在行号（可为小数）
+     * 整数部分：主行号（0, 1, 2...）
+     * 小数部分：分行后的子行号（如 1.5 表示第1行的第5个子行）
+     * 仅支持两层（即小数部分为 0-9）
+     */
+    row: number;
+    /**
+     * @description 所在列号（必须为整数）
+     */
+    column: number;
+    /**
+     * @description 元素在布局中的位置（相对于画板左上角，可选）
+     */
+    position?: [number, number];
+};
+/**
+ * @description Frame 画板元素属性
+ */
+export type FrameItemProperty = BaseItemProperty & {
+    /**
+     * @description 布局模式: auto - 自动布局, free - 自由布局
+     */
+    layoutMode: FrameLayoutMode;
+    /**
+     * @description 子元素ID数组
+     */
+    children: string[];
+    /**
+     * @description 自动布局配置
+     */
+    autoLayoutConfig?: AutoLayoutConfig;
+    /**
+     * @description 子元素布局位置信息（用于自动布局）
+     * key: 子元素ID, value: 元素的位置信息
+     */
+    layoutInfos?: Record<string, LayoutInfo>;
+};
+/**
+ * @description BaseItem 基础属性键名
+ */
+export type BaseItemPropertyKey = 'name' | 'duration' | 'delay' | 'endBehavior' | 'visible' | 'isLocked' | 'parentId';
+/**
+ * @description BaseItem 基础属性值类型映射
+ */
+export type BaseItemPropertyValueMap = {
+    name: string;
+    duration: number;
+    delay: number;
+    endBehavior: spec.EndBehavior;
+    visible: boolean;
+    isLocked: boolean;
+    parentId?: string;
+};
+/**
+ * @description Item 类型与 Property 类型的映射
+ */
+export type ItemPropertyMap = {
+    [SDKItemType.SPRITE]: SpriteItemProperty;
+    [SDKItemType.TEXT]: TextItemProperty;
+    [SDKItemType.VIDEO]: VideoItemProperty;
+    [SDKItemType.GROUP]: GroupItemProperty;
+    [SDKItemType.GENERATOR]: GeneratorItemProperty;
+    [SDKItemType.EFFECTS]: EffectsItemProperty;
+    [SDKItemType.FRAME]: FrameItemProperty;
+    [SDKItemType.CARD]: CardItemProperty;
+};
+/**
+ * @description 场景1：单个元素单个属性设置
+ * 支持设置 BaseItem 基础属性或具体 Item 类型的 property 属性
+ */
+export type SetSingleItemSinglePropertyParam<T extends SDKItemType = SDKItemType> = {
+    itemId: string;
+    type: T;
+    propertyName: BaseItemPropertyKey;
+    propertyValue: BaseItemPropertyValueMap[BaseItemPropertyKey];
+} | {
+    itemId: string;
+    type: T;
+    propertyName: keyof ItemPropertyMap[T];
+    propertyValue: ItemPropertyMap[T][keyof ItemPropertyMap[T]];
+};
+/**
+ * @description 场景2：单个元素多个属性设置
+ * 同时设置多个 BaseItem 属性或 property 属性
+ */
+export type SetSingleItemMultiplePropertiesParam<T extends SDKItemType = SDKItemType> = {
+    itemId: string;
+    type: T;
+    property: Partial<Record<BaseItemPropertyKey, BaseItemPropertyValueMap[BaseItemPropertyKey]>> & Partial<Record<keyof ItemPropertyMap[T], ItemPropertyMap[T][keyof ItemPropertyMap[T]]>>;
+};
+/**
+ * @description 设置元素属性的统一参数类型
+ * 支持两种场景：单元素单属性、单元素多属性
+ */
+export type SetItemPropertyParam<T extends SDKItemType = SDKItemType> = SetSingleItemSinglePropertyParam<T> | SetSingleItemMultiplePropertiesParam<T>;
+export type SDKOptions = {
+    /** 导出视频时，是否开启转码日志 */
+    loggerInExportVideoTranscoding?: boolean;
+};
+export type SDKInputParam = SDKTemplateInputParam | SDKEditorInputParam;
+/**
+ * @description SDK入参
+ */
+export type SDKTemplateInputParam = {
+    /**
+     * @description JSON地址
+     */
+    scene: string | spec.JSONScene;
+    /**
+     * @description SDK模式 - 模板编辑模式
+     */
+    mode: 'template';
+    /**
+     * @description 视图参数
+     */
+    viewParams?: ViewParam[];
+    /**
+     * @description 页面属性
+     */
+    options: PageOptions;
+};
+export type SDKEditorInputParam = {
+    /**
+     * @description SDK模式 - 编辑器模式
+     */
+    mode: 'editor';
+};
+export type SDKInitParam = {
+    scene: spec.JSONScene;
+    /**
+     * @description 视图参数
+     */
+    viewParams: ViewParam[];
+    /**
+     * @description 页面属性
+     */
+    options: PageOptions;
+};
+/**
+ * @description 页面属性
+ */
+export type PageOptions = {
+    /**
+     * @description 同步模式开关
+     */
+    asyncMode: boolean;
+    /**
+     * @description 安全区展示开关
+     */
+    safeAreaPreview: boolean;
+    /**
+     * @description 吸附开关
+     */
+    adsorption: boolean;
+};
+/**
+ * @description 页面数据
+ */
+export type PageData = {
+    /**
+     * @description 基础场景数据
+     */
+    scene: spec.JSONScene;
+    /**
+     * @description 页面属性
+     */
+    property: PageProperty;
+    /**
+     * @description 视图属性
+     */
+    viewProperties: ViewProperty[];
+    /**
+     * @description 活跃数据
+     */
+    activeData: ActiveData;
+    /**
+     * @description 元素数据
+     */
+    items: SDKItem[];
+    /**
+     * @description 视图当前时间
+     */
+    time: number;
+    /**
+     * @description 是否处于播放态
+     */
+    playing: boolean;
+};
+/**
+ * @description 页面自动布局参数
+ */
+export type PageAutoLayoutParam = {
+    /**
+     * @description 自动布局模式
+     */
+    mode?: GlobalLayoutMode;
+    /**
+     * @description 选中元素【无输入值时，页面内所有元素排布】
+     * 如果是选中元素自动排布，则保证包围盒左上角点位置相同
+     */
+    ids?: string[];
+    /**
+     * @description 排布后是否聚焦元素，默认开启
+     */
+    focus?: boolean;
+    /**
+     * @description 自动布局间隔
+     */
+    gap?: number;
+};
+/**
+ * @description 页面配置
+ */
+export type PageConfig = {
+    /**
+     * @description 出血区域展示开关
+     */
+    safeAreaPreview: boolean;
+    /**
+     * @description 缩放值
+     */
+    zoom: number;
+    /**
+     * @description 吸附开关
+     */
+    adsorption: boolean;
+    /**
+     * @description 同步开关
+     */
+    asyncMode: boolean;
+    /**
+     * @description 画布移动
+     */
+    translation: spec.vec2;
+};
+/**
+ * @description 页面属性
+ */
+export type PageProperty = {
+    /**
+     * @description 出血区域展示开关
+     */
+    safeAreaPreview: boolean;
+    /**
+     * @description 缩放值
+     */
+    zoom: number;
+    /**
+     * @description 偏移值
+     */
+    translation: [number, number];
+    /**
+     * @description 吸附开关
+     */
+    adsorption: boolean;
+    /**
+     * @description 同步开关
+     */
+    asyncMode: boolean;
+};
+/**
+ * @description 视图创建参数
+ */
+export type ViewParam = {
+    /**
+     * @description 页面尺寸
+     */
+    size?: [number, number];
+    /**
+     * @description 出血区参数
+     */
+    safeArea?: [number, number, number, number];
+    /**
+     * @description 自适应方向 - 默认根据视图宽高决定
+     */
+    adaptionDirection?: SizeAdaptDirection;
+    /**
+     * @description 自定义出血区 - 用于展示
+     */
+    previewSafeAreas?: PreviewSafeAreaParam[];
+    /**
+     * @description 导出参数
+     */
+    export: ExportParam;
+};
+/**
+ * @description 导出参数
+ */
+export type ExportParam = {
+    /**
+     * @description 视频名称
+     */
+    name?: string;
+} & Omit<ExportMediaItemOptions, 'scene' | 'size'>;
+/**
+ * @description 视图属性
+ */
+export type ViewProperty = {
+    /**
+     * @description 视图ID
+     */
+    id: number;
+    /**
+     * @description 视图宽高
+     */
+    size: [number, number];
+    /**
+     * @description 出血区数据
+     */
+    safeArea: [number, number, number, number];
+    /**
+     * @description 自定义出血区数据
+     */
+    previewSafeAreas: PreviewSafeAreaParam[];
+    /**
+     * @description 视图场景数据
+     */
+    scene: spec.JSONScene;
+    /**
+     * @description 导出参数
+     */
+    export: ExportParam;
+    /**
+     * @description 忽略交互 - 仅供展示
+     */
+    ignoreInteraction: boolean;
+};
+/**
+ * @description 自定义出血区数据
+ */
+export type PreviewSafeAreaParam = {
+    /**
+     * @description 出血区包围盒 [left top width height]
+     */
+    box: [number, number, number, number];
+    /**
+     * @description 出血区色块颜色 默认为 [255, 255, 255, 0.3]
+     */
+    color?: [number, number, number, number];
+    /**
+     * @description 出血区图像
+     */
+    url?: string;
+    /**
+     * @description 出血区是否可见
+     */
+    visible?: boolean;
+};
+/**
+ * @description 页面活跃数据
+ */
+export type ActiveData = {
+    /**
+     * @description 视图ID
+     */
+    view?: number;
+    /**
+     * @description 选中元素
+     */
+    selectedItems: string[];
+    /**
+     * @description 预选中元素
+     */
+    preSelectedItem?: string;
+    /**
+     * @description 执行中元素
+     */
+    loadingItems?: string[];
+};
+/**
+ * @description Generator 扩展配置
+ * 用于 GeneratorMetadataManager 返回的数据格式
+ */
+export type GeneratorExtension = {
+    /**
+     * @description 扩展类型标识
+     */
+    type: 'generator';
+    /**
+     * @description Generator 子类型
+     */
+    generatorType: 'sprite' | 'video';
+    /**
+     * @description 填充颜色 [r, g, b, a]，范围 0-1
+     */
+    fillColor: [number, number, number, number];
+    /**
+     * @description 图标 URL
+     */
+    iconUrl: string;
+};
+export type SDKBackgroundType = 'color' | 'image' | 'chess-board' | 'dot-board';
+/**
+ * @description 图层创建信息
+ */
+export type SpriteCreateInfo = {
+    type: SDKItemType.SPRITE;
+    /**
+     * @description 图层名称
+     */
+    name?: string;
+    /**
+     * @description 元素id
+     */
+    id?: string;
+    /**
+     * @description 父节点id
+     */
+    parentId?: string;
+    /**
+     * @description 扩展属性
+     */
+    extension?: Record<string, any>;
+    /**
+     * @description 元素属性
+     */
+    property: {
+        /**
+         * @description 图片资源地址 | 数据
+         */
+        image?: string;
+        /**
+         * @description 图层像素宽度
+         */
+        width: number;
+        /**
+         * @description 图层像素高度
+         */
+        height: number;
+        /**
+         * @description 元素位置
+         */
+        position: [number, number];
+        /**
+         * @description 元素旋转 z | [x, y, z]
+         */
+        rotation?: number | [number, number, number];
+        /**
+         * @description 元素缩放
+         */
+        scale?: [number, number];
+    };
+};
+/**
+ * @description 组 元素创建信息
+ */
+export type GroupCreateInfo = {
+    type: SDKItemType.GROUP;
+    /**
+     * @description 元素id
+     */
+    id?: string;
+    /**
+     * @description 父节点id
+     */
+    parentId?: string;
+    /**
+     * @description 元素名称
+     */
+    name?: string;
+    /**
+     * @description 扩展属性
+     */
+    extension?: Record<string, any>;
+    /**
+     * @description 元素属性
+     */
+    property: {
+        /**
+         * @description 元素位置
+         */
+        position?: [number, number];
+        /**
+         * @description 元素旋转 z | [x, y, z]
+         */
+        rotation?: number | [number, number, number];
+        /**
+         * @description 元素缩放
+         */
+        scale?: [number, number];
+        /**
+         * @description 子元素id
+         */
+        children: string[];
+    };
+};
+/**
+ * @description 文本创建信息
+ */
+export type TextCreateInfo = {
+    type: SDKItemType.TEXT;
+    /**
+     * @description 元素id
+     */
+    id?: string;
+    /**
+     * @description 父节点id
+     */
+    parentId?: string;
+    /**
+     * @description 元素名称
+     */
+    name?: string;
+    /**
+     * @description 扩展属性
+     */
+    extension?: Record<string, any>;
+    /**
+     * @description 元素属性
+     */
+    property: {
+        /**
+         * @description 文本宽度
+         */
+        width: number;
+        /**
+         * @description 文本高度
+         */
+        height?: number;
+        /**
+         * @description 元素位置
+         */
+        position: [number, number];
+        /**
+         * @description 元素旋转 z | [x, y, z]
+         */
+        rotation?: number | [number, number, number];
+        /**
+         * @description 元素缩放
+         */
+        scale?: [number, number];
+        /**
+         * @description 单行高度
+         */
+        lineHeight: number;
+        /**
+         * @description 字体名称
+         */
+        fontFamily: string;
+        /**
+         * @description 文字大小
+         */
+        fontSize: number;
+        /**
+         * @description 字重
+         */
+        fontWeight?: spec.TextWeight;
+        /**
+         * @description 字体格式
+         */
+        fontStyle?: spec.FontStyle;
+        /**
+         * @description 对齐方式
+         */
+        textAlign?: spec.TextAlignment;
+        /**
+         * @description 文本信息
+         */
+        text: string;
+        /**
+         * @description 填充色
+         */
+        color: spec.vec4;
+        /**
+         * @description 描边色
+         */
+        outlineColor?: spec.vec4;
+        /**
+         * @description 描边宽度
+         */
+        outlineWidth?: number;
+        /**
+         * @description 描边开关
+         */
+        outlineEnabled?: boolean;
+        /**
+         * @description 字体文件地址
+         */
+        fontUrl?: string;
+        /**
+         * @description 文本字间距
+         */
+        letterSpacing?: number;
+    };
+};
+/**
+ * @description 视频创建信息
+ */
+export type VideoCreateInfo = {
+    type: SDKItemType.VIDEO;
+    /**
+     * @description 视频名称
+     */
+    name?: string;
+    /**
+     * @description 元素id
+     */
+    id?: string;
+    /**
+     * @description 父节点id
+     */
+    parentId?: string;
+    /**
+     * @description 扩展属性
+     */
+    extension?: Record<string, any>;
+    /**
+     * @description 元素属性
+     */
+    property: {
+        /**
+         * @description 视频资源地址 | 数据
+         */
+        video?: string;
+        /**
+         * @description 视频元素像素宽度
+         */
+        width: number;
+        /**
+         * @description 视频元素像素高度
+         */
+        height: number;
+        /**
+         * @description 视频元素位置
+         */
+        position: [number, number];
+        /**
+         * @description 视频元素旋转 z | [x, y, z]
+         */
+        rotation?: number | [number, number, number];
+        /**
+         * @description 视频元素缩放
+         */
+        scale?: [number, number];
+        /**
+         * @description 是否静音
+         */
+        muted?: boolean;
+        /**
+         * @description 是否为透明视频
+         */
+        transparent?: boolean;
+        /**
+         * @description 播放速率
+         */
+        playbackRate?: number;
+        /**
+         * @description 音量
+         */
+        volume?: number;
+    };
+};
+/**
+ * @description 卡片元素变换信息（视口坐标系）
+ */
+export type CardItemTransformInfo = {
+    /** 卡片元素 ID */
+    id: string;
+    /** 卡片元素名称 */
+    name: string;
+    /** 卡片类型 */
+    cardType: string;
+    /** 视口坐标系中的左上角位置 [x, y] */
+    position: [number, number];
+    /** 视口坐标系中的宽高 [width, height] */
+    size: [number, number];
+};
+/**
+ * @description 卡片类型（动态配置，需在 SDK.config.itemConfig.cardConfig.cardTypes 中注册）
+ */
+export type CardType = string;
+/**
+ * @description 卡片创建信息
+ */
+export type CardCreateInfo = {
+    /**
+     * @description 元素类型 - 卡片
+     */
+    type: SDKItemType.CARD;
+    /**
+     * @description 元素名称
+     */
+    name?: string;
+    /**
+     * @description 元素id
+     */
+    id?: string;
+    /**
+     * @description 父元素id
+     */
+    parentId?: string;
+    /**
+     * @description 扩展属性
+     */
+    extension?: Record<string, any>;
+    /**
+     * @description 元素属性
+     */
+    property: {
+        /**
+         * @description 卡片类型
+         */
+        cardType: CardType;
+        /**
+         * @description 卡片元素像素宽度
+         */
+        width: number;
+        /**
+         * @description 卡片元素像素高度
+         */
+        height: number;
+        /**
+         * @description 是否根据 HTML 挂载内容的自然高度自动更新卡片高度
+         */
+        autoHeight?: boolean;
+        /**
+         * @description 卡片元素位置
+         */
+        position: [number, number];
+        /**
+         * @description 卡片元素旋转 z | [x, y, z]
+         */
+        rotation?: number | [number, number, number];
+        /**
+         * @description 卡片元素缩放
+         */
+        scale?: [number, number];
+        /**
+         * @description HTML 覆盖层配置；存在该字段时由 DOM overlay 渲染
+         */
+        html?: CardHTML;
+    };
+};
+/**
+ * @description 生成器类型
+ */
+export type GeneratorType = 'image' | 'video';
+/**
+ * @description 生成器创建信息
+ */
+export type GeneratorCreateInfo = {
+    /**
+     * @description 元素类型 - 生成器
+     */
+    type: SDKItemType.GENERATOR;
+    /**
+     * @description 元素名称
+     */
+    name?: string;
+    /**
+     * @description 元素id
+     */
+    id?: string;
+    /**
+     * @description 父元素id
+     */
+    parentId?: string;
+    /**
+     * @description 扩展属性
+     */
+    extension?: Record<string, any>;
+    /**
+     * @description 元素属性
+     */
+    property: {
+        /**
+         * @description 生成器类型
+         */
+        generatorType: GeneratorType;
+        /**
+         * @description 生成器元素像素宽度
+         */
+        width: number;
+        /**
+         * @description 生成器元素像素高度
+         */
+        height: number;
+        /**
+         * @description 生成器元素位置
+         */
+        position: [number, number];
+        /**
+         * @description 生成器元素旋转 z | [x, y, z]
+         */
+        rotation?: number | [number, number, number];
+        /**
+         * @description 生成器元素缩放
+         */
+        scale?: [number, number];
+    };
+};
+/**
+ * @description 图片生成器资源信息
+ */
+export type SpriteGeneratorResource = {
+    /**
+     * @description 资源地址
+     */
+    url: string;
+    /**
+     * @description 资源尺寸
+     */
+    size?: spec.vec2;
+    /**
+     * @description 目标生成器元素 ID（必填）
+     */
+    itemId: string;
+    /**
+     * @description 扩展属性
+     */
+    extension?: Record<string, any>;
+};
+/**
+ * @description 视频生成器资源信息
+ */
+export type VideoGeneratorResource = {
+    /**
+     * @description 资源地址
+     */
+    url: string;
+    /**
+     * @description 资源尺寸
+     */
+    size?: spec.vec2;
+    /**
+     * @description 是否静音（仅用于视频）
+     */
+    muted?: boolean;
+    /**
+     * @description 是否为透明视频（仅用于视频）
+     */
+    transparent?: boolean;
+    /**
+     * @description 播放速率（仅用于视频）
+     */
+    playbackRate?: number;
+    /**
+     * @description 音量（仅用于视频）
+     */
+    volume?: number;
+    /**
+     * @description 目标生成器元素 ID（必填）
+     */
+    itemId: string;
+    /**
+     * @description 扩展属性
+     */
+    extension?: Record<string, any>;
+};
+export type GeneratorResource = SpriteGeneratorResource | VideoGeneratorResource;
+/**
+ * @description 生成器样式配置
+ */
+export type GeneratorStyleConfig = {
+    /**
+     * @description 填充颜色 [r, g, b, a]，范围 0-1
+     */
+    fillColor?: spec.vec4;
+    /**
+     * @description 图标 URL
+     */
+    iconUrl?: string;
+};
+export type EffectsCreateInfo = {
+    /**
+     * @description 元素类型 - 特效
+     */
+    type: SDKItemType.EFFECTS;
+    /**
+     * @description 元素名称
+     */
+    name?: string;
+    /**
+     * @description 元素id
+     */
+    id?: string;
+    /**
+     * @description 父元素id
+     */
+    parentId?: string;
+    property: {
+        /**
+         * @description 动效像素宽度
+         */
+        width?: number;
+        /**
+         * @description 动效像素高度
+         */
+        height?: number;
+        /**
+         * @description 生成器位置
+         */
+        position: spec.vec2;
+        /**
+         * @description 旋转角度
+         */
+        rotation?: number | [number, number, number];
+        /**
+         * @description 缩放
+         */
+        scale?: spec.vec2;
+        /**
+         * @description 动效资源地址
+         */
+        effects: string;
+    };
+    /**
+     * @description 扩展属性
+     */
+    extension?: Record<string, any>;
+};
+export type AsyncSpriteCreateInfo = SpriteCreateInfo & {
+    textureId: string;
+};
+export type AsyncVideoCreateInfo = VideoCreateInfo & {
+    textureId: string;
+};
+/**
+ * @description Frame 画板元素创建信息
+ */
+export type FrameCreateInfo = {
+    /**
+     * @description 元素类型 - 画板
+     */
+    type: SDKItemType.FRAME;
+    /**
+     * @description 元素名称
+     */
+    name?: string;
+    /**
+     * @description 元素id
+     */
+    id?: string;
+    /**
+     * @description 父元素id
+     */
+    parentId?: string;
+    /**
+     * @description 元素属性
+     */
+    property: {
+        /**
+         * @description 画板像素宽度
+         */
+        width: number;
+        /**
+         * @description 画板像素高度
+         */
+        height: number;
+        /**
+         * @description 画板位置
+         */
+        position: [number, number];
+        /**
+         * @description 画板旋转 z | [x, y, z]
+         */
+        rotation?: number | [number, number, number];
+        /**
+         * @description 画板缩放
+         */
+        scale?: [number, number];
+        /**
+         * @description 布局模式: 'auto' | 'free'
+         */
+        layoutMode?: FrameLayoutMode;
+        /**
+         * @description 子元素序号
+         */
+        children: string[];
+        /**
+         * @description 自动布局配置
+         */
+        autoLayoutConfig?: AutoLayoutConfig;
+        /**
+         * @description 子元素布局位置信息（用于自动布局）
+         * key: 子元素ID, value: 元素的位置信息
+         */
+        layoutInfos?: Record<string, LayoutInfo>;
+    };
+    /**
+     * @description 扩展属性
+     */
+    extension?: Record<string, any>;
+};
+export type ItemCreateInfo = GroupCreateInfo | SpriteCreateInfo | TextCreateInfo | VideoCreateInfo | GeneratorCreateInfo | EffectsCreateInfo | FrameCreateInfo | CardCreateInfo;
+export type AsyncItemCreateInfo = GroupCreateInfo | TextCreateInfo | AsyncSpriteCreateInfo | AsyncVideoCreateInfo;
+/**
+ * @description 场景创建信息
+ */
+export type SceneCreaetInfo = {
+    /**
+     * @description 场景名称
+     */
+    name: string;
+    /**
+     * @description 场景大小
+     */
+    size: spec.vec2;
+};
+export declare enum ItemOrderAction {
+    BringToFront = 0,
+    SendToBack = 1,
+    BringForward = 2,
+    SendBackward = 3
+}
+/**
+ * @description 视图自适应偏移参数
+ */
+export type ViewportFitShiftParam = {
+    /**
+     * @description 左偏移
+     */
+    left?: number;
+    /**
+     * @description 右偏移
+     */
+    right?: number;
+    /**
+     * @description 上偏移
+     */
+    top?: number;
+    /**
+     * @description 下偏移
+     */
+    bottom?: number;
+};
+export type TextureInfo = {
+    id: string;
+    url: string;
+    type: 'image' | 'video';
+};
+export type LoadTextureInfo = {
+    id: string;
+    textureId: string;
+    url: string;
+    type: 'image' | 'video';
+};