@vvfx/sdk 0.1.19-alpha.0 → 0.1.19-alpha.1

package/dist/index.d.cts

@@ -107,6 +107,15 @@ type GeneratorItemOptions = SDKItemOptions & {
 type EffectsItemOptions = SDKItemOptions & {
     property?: Partial<EffectsItemProperty>;
 };
+/**
+ * @description Frame 画板元素 SDKItem 选项
+ */
+type FrameItemOptions = SDKItemOptions & {
+    /**
+     * @description 元素属性
+     */
+    property?: Partial<FrameItemProperty>;
+};
 /**
  * @description SDKItem 类型（独立于 spec.ItemType）
  * @description 包含所有 SDK 层级的元素类型，包括虚拟类型如 generator
@@ -697,6 +706,106 @@ declare class EffectsItem extends BaseItem {
  */
 declare function isEffectsItem(obj: any): obj is EffectsItem;
 
+/**
+ * @description 画板/框架元素 SDKItem 类
+ * @description 支持自动布局和自由布局两种模式
+ * @description 底层以 composition 形式渲染
+ */
+declare class FrameItem extends BaseItem {
+    /**
+     * @description 元素类型
+     */
+    readonly type = SDKItemType.FRAME;
+    /**
+     * @description 元素属性
+     */
+    property: FrameItemProperty;
+    constructor(options: FrameItemOptions);
+    /**
+     * @description 子元素ID列表（只读）
+     */
+    get children(): readonly string[];
+    /**
+     * @description 布局模式
+     */
+    get layoutMode(): FrameLayoutMode;
+    set layoutMode(value: FrameLayoutMode);
+    /**
+     * @description 位置
+     */
+    get position(): [number, number];
+    set position(value: [number, number]);
+    /**
+     * @description 宽度
+     */
+    get width(): number;
+    set width(value: number);
+    /**
+     * @description 高度
+     */
+    get height(): number;
+    set height(value: number);
+    /**
+     * @description 缩放
+     */
+    get scale(): [number, number];
+    set scale(value: [number, number]);
+    /**
+     * @description 旋转（二维旋转角度）
+     */
+    get rotation(): number;
+    set rotation(value: number);
+    /**
+     * @description 完整旋转（包含 x, y, z）
+     */
+    get fullRotation(): [number, number, number];
+    set fullRotation(value: [number, number, number]);
+    /**
+     * @description 添加子元素
+     * @param itemId 子元素ID
+     * @returns 是否添加成功
+     */
+    addChild(itemId: string): boolean;
+    /**
+     * @description 批量添加子元素
+     * @param itemIds 子元素ID列表
+     */
+    addChildren(itemIds: string[]): void;
+    /**
+     * @description 移除子元素
+     * @param itemId 子元素ID
+     * @returns 是否移除成功
+     */
+    removeChild(itemId: string): boolean;
+    /**
+     * @description 批量移除子元素
+     * @param itemIds 子元素ID列表
+     */
+    removeChildren(itemIds: string[]): void;
+    /**
+     * @description 是否包含指定子元素
+     * @param itemId 子元素ID
+     */
+    hasChild(itemId: string): boolean;
+    /**
+     * @description 清空所有子元素
+     */
+    clearChildren(): void;
+    /**
+     * @description 转换为 FrameCreateInfo
+     * @param withParent 是否包含父节点ID
+     */
+    toCreateInfo(withParent?: boolean): FrameCreateInfo;
+    /**
+     * @description 克隆 SDKItem
+     */
+    clone(): FrameItem;
+}
+/**
+ * @description 类型守卫：检查是否是 FrameItem
+ */
+declare function isFrameItem(obj: any): obj is FrameItem;
+
 /**
  * @description 根据 item type 创建对应的 SDKItem 实例
  * @param type 元素类型
@@ -708,7 +817,7 @@ declare function createSDKItem(type: spec.ItemType, options: SDKItemOptions): Ba
  * @description SDKItem 类型联合
  * @description 用于替换原来的 SDKItem type
  */
-type SDKItem$1 = SpriteItem | TextItem | VideoItem | GroupItem | GeneratorItem | EffectsItem;
+type SDKItem$1 = SpriteItem | TextItem | VideoItem | GroupItem | GeneratorItem | EffectsItem | FrameItem;
 
 /**
  * @class 二维线段
@@ -1243,6 +1352,26 @@ type GeneratorItemProperty = BaseItemProperty & {
 type EffectsItemProperty = BaseItemProperty & {
     effects: string;
 };
+/**
+ * @description Frame 画板元素布局模式
+ */
+declare enum FrameLayoutMode {
+    AUTO = "auto",
+    FREE = "free"
+}
+/**
+ * @description Frame 画板元素属性
+ */
+type FrameItemProperty = BaseItemProperty & {
+    /**
+     * @description 布局模式: auto - 自动布局, free - 自由布局
+     */
+    layoutMode: FrameLayoutMode;
+    /**
+     * @description 子元素ID数组
+     */
+    children: string[];
+};
 /**
  * @description BaseItem 基础属性键名
  */
@@ -1269,7 +1398,7 @@ type ItemPropertyMap = {
     [SDKItemType.GROUP]: GroupItemProperty;
     [SDKItemType.GENERATOR]: GeneratorItemProperty;
     [SDKItemType.EFFECTS]: EffectsItemProperty;
-    [SDKItemType.FRAME]: BaseItemProperty;
+    [SDKItemType.FRAME]: FrameItemProperty;
 };
 /**
  * @description 场景1：单个元素单个属性设置
@@ -1970,7 +2099,61 @@ type EffectsCreateInfo = {
      */
     extension?: Record<string, any>;
 };
-type ItemCreateInfo = GroupCreateInfo | SpriteCreateInfo | TextCreateInfo | VideoCreateInfo | GeneratorCreateInfo | EffectsCreateInfo;
+/**
+ * @description Frame 画板元素创建信息
+ */
+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 扩展属性
+     */
+    extension?: Record<string, any>;
+};
+type ItemCreateInfo = GroupCreateInfo | SpriteCreateInfo | TextCreateInfo | VideoCreateInfo | GeneratorCreateInfo | EffectsCreateInfo | FrameCreateInfo;
 /**
  * @description 场景创建信息
  */
@@ -2707,7 +2890,26 @@ type VideoPlayGizmoConfig = {
     height: number;
 };
 type ItemCreateGizmoConfig = {
-    frameColor: number;
+    /**
+     * @description 边框颜色
+     */
+    frameBorderColor: number;
+    /**
+     * @description 边框宽度
+     */
+    frameBorderWidth: number;
+    /**
+     * @description 边框透明度
+     */
+    frameBorderAlpha: number;
+    /**
+     * @description 填充颜色
+     */
+    frameFillColor: number;
+    /**
+     * @description 填充透明度
+     */
+    frameFillAlpha: number;
 };
 
 /**
@@ -2801,6 +3003,7 @@ type SDKEvents = {
     'itemCreate': [{
         type: ItemCreateType;
         position: spec.vec2;
+        id: string;
     }];
     'viewLost': [];
     'viewRebuildFinish': [];
@@ -3078,21 +3281,14 @@ declare class SDK {
      * @param extensions 扩展属性对象（支持同时设置多个）
      * @returns 是否设置成功
      */
-    setItemExtensions(id: string, extensions: Record<string, any>): boolean;
+    setItemExtension(id: string, extension: Record<string, any>): boolean;
     /**
      * @description 批量获取元素扩展属性
      * @param id 元素ID
      * @param keys 扩展属性名称列表（不传则返回所有扩展属性）
      * @returns 扩展属性对象
      */
-    getItemExtensions(id: string, keys?: string[]): Record<string, any> | undefined;
-    /**
-     * @description 获取单个元素扩展属性
-     * @param id 元素ID
-     * @param key 扩展属性名称
-     * @returns 扩展属性值
-     */
-    getItemExtension(id: string, key: string): any;
+    getItemExtension(id: string, keys?: string[]): Record<string, any> | undefined;
     /**
      * @description 删除元素扩展属性（支持批量删除）
      * @param id 元素ID
@@ -3175,6 +3371,12 @@ declare class SDK {
      * @param effectsInfo 动效创建信息
      */
     addEffectsItem(effectsInfo: EffectsCreateInfo): Promise<string | undefined>;
+    /**
+     * @description 创建画板元素
+     * @param createInfo 画板创建信息
+     * @returns 画板元素ID
+     */
+    addFrameItem(createInfo: FrameCreateInfo): string;
     /**
      * @description 设置生成器资源，将生成器转换为对应的元素
      * @param id 生成器元素ID
@@ -3205,4 +3407,4 @@ declare class SDK {
     setSafeAreaPreviewVisible(id: number, type: 'url' | 'color', visible: boolean): void;
 }
 
-export { type ActiveData, BaseItem, type BaseItemProperty, type BaseItemPropertyKey, type BaseItemPropertyValueMap, Box2, type CreateOperation, type DeleteOperation, type EffectsCreateInfo, EffectsItem, type EffectsItemOptions, type GeneratorCreateInfo, GeneratorItem, type GeneratorItemOptions, type GeneratorItemProperty, type GizmoType, type GroupCreateInfo, GroupItem, type GroupItemOptions, type ItemCreateInfo, ItemOrderAction, type ItemPropertyMap, type Operation, type PageData, type PageProperty, SDK, type SDKEvents, type SDKInputParam, type SDKItem$1 as SDKItem, type SDKItemOptions, SDKItemType, type SDKOptions, type SetItemPropertyParam, type SetSingleItemMultiplePropertiesParam, type SetSingleItemSinglePropertyParam, type SpriteCreateInfo, SpriteItem, type SpriteItemOptions, type SpriteItemProperty, type TextCreateInfo, TextItem, type TextItemOptions, type TextItemProperty, type UpdateOperation, Vector2, type VideoCreateInfo, VideoItem, type VideoItemOptions, type VideoItemProperty, type ViewParam, type ViewProperty, createSDKItem, isBaseItem, isEffectsItem, isGeneratorItem, isGroupItem, isSpriteItem, isTextItem, isVideoItem };
+export { type ActiveData, BaseItem, type BaseItemProperty, type BaseItemPropertyKey, type BaseItemPropertyValueMap, Box2, type CreateOperation, type DeleteOperation, type EffectsCreateInfo, EffectsItem, type EffectsItemOptions, type FrameCreateInfo, FrameItem, type FrameItemOptions, type FrameItemProperty, FrameLayoutMode, type GeneratorCreateInfo, GeneratorItem, type GeneratorItemOptions, type GeneratorItemProperty, type GizmoType, type GroupCreateInfo, GroupItem, type GroupItemOptions, type ItemCreateInfo, ItemOrderAction, type ItemPropertyMap, type Operation, type PageData, type PageProperty, SDK, type SDKEvents, type SDKInputParam, type SDKItem$1 as SDKItem, type SDKItemOptions, SDKItemType, type SDKOptions, type SetItemPropertyParam, type SetSingleItemMultiplePropertiesParam, type SetSingleItemSinglePropertyParam, type SpriteCreateInfo, SpriteItem, type SpriteItemOptions, type SpriteItemProperty, type TextCreateInfo, TextItem, type TextItemOptions, type TextItemProperty, type UpdateOperation, Vector2, type VideoCreateInfo, VideoItem, type VideoItemOptions, type VideoItemProperty, type ViewParam, type ViewProperty, createSDKItem, isBaseItem, isEffectsItem, isFrameItem, isGeneratorItem, isGroupItem, isSpriteItem, isTextItem, isVideoItem };

package/dist/index.d.ts

@@ -107,6 +107,15 @@ type GeneratorItemOptions = SDKItemOptions & {
 type EffectsItemOptions = SDKItemOptions & {
     property?: Partial<EffectsItemProperty>;
 };
+/**
+ * @description Frame 画板元素 SDKItem 选项
+ */
+type FrameItemOptions = SDKItemOptions & {
+    /**
+     * @description 元素属性
+     */
+    property?: Partial<FrameItemProperty>;
+};
 /**
  * @description SDKItem 类型（独立于 spec.ItemType）
  * @description 包含所有 SDK 层级的元素类型，包括虚拟类型如 generator
@@ -697,6 +706,106 @@ declare class EffectsItem extends BaseItem {
  */
 declare function isEffectsItem(obj: any): obj is EffectsItem;
 
+/**
+ * @description 画板/框架元素 SDKItem 类
+ * @description 支持自动布局和自由布局两种模式
+ * @description 底层以 composition 形式渲染
+ */
+declare class FrameItem extends BaseItem {
+    /**
+     * @description 元素类型
+     */
+    readonly type = SDKItemType.FRAME;
+    /**
+     * @description 元素属性
+     */
+    property: FrameItemProperty;
+    constructor(options: FrameItemOptions);
+    /**
+     * @description 子元素ID列表（只读）
+     */
+    get children(): readonly string[];
+    /**
+     * @description 布局模式
+     */
+    get layoutMode(): FrameLayoutMode;
+    set layoutMode(value: FrameLayoutMode);
+    /**
+     * @description 位置
+     */
+    get position(): [number, number];
+    set position(value: [number, number]);
+    /**
+     * @description 宽度
+     */
+    get width(): number;
+    set width(value: number);
+    /**
+     * @description 高度
+     */
+    get height(): number;
+    set height(value: number);
+    /**
+     * @description 缩放
+     */
+    get scale(): [number, number];
+    set scale(value: [number, number]);
+    /**
+     * @description 旋转（二维旋转角度）
+     */
+    get rotation(): number;
+    set rotation(value: number);
+    /**
+     * @description 完整旋转（包含 x, y, z）
+     */
+    get fullRotation(): [number, number, number];
+    set fullRotation(value: [number, number, number]);
+    /**
+     * @description 添加子元素
+     * @param itemId 子元素ID
+     * @returns 是否添加成功
+     */
+    addChild(itemId: string): boolean;
+    /**
+     * @description 批量添加子元素
+     * @param itemIds 子元素ID列表
+     */
+    addChildren(itemIds: string[]): void;
+    /**
+     * @description 移除子元素
+     * @param itemId 子元素ID
+     * @returns 是否移除成功
+     */
+    removeChild(itemId: string): boolean;
+    /**
+     * @description 批量移除子元素
+     * @param itemIds 子元素ID列表
+     */
+    removeChildren(itemIds: string[]): void;
+    /**
+     * @description 是否包含指定子元素
+     * @param itemId 子元素ID
+     */
+    hasChild(itemId: string): boolean;
+    /**
+     * @description 清空所有子元素
+     */
+    clearChildren(): void;
+    /**
+     * @description 转换为 FrameCreateInfo
+     * @param withParent 是否包含父节点ID
+     */
+    toCreateInfo(withParent?: boolean): FrameCreateInfo;
+    /**
+     * @description 克隆 SDKItem
+     */
+    clone(): FrameItem;
+}
+/**
+ * @description 类型守卫：检查是否是 FrameItem
+ */
+declare function isFrameItem(obj: any): obj is FrameItem;
+
 /**
  * @description 根据 item type 创建对应的 SDKItem 实例
  * @param type 元素类型
@@ -708,7 +817,7 @@ declare function createSDKItem(type: spec.ItemType, options: SDKItemOptions): Ba
  * @description SDKItem 类型联合
  * @description 用于替换原来的 SDKItem type
  */
-type SDKItem$1 = SpriteItem | TextItem | VideoItem | GroupItem | GeneratorItem | EffectsItem;
+type SDKItem$1 = SpriteItem | TextItem | VideoItem | GroupItem | GeneratorItem | EffectsItem | FrameItem;
 
 /**
  * @class 二维线段
@@ -1243,6 +1352,26 @@ type GeneratorItemProperty = BaseItemProperty & {
 type EffectsItemProperty = BaseItemProperty & {
     effects: string;
 };
+/**
+ * @description Frame 画板元素布局模式
+ */
+declare enum FrameLayoutMode {
+    AUTO = "auto",
+    FREE = "free"
+}
+/**
+ * @description Frame 画板元素属性
+ */
+type FrameItemProperty = BaseItemProperty & {
+    /**
+     * @description 布局模式: auto - 自动布局, free - 自由布局
+     */
+    layoutMode: FrameLayoutMode;
+    /**
+     * @description 子元素ID数组
+     */
+    children: string[];
+};
 /**
  * @description BaseItem 基础属性键名
  */
@@ -1269,7 +1398,7 @@ type ItemPropertyMap = {
     [SDKItemType.GROUP]: GroupItemProperty;
     [SDKItemType.GENERATOR]: GeneratorItemProperty;
     [SDKItemType.EFFECTS]: EffectsItemProperty;
-    [SDKItemType.FRAME]: BaseItemProperty;
+    [SDKItemType.FRAME]: FrameItemProperty;
 };
 /**
  * @description 场景1：单个元素单个属性设置
@@ -1970,7 +2099,61 @@ type EffectsCreateInfo = {
      */
     extension?: Record<string, any>;
 };
-type ItemCreateInfo = GroupCreateInfo | SpriteCreateInfo | TextCreateInfo | VideoCreateInfo | GeneratorCreateInfo | EffectsCreateInfo;
+/**
+ * @description Frame 画板元素创建信息
+ */
+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 扩展属性
+     */
+    extension?: Record<string, any>;
+};
+type ItemCreateInfo = GroupCreateInfo | SpriteCreateInfo | TextCreateInfo | VideoCreateInfo | GeneratorCreateInfo | EffectsCreateInfo | FrameCreateInfo;
 /**
  * @description 场景创建信息
  */
@@ -2707,7 +2890,26 @@ type VideoPlayGizmoConfig = {
     height: number;
 };
 type ItemCreateGizmoConfig = {
-    frameColor: number;
+    /**
+     * @description 边框颜色
+     */
+    frameBorderColor: number;
+    /**
+     * @description 边框宽度
+     */
+    frameBorderWidth: number;
+    /**
+     * @description 边框透明度
+     */
+    frameBorderAlpha: number;
+    /**
+     * @description 填充颜色
+     */
+    frameFillColor: number;
+    /**
+     * @description 填充透明度
+     */
+    frameFillAlpha: number;
 };
 
 /**
@@ -2801,6 +3003,7 @@ type SDKEvents = {
     'itemCreate': [{
         type: ItemCreateType;
         position: spec.vec2;
+        id: string;
     }];
     'viewLost': [];
     'viewRebuildFinish': [];
@@ -3078,21 +3281,14 @@ declare class SDK {
      * @param extensions 扩展属性对象（支持同时设置多个）
      * @returns 是否设置成功
      */
-    setItemExtensions(id: string, extensions: Record<string, any>): boolean;
+    setItemExtension(id: string, extension: Record<string, any>): boolean;
     /**
      * @description 批量获取元素扩展属性
      * @param id 元素ID
      * @param keys 扩展属性名称列表（不传则返回所有扩展属性）
      * @returns 扩展属性对象
      */
-    getItemExtensions(id: string, keys?: string[]): Record<string, any> | undefined;
-    /**
-     * @description 获取单个元素扩展属性
-     * @param id 元素ID
-     * @param key 扩展属性名称
-     * @returns 扩展属性值
-     */
-    getItemExtension(id: string, key: string): any;
+    getItemExtension(id: string, keys?: string[]): Record<string, any> | undefined;
     /**
      * @description 删除元素扩展属性（支持批量删除）
      * @param id 元素ID
@@ -3175,6 +3371,12 @@ declare class SDK {
      * @param effectsInfo 动效创建信息
      */
     addEffectsItem(effectsInfo: EffectsCreateInfo): Promise<string | undefined>;
+    /**
+     * @description 创建画板元素
+     * @param createInfo 画板创建信息
+     * @returns 画板元素ID
+     */
+    addFrameItem(createInfo: FrameCreateInfo): string;
     /**
      * @description 设置生成器资源，将生成器转换为对应的元素
      * @param id 生成器元素ID
@@ -3205,4 +3407,4 @@ declare class SDK {
     setSafeAreaPreviewVisible(id: number, type: 'url' | 'color', visible: boolean): void;
 }
 
-export { type ActiveData, BaseItem, type BaseItemProperty, type BaseItemPropertyKey, type BaseItemPropertyValueMap, Box2, type CreateOperation, type DeleteOperation, type EffectsCreateInfo, EffectsItem, type EffectsItemOptions, type GeneratorCreateInfo, GeneratorItem, type GeneratorItemOptions, type GeneratorItemProperty, type GizmoType, type GroupCreateInfo, GroupItem, type GroupItemOptions, type ItemCreateInfo, ItemOrderAction, type ItemPropertyMap, type Operation, type PageData, type PageProperty, SDK, type SDKEvents, type SDKInputParam, type SDKItem$1 as SDKItem, type SDKItemOptions, SDKItemType, type SDKOptions, type SetItemPropertyParam, type SetSingleItemMultiplePropertiesParam, type SetSingleItemSinglePropertyParam, type SpriteCreateInfo, SpriteItem, type SpriteItemOptions, type SpriteItemProperty, type TextCreateInfo, TextItem, type TextItemOptions, type TextItemProperty, type UpdateOperation, Vector2, type VideoCreateInfo, VideoItem, type VideoItemOptions, type VideoItemProperty, type ViewParam, type ViewProperty, createSDKItem, isBaseItem, isEffectsItem, isGeneratorItem, isGroupItem, isSpriteItem, isTextItem, isVideoItem };
+export { type ActiveData, BaseItem, type BaseItemProperty, type BaseItemPropertyKey, type BaseItemPropertyValueMap, Box2, type CreateOperation, type DeleteOperation, type EffectsCreateInfo, EffectsItem, type EffectsItemOptions, type FrameCreateInfo, FrameItem, type FrameItemOptions, type FrameItemProperty, FrameLayoutMode, type GeneratorCreateInfo, GeneratorItem, type GeneratorItemOptions, type GeneratorItemProperty, type GizmoType, type GroupCreateInfo, GroupItem, type GroupItemOptions, type ItemCreateInfo, ItemOrderAction, type ItemPropertyMap, type Operation, type PageData, type PageProperty, SDK, type SDKEvents, type SDKInputParam, type SDKItem$1 as SDKItem, type SDKItemOptions, SDKItemType, type SDKOptions, type SetItemPropertyParam, type SetSingleItemMultiplePropertiesParam, type SetSingleItemSinglePropertyParam, type SpriteCreateInfo, SpriteItem, type SpriteItemOptions, type SpriteItemProperty, type TextCreateInfo, TextItem, type TextItemOptions, type TextItemProperty, type UpdateOperation, Vector2, type VideoCreateInfo, VideoItem, type VideoItemOptions, type VideoItemProperty, type ViewParam, type ViewProperty, createSDKItem, isBaseItem, isEffectsItem, isFrameItem, isGeneratorItem, isGroupItem, isSpriteItem, isTextItem, isVideoItem };