@vvfx/artis 0.0.1-alpha.0

package/dist/artis/operations/operations.d.ts

@@ -0,0 +1,362 @@
+import type { BaseArtis } from '../base-artis';
+import { IOPlugin, type ArtisData, type ArtisItemType, type CardTypeConfig, type HistoryManager, type InitArtisData, type ItemCreateInfo, type PageAutoLayoutParam, type SetItemPropertyParam, type SpriteCreateInfo, type TextCreateInfo, type VideoCreateInfo, type GeneratorCreateInfo, type EffectsCreateInfo, type FrameCreateInfo, type CardCreateInfo } from '../../core';
+import type { ExportMediaInitOptions, ExportMediaItemDownloadInfo, ExportParams, Buffers, Extras } from '../../helper';
+import { Exporter, ScreenShot } from '../../helper';
+import { spec } from '../../shared';
+import { Box2, Vector2, type LoadingItemOptions, type MaskConfig } from '@vvfx/gizmo';
+import type { AlignType, DistributeType } from '../../utils/types';
+import type { InitPositionOptions, ViewportFitParam } from './types';
+/**
+ * Artis 顶层操作门面（namespace `artis.operations`）。
+ *
+ * 直接实现常用基础功能（创建/删除/写属性/截图/导出/对齐/gizmo 开关 …），供外部
+ * `artis.operations.addSprite(info)` 类型化调用，而非走 `artis.command.execute('item.create', { schemas: schema })`
+ * 字符串命令。方法体内直接委托宿主 artis 的 namespace getter（command/item/view/selection/preferences/
+ * history/stateManager/gizmoManager/gestureHandler/player/renderer/interactionService/pluginSystem/store），
+ * 保留撤销/守卫/batch/资源回流（N10/C3）——是 command 的类型化高层糖，非替代。
+ *
+ * 真逻辑（schema 转换 / batch 包裹 / 资源回流 / 视口并集 / rAF 轮询 / 导出校验）直接写在方法体内，
+ * 从旧 ArtisSDK 搬迁去 deprecated。懒实例（导出器/截图工具/openTextGizmo rAF 句柄）作为本类私有字段托管，
+ * {@link dispose} 由 BaseArtis.dispose 调用释放。
+ *
+ * 可被 SceneArtis 子类化扩展出 SceneOperations（BaseArtis 的 `_createOperations` 工厂由子类 override）。
+ */
+export declare class Operations {
+    /** 视频导出器（懒实例化，dispose 时释放） */
+    private _exporter?;
+    /** 无头截图工具（懒实例化，dispose 时释放） */
+    private _screenShot?;
+    /** openTextGizmo 的 rAF 轮询句柄（dispose 时需取消，避免回调落到已释放的 GestureHandler） */
+    private _textEditRafId?;
+    constructor(artis: BaseArtis);
+    /** 懒实例化并返回本实例专属的视频导出器。 */
+    protected getExporter(): Exporter;
+    /** 懒实例化并返回本实例专属的截图工具。 */
+    protected getScreenShot(): ScreenShot;
+    /** 获取已注册的 IOPlugin；未注册或未激活时抛错。 */
+    protected getIOPlugin(): IOPlugin;
+    /**
+     * 释放本门面托管资源：取消悬挂 rAF、dispose 导出器/截图工具。
+     * 由 {@link BaseArtis.dispose} 调用（step 10b）。
+     */
+    dispose(): void;
+    /** 创建图片元素。经 CreateInfo → ItemSchema 转换后走 item.create Command，并 await 资源回流（D-资源回流/C7）。 */
+    addSpriteItem(spriteInfo: SpriteCreateInfo): string;
+    /** 创建文本元素。 */
+    addTextItem(textInfo: TextCreateInfo): string;
+    /** 创建视频元素。 */
+    addVideoItem(videoInfo: VideoCreateInfo): string;
+    /** 创建卡片元素。 */
+    addCardItem(createInfo: CardCreateInfo): string;
+    /** 创建生成器元素。 */
+    addGeneratorItem(createInfo: GeneratorCreateInfo): string;
+    /** 创建特效元素。 */
+    addEffectsItem(effectsInfo: EffectsCreateInfo): string;
+    /** 创建画板元素。 */
+    addFrameItem(createInfo: FrameCreateInfo): string;
+    /**
+     * 计算新元素的空闲落位 [x,y]（纯计算，不创建/不改任何元素）。
+     *
+     * 收口 docs/artis-functions.ts 的 initPositionByFree / initPositionByRow 布局算法，走
+     * {@link ItemService.getInitPosition}：参考画布已有元素，算出一个不重叠的落位供 create schema 的
+     * `property.position` 使用。无已有元素时返回 [0,0]。
+     *
+     * - `layout:'free'`（默认）：找已有元素最右下角作参照 → 超过 `wrapThreshold` 或显式 wrap 时换行 → Y 轴碰撞下移。
+     *   `wrapMode`：'wrap'（立即换行）|'nowrap'（禁换行）；`wrapThreshold` 为自动换行阈值，默认 12000px。
+     *   忽略画板父级的子元素与组元素。
+     * - `layout:'row'`：从 `rowAnchor` 往右避让，sprite/video 碰撞框按 `rowScale` 算实际占位，横向重叠则右移；
+     *   带 10s 超时防死循环。
+     * - `shift`: 可选，在计算落位时额外向右下偏移的像素量（默认 20）。
+     *
+     * @param nodeSize 新节点尺寸（宽高，用于落位中心偏移与碰撞框）
+     * @param options layout/wrapMode/wrapThreshold/excludeIds/rowAnchor/rowScale，见上
+     * @returns [x, y] 像素坐标
+     */
+    getInitPosition(nodeSize: {
+        width: number;
+        height: number;
+    }, options?: InitPositionOptions): [number, number];
+    /**
+     * 批量创建元素。「先子后父」拓扑排序已下沉到命令层，此处只做 createInfo → schema 转发；
+     * 返回的 ids 与 createInfos 逐项一一对应。
+     * @param asyncMode false(默认)同步等资源；true 立即返回、资源后台加载
+     */
+    addItemByCreateInfos(createInfos: ItemCreateInfo[], asyncMode?: boolean): string[];
+    /** 经 CreateInfo → ItemSchema 转换后创建单个元素，await 资源回流后返回新元素 ID。 */
+    private _createByInfoAsync;
+    /** 删除单个元素（支持撤销）。 */
+    deleteItem(id: string): void;
+    /** 删除多个元素，以 batch 聚合为单条历史。 */
+    deleteItems(ids: string[]): void;
+    /** 调整元素层级顺序。 */
+    updateItemOrder(id: string, reorderType: 'bringToFront' | 'sendToBack' | 'moveUp' | 'moveDown'): void;
+    /** 成组元素。 */
+    groupItems(childrenIds: string[]): void;
+    /** 将元素移入画板。 */
+    moveItemsToFrame(itemIds: string[], frameId: string): void;
+    /** 将元素移出画板。 */
+    moveItemsOutOfFrame(itemIds: string[]): void;
+    /** 设置元素父子关系（移入指定父级）。 */
+    setItemParent(id: string, parentId: string): void;
+    /** 解除元素与指定父级的关系（移出画板）。 */
+    deleteItemParent(id: string, parentId: string): void;
+    /** 设置选中元素（支持撤销）。 */
+    setSelectedItems(itemIds: string[]): void;
+    /** 获取当前选中元素 ID 列表（elementId 语义）。 */
+    getActiveItemIds(): string[];
+    /** 命中测试：返回 (x, y) 处命中的元素 ID 列表（elementId 语义，由前往后）。 */
+    hitTest(x: number, y: number): string[];
+    /** 获取指定元素；元素不存在时返回 undefined。 */
+    getItem(id: string): import("../..").ArtisItem | undefined;
+    /** 获取多个元素（缺省取全部，过滤 ignoredInteractionNames 命名元素）。 */
+    getItems(ids?: string[]): NonNullable<import("../..").ArtisItem | undefined>[];
+    /** 获取指定元素 schema；元素不存在时返回 undefined。 */
+    getItemSchema(id: string): import("../..").ItemSchema | undefined;
+    /** 获取多个元素 schema；（缺省取全部） */
+    getItemSchemas(ids?: string[]): import("../..").ItemSchema[];
+    /** 获取元素的子元素 ID 列表。 */
+    getChildrenIds(id: string): string[];
+    /** 获取元素的视图包围盒。 */
+    getViewBox(id: string): Box2;
+    /** 获取多个元素视图包围盒（缺省取全部） */
+    getViewBoxes(ids?: string[]): Box2[];
+    /** 获取多个元素视图包围盒并合并 */
+    getUnionViewBox(ids?: string[]): Box2;
+    /** 获取元素的像素包围盒。 */
+    getPixelBox(id: string): Box2;
+    /** 获取多个元素像素包围盒（缺省取全部） */
+    getPixelBoxes(ids?: string[]): Box2[];
+    /** 获取多个元素像素包围盒并合并 */
+    getUnionPixelBox(ids?: string[]): Box2;
+    /** 获取元素的锁定状态；元素不存在时返回 false。 */
+    getItemLockState(id: string): boolean;
+    /** 设置元素属性（单 / 多属性，多属性 batch 聚合）。 */
+    setItemProperty<T extends ArtisItemType>(param: SetItemPropertyParam<T>): void;
+    /** 设置元素名称。 */
+    setItemName(id: string, name: string): void;
+    /** 设置元素锁定状态。 */
+    setItemLockState(id: string, state: boolean): void;
+    /** 设置图片元素尺寸。 */
+    setSpriteSize(id: string, size: [number, number]): void;
+    /** 调整画板元素尺寸（可选同时平移）。 */
+    resizeFrameItem(id: string, size: [number, number], translation?: [number, number]): void;
+    /** 设置特效元素的资源。 */
+    setEffectsResource(id: string, effects: string): void;
+    /** 设置文本元素字体（可撤销）。 */
+    setItemFontFamily(id: string, fontFamilyName: string, url: string): Promise<void>;
+    /** 批量设置元素扩展属性；元素不存在时返回 false。 */
+    setItemExtension(id: string, extension: Record<string, unknown>): boolean;
+    /** 批量获取元素扩展属性（不传 keys 则返回全部）。 */
+    getItemExtension(id: string, keys?: string[]): Record<string, unknown> | undefined;
+    /** 删除元素扩展属性（支持批量）。 */
+    deleteItemExtensions(id: string, keys: string[]): boolean;
+    /** 检查元素是否有指定扩展属性。 */
+    hasItemExtension(id: string, key: string): boolean;
+    /** 获取元素所有扩展属性键名列表。 */
+    getItemExtensionKeys(id: string): string[] | undefined;
+    /** 对画板执行自动布局（切换为 auto 布局模式）。 */
+    applyFrameAutoLayout(frameId: string): void;
+    /** 对整个页面执行自动排布。 */
+    autoLayoutPage(param?: PageAutoLayoutParam): void;
+    /** 设置播放状态：'play' 播放 / 'pause' 暂停。 */
+    setPlayState(playState: 'play' | 'pause'): void;
+    /** 按百分比跳转播放进度（0-100）。委托 Renderer.goto（N2）。 */
+    setPlayProgress(progress: number): void;
+    /** 读取视频元素当前播放时间（秒）。 */
+    getVideoItemPlayTime(id: string): number;
+    /** 设置视频元素播放时间（秒），静默定位不动播放态。 */
+    setVideoItemPlayTime(id: string, time: number): void;
+    /** 暂停视频元素 */
+    pauseVideoItem(id: string): void;
+    /** 播放视频元素 */
+    playVideoItem(id: string): void;
+    /** 读取动效元素当前播放时间（秒）。 */
+    getEffectsItemPlayTime(id: string): number;
+    /** 设置动效元素播放时间（秒）。 */
+    setEffectsItemPlayTime(id: string, time: number): void;
+    /** 暂停特效元素 */
+    pauseEffectsItem(id: string): void;
+    /** 播放特效元素 */
+    playEffectsItem(id: string): void;
+    /** 设置生成器资源（原地替换为 sprite/video 元素，复用同 ID，可撤销）。 */
+    setGeneratorResource(id: string, resourceUrl: string): Promise<string>;
+    /** 设置视图缩放（绝对值）。 */
+    setPageZoom(zoom: number, center?: [number, number]): void;
+    /** 设置画布平移（绝对值），兼容 [x,y] 数组或带 toArray() 的 Vector2。 */
+    setPageMove(targetTranslation: [number, number] | {
+        toArray(): number[];
+    }): void;
+    /** 缩放视图（增量）。 */
+    pageZoom(shift: number, center?: [number, number]): void;
+    /** 平移视图（增量）。 */
+    pageMove(shift: [number, number]): void;
+    /**
+     * 自适应视口（封装 `viewport.fitToBox` / `viewport.fitToItems` 两个 Command）。
+     *
+     * - 传入 `box`：直接走 `viewport.fitToBox(shiftParam, box)` 聚焦该包围盒；
+     * - 未传 `box`：走 `viewport.fitToItems(shiftParam, undefined)` 聚焦全部元素
+     *   （命令内部取所有元素 viewBox 并集；空场景由命令侧 reset 兜底）。
+     *
+     * 两个分支统一经 Command 入口，保留与 wiring 注册处同源的取盒/坐标系口径（viewBox），
+     * 取代此前在此手写 pixel box 并集 + 直调 view.fitToBox 的旁路。
+     */
+    viewportFit(param?: ViewportFitParam): void;
+    /** 像素坐标系包围盒 → 视口坐标系包围盒。 */
+    getViewBoxByBox(box: Box2): Box2;
+    /** 视口坐标 → 像素坐标换算。 */
+    getPixelPositionByViewPosition(viewPosition: Vector2): Vector2;
+    /** 设置交互类型：'hand' 平移 / 'select' 选择。 */
+    setInteractType(type: 'hand' | 'select'): void;
+    /** 读取当前交互类型。 */
+    getInteractType(): 'hand' | 'select' | undefined;
+    /** 页面数据（单视图投影为 ArtisData，仅 items）。 */
+    get pageData(): ArtisData;
+    /** 通过页面数据重新加载并启动。入参缺省或无 items 时退化为空场景启动。 */
+    runByPageData(data: InitArtisData | {
+        items?: unknown[];
+    }): Promise<void>;
+    /** 获取页面配置。 */
+    getPageConfig(): {
+        safeAreaPreview: boolean;
+        zoom: number;
+        adsorption: boolean;
+        asyncMode: boolean;
+        translation: [number, number];
+    };
+    /** 设置页面配置（缩放走 view，其余开关走 preferences）。 */
+    setPageConfig(pageConfig: {
+        safeAreaPreview?: boolean;
+        zoom?: number;
+        adsorption?: boolean;
+        asyncMode?: boolean;
+    }): void;
+    /** 多元素对齐；ids 缺省取当前选中元素。 */
+    makeItemAlign(type: AlignType, ids?: string[]): void;
+    /** 多元素等间距分布；ids 缺省取当前选中元素。 */
+    makeItemDistribute(type: DistributeType, ids?: string[]): void;
+    /** 由指定元素 ID 组装独立场景并生成截图。time 截图时刻（秒），默认 0。 */
+    createScreenShotSceneByIds(idInfo: string | string[], time?: number): Promise<string | undefined>;
+    /** 生成指定元素的截图（可指定结果尺寸 / 时刻 / 背景色）。 */
+    generateScreenShot(idInfo: string | string[], size?: [number, number], tick?: number, backgroundColor?: spec.vec4): Promise<string | undefined>;
+    /** 生成画板（Frame）元素的截图（仅渲染其子元素）。 */
+    createScreenShotByFrame(id: string): Promise<string | undefined>;
+    /** 生成动效（Effects）元素的截图。 */
+    createScreenShotByEffects(id: string): Promise<string | undefined>;
+    /** 视频导出器实例（懒创建）。 */
+    get exporter(): Exporter;
+    /** 当前导出器状态；未创建过导出器时返回 undefined。 */
+    get exportStatus(): Exporter['status'] | undefined;
+    /** 执行导出。导出功能须启用（preferences.export.enabled）且显式传入 params。 */
+    onExport(params?: ExportParams): void;
+    /** 取消导出。 */
+    cancelExport(): void;
+    /** 设置导出参数。 */
+    setExportParam(exportParam: Partial<ExportMediaInitOptions>): void;
+    /** 以媒体格式 buffer 下载。 */
+    downloadByMediaBuffersOfExporter(params: ExportMediaItemDownloadInfo[], buffers: Buffers, extras: Extras): void;
+    /** 撤销最近一条历史。 */
+    undo(): void;
+    /** 重做最近一条历史。 */
+    redo(): void;
+    /** 是否还有可撤销的历史步骤。 */
+    get canUndo(): boolean;
+    /** 是否还有可重做的历史步骤。 */
+    get canRedo(): boolean;
+    /** 撤销 / 重做入口（兼容旧 `_undoRedo` 形态）。 */
+    get undoRedo(): {
+        push: HistoryManager['push'];
+        undo: HistoryManager['undo'];
+        redo: HistoryManager['redo'];
+        canUndo: boolean;
+        canRedo: boolean;
+    };
+    /** 注册单个卡片类型。 */
+    registerCardType(config: CardTypeConfig): boolean;
+    /** 批量注册卡片类型。 */
+    registerCardTypes(configs: CardTypeConfig[]): number;
+    /** 注销卡片类型。 */
+    unregisterCardType(type: string): boolean;
+    /** 获取所有已注册的卡片类型。 */
+    getRegisteredCardTypes(): CardTypeConfig[];
+    /** 判断卡片类型是否已注册。 */
+    isCardTypeRegistered(type: string): boolean;
+    /** 开启文本编辑 Gizmo（选中并进入 textarea 编辑态）。 */
+    openTextGizmo(itemId: string): void;
+    /** 关闭文本编辑态。 */
+    closeTextGizmo(): void;
+    /** 开启蒙版 Gizmo（应用初始笔刷大小）。笔刷大小须为正有限数，非法值回退默认 1。 */
+    openMaskGizmo(brushSize: number): void;
+    /** 关闭蒙版 Gizmo。 */
+    closeMaskGizmo(): void;
+    /**
+     * 清空蒙版：移除已绘制的所有蒙版笔迹。
+     */
+    clearMaskGizmo(): void;
+    /**
+     * 设置蒙版 Gizmo 配置（笔刷大小 / 蒙版颜色 / 蒙版图片等）。
+     *
+     * 其中 maskImage 为运行时蒙版图片（非 MaskConfig 字段），单独写入 gizmo.maskImage。
+     * @param config 蒙版配置（笔刷大小 / 蒙版颜色 / 蒙版图片等）
+     */
+    setMaskGizmoConfig(config: Partial<MaskConfig> & {
+        maskImage?: HTMLImageElement;
+    }): void;
+    /**
+     * 设置蒙版 Gizmo 模式。
+     * @param mode 蒙版模式：笔刷涂抹 / 笔刷擦除 / 框选涂抹 / 框选擦除
+     */
+    setMaskGizmoMode(mode: 'paint' | 'erase' | 'box-paint' | 'box-erase'): void;
+    /**
+     * 设置蒙版 Gizmo 偏好（MaskConfig 全字段可选），覆盖 {@link maskConfig} 的产品级默认。
+     *
+     * @param config 要覆盖的 MaskGizmo 偏好子集（全字段可选；颜色为 number hex，如 0x6A34FF）
+     */
+    /** 开启 loading 覆盖（id 为 elementId，内部翻译为 instanceId）。 */
+    openLoadingGizmo(id: string, options?: LoadingItemOptions): void;
+    /** 更新 LoadingTip 属性。 */
+    updateLoadingGizmo(id: string, options: LoadingItemOptions): void;
+    /** 关闭 loading 覆盖。 */
+    closeLoadingGizmo(id: string): void;
+    /** 开启图片裁切 Gizmo。 */
+    openPictureCutGizmo(): void;
+    setPictureCutGizmoLockScale(lock: boolean): void;
+    /**
+     * 获取当前裁切信息（归一化裁切框 + 元素视图框），委托 PictureCutGizmo.getCutInfo。
+     * @returns 裁切信息；Gizmo 未就绪 / 未选中单个元素 / 结果无效时返回 undefined
+     */
+    getCutInfo(): {
+        cutBox: Box2;
+        itemBox: Box2;
+    } | undefined;
+    /**
+     * 获取归一化裁切包围盒（min/max ∈ [0,1]，相对元素包围盒），委托 PictureCutGizmo.getCutBox。
+     * @returns 归一化裁切框；Gizmo 未就绪时返回 undefined
+     */
+    getCutBox(): Box2 | undefined;
+    /**
+     * 设置归一化裁切包围盒（入参为归一化坐标），委托 PictureCutGizmo.setCutBox。
+     * @param normalizeBox 归一化裁切框
+     */
+    setCutBox(normalizeBox: Box2): void;
+    /** 关闭图片裁切 Gizmo。 */
+    closePictureCutGizmo(): void;
+    setPictureExpandGizmoLockScale(lock: boolean): void;
+    /**
+     * 获取当前扩边信息（归一化扩边框 + 元素视图框），委托 PictureExpandGizmo.getExpandInfo。
+     * @returns 扩边信息；Gizmo 未就绪 / 未选中单个元素 / 结果无效时返回 undefined
+     */
+    getExpandInfo(): {
+        expandBox: Box2;
+        itemBox: Box2;
+    } | undefined;
+    /**
+     * 获取归一化扩边包围盒（相对元素包围盒，可超出 [0,1]），委托 PictureExpandGizmo.getExpandBox。
+     * @returns 归一化扩边框；Gizmo 未就绪时返回 undefined
+     */
+    getExpandBox(): Box2 | undefined;
+    /**
+     * 设置归一化扩边包围盒（入参为归一化坐标），委托 PictureExpandGizmo.setExpandBox。
+     * @param normalizeBox 归一化扩边框
+     */
+    setExpandBox(normalizeBox: Box2): void;
+}

package/dist/artis/operations/scene-operations.d.ts

@@ -0,0 +1,26 @@
+import { Operations } from './operations';
+import type { spec } from '../../shared';
+/**
+ * SceneArtis 专属操作门面（`artis.operations` 在 SceneArtis 实例上的扩展形态）。
+ *
+ * 继承 {@link Operations} 全部基础功能（创建/删除/写属性/截图/导出媒体/对齐/gizmo 开关 …），
+ * 并追加 Scene 专属「场景 JSON 导出」家族——基于 SceneStore 实时回写的活动场景 JSON（浅克隆保护）。
+ *
+ * 仅 anxiety SceneArtis 经 `_createOperations` 工厂返回本类（见 SceneArtis override）。artis.operations
+ * 的 getter 类型在基类声明为 Operations；SceneArtis 消费侧可经类型断言或 `instanceof SceneOperations`
+ * 取本扩展，或在 SceneArtis 上另开 `get sceneOperations()` 强类型门面（按需，本类提供能力即可）。
+ *
+ * 边界：场景级生命周期方法（play/stop/seek/switchScene/setPlaying/setSafeAreaEnabled）属强生命周期
+ * 动词，留在 SceneArtis 顶层不迁入——不走通用 operations；本类只承载「导出场景 JSON」这一同质于
+ * Operations 导出语义、但 Scene 特有的能力。
+ */
+export declare class SceneOperations extends Operations {
+    /** 导出当前激活场景 JSON（已由 JsonSceneSyncService 实时回写，浅克隆保护）。无激活场景返回 undefined。 */
+    exportScene(): spec.JSONScene | undefined;
+    /** 按 id 导出指定场景 JSON；id 不存在返回 undefined。 */
+    exportSceneById(id: string): spec.JSONScene | undefined;
+    /** 按 index 导出指定场景 JSON；越界返回 undefined。 */
+    exportSceneByIndex(index: number): spec.JSONScene | undefined;
+    /** 导出全部场景 JSON（按 store 顺序）。 */
+    exportAllScenes(): spec.JSONScene[];
+}

package/dist/artis/operations/types.d.ts

@@ -0,0 +1,39 @@
+import { Box2 } from '@vvfx/gizmo';
+import type { ViewportFitShiftParam } from '../../core/types';
+/** 视图聚焦参数 */
+export type ViewportFitParam = ViewportFitToBoxParam | ViewportFitToItemsParam;
+/** 视图聚焦包围盒参数 */
+export type ViewportFitToBoxParam = {
+    /** 类型： 包围盒 */
+    type: 'box';
+    /** 偏移参数 */
+    shift?: ViewportFitShiftParam;
+    /** 目标包围盒 */
+    target?: Box2;
+};
+/** 视图聚焦元素参数 */
+export type ViewportFitToItemsParam = {
+    /** 类型： 元素 */
+    type: 'items';
+    /** 偏移参数 */
+    shift?: ViewportFitShiftParam;
+    /** 目标元素 */
+    target?: string[];
+};
+/** 初始化位置参数 */
+export type InitPositionOptions = {
+    /** 模式 */
+    layout?: 'free' | 'row';
+    /** 环绕模式 */
+    wrapMode?: 'wrap' | 'nowrap';
+    /** free 布局自动换行的 X 轴阈值，默认 12000px */
+    wrapThreshold?: number;
+    /** 计算落位时忽略的元素 ID，适用于已创建占位节点的异步元素 */
+    excludeIds?: string[];
+    /** 行锚点 */
+    rowAnchor?: [number, number];
+    /** 行缩放倍数 */
+    rowScale?: [number, number];
+    /** 偏移值 */
+    shift?: number;
+};