@vvfx/sdk 0.2.7 → 0.2.9

package/dist/utils/layout-utils.js

@@ -0,0 +1,1217 @@
+import { Box2 } from '../math/box2';
+import { Line2, Vector2 } from '../math';
+// ============================================
+// 工具函数
+// ============================================
+/**
+ * @description 将元素按行分组
+ * @param items 元素列表
+ * @returns 按行号分组的 Map
+ */
+function groupItemsByRow(items) {
+    const groups = new Map();
+    for (const item of items) {
+        const row = item.row ?? 0;
+        const group = groups.get(row);
+        if (group) {
+            group.push(item);
+        }
+        else {
+            groups.set(row, [item]);
+        }
+    }
+    return groups;
+}
+/**
+ * @description 将元素映射为带尺寸的列表
+ * @param items 元素列表
+ * @returns 带尺寸的元素列表
+ */
+function mapItemsWithSize(items) {
+    return items.map(item => {
+        const size = item.box.getSize();
+        return {
+            ...item,
+            width: size.x,
+            height: size.y,
+        };
+    });
+}
+/**
+ * @description 自动排布函数
+ * 根据元素信息中的行列数参数进行排布：
+ * - 如果元素有 row/column，则按指定行列排布
+ * - 如果元素没有 row/column，则使用 Shelf 算法自动生成行列数，再排布
+ *
+ * @param canvasBox 画布范围（Box2），min为左上角，max为右下角
+ * @param items 元素信息列表（包含 ID、Box2、可选的 row/column）
+ * @param options 可选配置（padding, gap）
+ * @returns 各元素的位置信息和整体尺寸
+ */
+export function autoLayout(items, options = {}) {
+    if (items.length === 0) {
+        const padding = options.padding ?? 20;
+        return { items: [], size: [padding * 2, padding * 2] };
+    }
+    const padding = options.padding ?? 20;
+    const gap = options.gap ?? 5;
+    const itemsWithSize = mapItemsWithSize(items);
+    // 判断是否有任意元素有行列信息
+    const hasAnyLayoutInfo = itemsWithSize.some(item => item.row !== undefined);
+    let layoutResult;
+    if (hasAnyLayoutInfo) {
+        // 有布局信息，使用混合排布
+        layoutResult = calculateMixedLayout(itemsWithSize, padding, gap);
+    }
+    else {
+        // 没有布局信息，使用 Shelf 算法
+        layoutResult = calculateShelfLayout(itemsWithSize, padding, gap, options.config);
+    }
+    // 转换为输出格式
+    const result = layoutResult.items.map(item => {
+        return {
+            id: item.id,
+            position: [item.x, item.y],
+            row: item.row,
+            column: item.column,
+        };
+    });
+    return {
+        items: result,
+        size: layoutResult.size,
+    };
+}
+/**
+ * @description Shelf 算法计算自动布局
+ * 为单个元素判断是否有 row 信息：
+ * - 有 row 的元素：使用指定的 row，在该行内使用 Shelf 算法排列
+ * - 无 row 的元素：通过 Shelf 算法自动计算 row 和 column
+ *
+ * 支持 AutoLayoutConfig：
+ * - maxRowWidth: 单行最大宽度，超过后自动换行
+ * - maxRowCount: 最大行数限制
+ *
+ * @param items 元素列表（包含可选的 row）
+ * @param padding 边距
+ * @param gap 元素间隔
+ * @param config 自动布局配置（可选）
+ * @returns 计算后的位置、行列号和整体尺寸
+ */
+function calculateShelfLayout(items, padding, gap, config) {
+    if (items.length === 0) {
+        return { items: [], size: [padding * 2, padding * 2] };
+    }
+    // 按 row 分组（无 row 的分配到 row 0）
+    const rowGroups = groupItemsByRow(items);
+    // 按行号排序
+    const sortedRows = Array.from(rowGroups.keys()).sort((a, b) => a - b);
+    const placedItems = [];
+    let currentY = padding;
+    let maxX = padding;
+    // 处理每一行
+    for (const row of sortedRows) {
+        const rowItems = rowGroups.get(row);
+        if (!rowItems) {
+            continue;
+        }
+        let currentX = padding;
+        let currentShelfHeight = 0;
+        let column = 0;
+        let currentRowCount = 1;
+        for (const item of rowItems) {
+            const { x: width, y: height } = item.box.getSize();
+            // 检查是否超出最大行宽
+            const wouldExceedMaxWidth = config?.maxRowWidth !== undefined &&
+                currentX + width + padding > config.maxRowWidth;
+            // 检查是否需要换行（同一行号内的自动换行）
+            let needNewShelf = wouldExceedMaxWidth && currentX > padding;
+            // 检查是否达到最大行数限制
+            if (needNewShelf && config?.maxRowCount !== undefined) {
+                if (currentRowCount >= config.maxRowCount) {
+                    needNewShelf = false;
+                }
+            }
+            if (needNewShelf) {
+                // 当前行号内开新 shelf
+                currentY += currentShelfHeight + gap;
+                currentX = padding;
+                currentShelfHeight = height;
+                column = 0;
+                currentRowCount++;
+            }
+            else {
+                // 同一行内，更新 shelf 高度
+                currentShelfHeight = Math.max(currentShelfHeight, height);
+            }
+            // 放置当前元素（中心点坐标）
+            placedItems.push({
+                id: item.id,
+                x: currentX + width / 2,
+                y: currentY + height / 2,
+                row,
+                column,
+            });
+            // 更新最大 X
+            maxX = Math.max(maxX, currentX + width + padding);
+            // 移动到下一个位置
+            currentX += width + gap;
+            column++;
+        }
+        // 完成当前行号的所有元素，移动到下一行
+        if (rowItems.length > 0) {
+            currentY += currentShelfHeight + gap;
+        }
+    }
+    // 计算画板大小
+    const maxY = Math.max(currentY - gap + padding, padding * 2);
+    return {
+        items: placedItems,
+        size: [Math.max(maxX, padding * 2), maxY],
+    };
+}
+/**
+ * @description 混合排布算法
+ * 有 row/column 的元素按指定位置排布
+ * 无 row/column 的元素自动填充空位
+ *
+ * @param items 元素列表（包含宽高和可选的行列信息）
+ * @param padding 边距
+ * @param gap 元素间隔
+ * @returns 计算后的位置、行列号和整体尺寸
+ */
+function calculateMixedLayout(items, padding, gap) {
+    if (items.length === 0) {
+        return { items: [], size: [padding * 2, padding * 2] };
+    }
+    // 按 row 分组（无 row 的分配到 row 0）
+    const rowGroups = groupItemsByRow(items);
+    // 按行号排序
+    const sortedRows = Array.from(rowGroups.keys()).sort((a, b) => a - b);
+    const placedItems = [];
+    let currentY = padding;
+    let maxX = padding;
+    // 处理每一行
+    for (const row of sortedRows) {
+        const rowItems = rowGroups.get(row);
+        if (!rowItems) {
+            continue;
+        }
+        // 分离有 column 和无 column 的元素
+        const withColumn = rowItems.filter(i => i.column !== undefined);
+        const withoutColumn = rowItems.filter(i => i.column === undefined);
+        // 计算行高
+        const rowHeight = Math.max(...rowItems.map(i => i.box.getSize().y), 0);
+        // 为所有元素分配列号
+        const columnAssignments = new Map();
+        const columnWidths = new Map(); // 记录每列宽度
+        // 1. 先处理有 column 的元素（优先）
+        const sortedWithColumn = [...withColumn].sort((a, b) => (a.column ?? 0) - (b.column ?? 0));
+        for (const item of sortedWithColumn) {
+            let targetColumn = item.column ?? 0;
+            // 如果目标列被占用，顺延到下一个可用列
+            while (columnAssignments.has(targetColumn)) {
+                targetColumn++;
+            }
+            columnAssignments.set(targetColumn, item);
+            columnWidths.set(targetColumn, item.box.getSize().x);
+        }
+        // 2. 为无 column 的元素填充空位
+        let nextColumn = 0;
+        for (const item of withoutColumn) {
+            while (columnAssignments.has(nextColumn)) {
+                nextColumn++;
+            }
+            columnAssignments.set(nextColumn, item);
+            columnWidths.set(nextColumn, item.box.getSize().x);
+            nextColumn++;
+        }
+        // 3. 按列号顺序计算位置（优化：使用累积宽度计算）
+        const allColumns = Array.from(columnAssignments.keys()).sort((a, b) => a - b);
+        let currentX = padding;
+        for (const column of allColumns) {
+            const item = columnAssignments.get(column);
+            const width = columnWidths.get(column);
+            if (!item || width === undefined) {
+                continue;
+            }
+            placedItems.push({
+                id: item.id,
+                x: currentX + width / 2,
+                y: currentY + item.box.getSize().y / 2,
+                row,
+                column,
+            });
+            maxX = Math.max(maxX, currentX + width + padding);
+            currentX += width + gap;
+        }
+        // 移动到下一行
+        currentY += rowHeight + gap;
+    }
+    // 计算画板大小
+    const maxY = Math.max(currentY - gap + padding, padding * 2);
+    return {
+        items: placedItems,
+        size: [Math.max(maxX, padding * 2), maxY],
+    };
+}
+/**
+ * @description 计算元素到目标位置的位移
+ * @param currentPosition 当前位置 [x, y]
+ * @param targetPosition 目标位置 [x, y]
+ * @returns 位移向量 [dx, dy]
+ */
+export function calculateDisplacement(currentPosition, targetPosition) {
+    return [
+        targetPosition[0] - currentPosition[0],
+        targetPosition[1] - currentPosition[1],
+    ];
+}
+/**
+ * @description 为 autoLayout 结果计算位移信息
+ * @param items 元素列表（包含当前位置）
+ * @param layoutResult autoLayout 的返回结果
+ * @returns 每个元素的位移信息
+ */
+export function calculateLayoutDisplacements(items, layoutResult) {
+    return layoutResult.items.map(layoutItem => {
+        const currentItem = items.find(i => i.id === layoutItem.id);
+        const currentPosition = currentItem?.currentPosition ?? [0, 0];
+        return {
+            id: layoutItem.id,
+            displacement: calculateDisplacement(currentPosition, layoutItem.position),
+            targetPosition: layoutItem.position,
+        };
+    });
+}
+// ============================================
+// 自动布局拖拽相关函数
+// ============================================
+/**
+ * @description 计算自动布局指示线位置
+ * @param position 插入位置信息
+ * @param getViewBoxById 获取元素包围盒的函数
+ * @returns 主指示线
+ */
+export function calculateAutoLayoutIndicatorLine(position, getViewBoxById) {
+    const LINE_EXTENSION = 10;
+    const MOUSE_GAP = 5;
+    const ROW_LINE_EXTENSION = 20;
+    // 如果是换行操作，绘制水平行级指示线
+    if (position.rowChange?.isRowChange && position.rowChange.rowBounds) {
+        const bounds = position.rowChange.rowBounds;
+        const isMovingUp = position.rowChange.toRow < position.rowChange.fromRow;
+        // 向上移动（到更小的行号）：线在当前行上方
+        // 向下移动（到更大的行号）：线在当前行下方
+        const lineY = isMovingUp ? bounds.minY : bounds.maxY;
+        return new Line2(new Vector2(bounds.minX - ROW_LINE_EXTENSION, lineY), new Vector2(bounds.maxX + ROW_LINE_EXTENSION, lineY));
+    }
+    // 同行内移动，绘制列级垂直指示线
+    if (position.siblingId) {
+        const siblingBox = getViewBoxById(position.siblingId);
+        if (position.direction === 'before') {
+            return new Line2(new Vector2(siblingBox.min.x - MOUSE_GAP, siblingBox.min.y - LINE_EXTENSION), new Vector2(siblingBox.min.x - MOUSE_GAP, siblingBox.max.y + LINE_EXTENSION));
+        }
+        else {
+            return new Line2(new Vector2(siblingBox.max.x + MOUSE_GAP, siblingBox.min.y - LINE_EXTENSION), new Vector2(siblingBox.max.x + MOUSE_GAP, siblingBox.max.y + LINE_EXTENSION));
+        }
+    }
+    return new Line2();
+}
+/**
+ * @description 基于鼠标位置计算布局位置（row 和 column）
+ * @param mousePoint 鼠标位置
+ * @param allItems 所有子元素
+ * @param getViewBoxById 获取元素包围盒的函数
+ * @param getLayoutInfo 获取元素布局信息的函数
+ * @param excludeItemId 需要排除的元素ID（被拖拽的元素）
+ * @returns 布局位置信息 { row: number, column: number }
+ */
+export function calculateAutoLayoutPositionByMouse(mousePoint, allItems, getViewBoxById, getLayoutInfo, excludeItemId) {
+    // 排除被拖拽的元素
+    const siblings = allItems.filter(item => item.id !== excludeItemId);
+    if (siblings.length === 0) {
+        return { row: 0, column: 0 };
+    }
+    const siblingsWithInfo = siblings
+        .map(sibling => {
+        const box = getViewBoxById(sibling.id);
+        return {
+            id: sibling.id,
+            box,
+            center: box.getCenter(),
+            layoutInfo: getLayoutInfo(sibling),
+        };
+    })
+        .filter(item => !item.box.isEmpty());
+    if (siblingsWithInfo.length === 0) {
+        return { row: 0, column: 0 };
+    }
+    const mouseY = mousePoint.y;
+    const mouseX = mousePoint.x;
+    // 使用已有行号信息进行分组
+    const rowGroups = groupItemsByRow(siblingsWithInfo.map(s => ({
+        ...s,
+        row: s.layoutInfo?.row !== undefined ? Math.floor(s.layoutInfo.row) : 0,
+    })));
+    let maxRow = 0;
+    let minRow = 0;
+    for (const row of rowGroups.keys()) {
+        maxRow = Math.max(maxRow, row);
+        minRow = Math.min(minRow, row);
+    }
+    const rowInfos = [];
+    for (const [row, items] of rowGroups) {
+        const minY = Math.min(...items.map(i => i.box.min.y));
+        const maxY = Math.max(...items.map(i => i.box.max.y));
+        const centerY = (minY + maxY) / 2;
+        const height = maxY - minY;
+        rowInfos.push({ row, centerY, minY, maxY, height });
+    }
+    // 按 Y 坐标排序
+    rowInfos.sort((a, b) => a.centerY - b.centerY);
+    // 确定目标行号
+    let targetRow = 0;
+    // 检查鼠标是否在某行的垂直范围内
+    let foundRow = false;
+    for (const currentRow of rowInfos) {
+        if (mouseY >= currentRow.minY && mouseY <= currentRow.maxY) {
+            targetRow = currentRow.row;
+            foundRow = true;
+            break;
+        }
+    }
+    // 如果鼠标在所有行上方，创建新行（row -1）
+    if (!foundRow && rowInfos.length > 0) {
+        const firstRow = rowInfos[0];
+        if (firstRow && mouseY < firstRow.minY) {
+            targetRow = minRow - 1;
+            foundRow = true;
+        }
+    }
+    // 如果鼠标在所有行下方，创建新行
+    if (!foundRow && rowInfos.length > 0) {
+        const lastRow = rowInfos[rowInfos.length - 1];
+        if (lastRow && mouseY > lastRow.maxY) {
+            targetRow = maxRow + 1;
+            foundRow = true;
+        }
+    }
+    // 默认使用最近的行
+    if (!foundRow) {
+        let minDistance = Infinity;
+        for (const rowInfo of rowInfos) {
+            const distance = Math.abs(mouseY - rowInfo.centerY);
+            if (distance < minDistance) {
+                minDistance = distance;
+                targetRow = rowInfo.row;
+            }
+        }
+    }
+    // 在目标行内确定列号
+    const targetRowItems = rowGroups.get(targetRow) ?? [];
+    // 如果目标行没有元素，从第0列开始
+    if (targetRowItems.length === 0) {
+        return { row: targetRow, column: 0 };
+    }
+    // 按 X 坐标排序
+    targetRowItems.sort((a, b) => a.center.x - b.center.x);
+    // 找到鼠标的插入位置
+    for (let i = 0; i < targetRowItems.length; i++) {
+        const item = targetRowItems[i];
+        if (item && mouseX < item.center.x) {
+            return { row: targetRow, column: i };
+        }
+    }
+    // 鼠标在该行所有元素右侧，添加到最后
+    return { row: targetRow, column: targetRowItems.length };
+}
+/**
+ * @description 基于鼠标位置计算插入位置（用于显示指示器）
+ * @param mousePoint 鼠标位置
+ * @param allItems 所有子元素
+ * @param excludeItemId 需要排除的元素ID（被拖拽的元素）
+ * @param parent 父画板
+ * @param originalRow 原始行号
+ * @param getSelectedItemsBox 获取选中项包围盒的函数
+ * @returns 插入位置信息和计算出的行列位置
+ */
+export function calculateInsertPositionFromLayout(mousePoint, allItems, excludeItemId, parent, originalRow, getViewBoxById, getSelectedItemsBox) {
+    const mouseX = mousePoint.x;
+    const mouseY = mousePoint.y;
+    // 排除被拖拽的元素
+    const siblings = allItems.filter(item => item.id !== excludeItemId);
+    if (siblings.length === 0) {
+        return { index: 0, direction: 'after', row: -1, column: 0 };
+    }
+    const siblingsWithInfo = siblings
+        .map(item => {
+        const box = getViewBoxById(item.id);
+        if (box.isEmpty()) {
+            return null;
+        }
+        const layoutInfo = parent.property.layoutInfos?.[item.id];
+        return {
+            item,
+            box,
+            row: Math.floor(layoutInfo?.row ?? 0),
+            column: layoutInfo?.column ?? 0,
+            centerX: box.getCenter().x,
+        };
+    })
+        .filter((info) => info !== null);
+    if (siblingsWithInfo.length === 0) {
+        return { index: 0, direction: 'after', row: -1, column: 0 };
+    }
+    // 按行号分组，计算每行的垂直边界
+    const rowGroups = groupItemsByRow(siblingsWithInfo);
+    // 计算每行的边界（minY, maxY, minX, maxX）
+    const rowBounds = new Map();
+    for (const [row, items] of rowGroups) {
+        const minY = Math.min(...items.map(i => i.box.min.y));
+        const maxY = Math.max(...items.map(i => i.box.max.y));
+        const minX = Math.min(...items.map(i => i.box.min.x));
+        const maxX = Math.max(...items.map(i => i.box.max.x));
+        rowBounds.set(row, { minY, maxY, minX, maxX });
+    }
+    // 按行号排序
+    const sortedRows = Array.from(rowGroups.keys()).sort((a, b) => a - b);
+    // 步骤1：确定目标行
+    let targetRow = -1;
+    // 检查鼠标是否在某行的垂直范围内
+    for (const row of sortedRows) {
+        const bounds = rowBounds.get(row);
+        if (bounds && mouseY >= bounds.minY && mouseY <= bounds.maxY) {
+            targetRow = row;
+            break;
+        }
+    }
+    // 如果没有找到行，检查鼠标是否在所有行上方
+    if (targetRow === -1 && sortedRows.length > 0) {
+        const firstRowNum = sortedRows[0];
+        if (firstRowNum === undefined) {
+            targetRow = -1;
+        }
+        else {
+            const firstRowBounds = rowBounds.get(firstRowNum);
+            if (firstRowBounds && mouseY < firstRowBounds.minY) {
+                targetRow = -1; // 在所有行上方
+            }
+            else {
+                // 鼠标在所有行下方，使用最后一行
+                targetRow = sortedRows[sortedRows.length - 1] ?? -1;
+            }
+        }
+    }
+    // 计算是否换行
+    const currentRowBounds = rowBounds.get(originalRow);
+    const isRowChange = targetRow !== originalRow;
+    // 步骤2：在目标行内确定插入位置
+    const targetRowItems = rowGroups.get(targetRow) ?? [];
+    // 如果目标行没有元素（可能是 -1 行或空行），需要找到参考点
+    if (targetRowItems.length === 0) {
+        // 找到目标行位置的第一个元素作为参考
+        let referenceItem = null;
+        for (const [row, items] of rowGroups) {
+            if (row > targetRow && items.length > 0) {
+                const firstItem = items[0];
+                if (firstItem) {
+                    referenceItem = firstItem.item;
+                    break;
+                }
+            }
+        }
+        if (!referenceItem) {
+            // 使用最后一个元素
+            const lastRow = sortedRows[sortedRows.length - 1];
+            const lastRowItems = lastRow !== undefined ? rowGroups.get(lastRow) ?? [] : [];
+            referenceItem = lastRowItems[lastRowItems.length - 1]?.item ?? null;
+        }
+        if (referenceItem) {
+            const refIndex = parent.children.indexOf(referenceItem.id);
+            if (refIndex !== -1) {
+                return {
+                    index: targetRow === -1 ? refIndex : refIndex + 1,
+                    direction: targetRow === -1 ? 'before' : 'after',
+                    siblingId: referenceItem.id,
+                    row: targetRow,
+                    column: targetRow === -1 ? 0 : (rowGroups.get(targetRow)?.length ?? 0),
+                    rowChange: isRowChange && currentRowBounds ? {
+                        fromRow: originalRow,
+                        toRow: targetRow,
+                        rowBounds: currentRowBounds,
+                        isRowChange,
+                    } : undefined,
+                };
+            }
+        }
+        return {
+            index: 0,
+            direction: 'after',
+            row: targetRow,
+            column: 0,
+            rowChange: isRowChange && currentRowBounds ? {
+                fromRow: originalRow,
+                toRow: targetRow,
+                rowBounds: currentRowBounds,
+                isRowChange,
+            } : undefined,
+        };
+    }
+    // 按X坐标排序
+    targetRowItems.sort((a, b) => a.centerX - b.centerX);
+    // 步骤2：在行内基于鼠标X坐标确定插入位置
+    for (const info of targetRowItems) {
+        if (mouseX < info.centerX) {
+            // 鼠标在元素中心左侧，插入到该元素之前
+            const refIndex = parent.children.indexOf(info.item.id);
+            if (refIndex !== -1) {
+                return {
+                    index: refIndex,
+                    direction: 'before',
+                    siblingId: info.item.id,
+                    row: targetRow,
+                    column: info.column,
+                    rowChange: isRowChange && currentRowBounds ? {
+                        fromRow: originalRow,
+                        toRow: targetRow,
+                        rowBounds: currentRowBounds,
+                        isRowChange: true,
+                    } : undefined,
+                };
+            }
+        }
+    }
+    // 鼠标在该行所有元素右侧，添加到最后
+    const lastItem = targetRowItems[targetRowItems.length - 1];
+    if (lastItem) {
+        const refIndex = parent.children.indexOf(lastItem.item.id);
+        if (refIndex !== -1) {
+            return {
+                index: refIndex + 1,
+                direction: 'after',
+                siblingId: lastItem.item.id,
+                row: targetRow,
+                column: lastItem.column + 1,
+                rowChange: isRowChange && currentRowBounds ? {
+                    fromRow: originalRow,
+                    toRow: targetRow,
+                    rowBounds: currentRowBounds,
+                    isRowChange: true,
+                } : undefined,
+            };
+        }
+    }
+    return {
+        index: 0,
+        direction: 'after',
+        row: -1,
+        column: 0,
+        rowChange: isRowChange && currentRowBounds ? {
+            fromRow: originalRow,
+            toRow: targetRow,
+            rowBounds: currentRowBounds,
+            isRowChange: true,
+        } : undefined,
+    };
+}
+/**
+ * @description 更新元素的 layoutInfo
+ * @param item 要更新的元素
+ * @param parent 父画板
+ * @param layoutPosition 新的布局位置
+ */
+export function updateItemLayoutInfo(item, parent, layoutPosition) {
+    // 初始化 layoutInfos 如果不存在
+    parent.property.layoutInfos ??= {};
+    // 更新被拖拽元素的 layoutInfo
+    const currentInfo = parent.property.layoutInfos[item.id];
+    parent.property.layoutInfos[item.id] = {
+        ...currentInfo,
+        row: layoutPosition.row,
+        column: layoutPosition.column,
+    };
+}
+// ============================================
+// 全局自适应排布
+// ============================================
+/**
+ * @description 分析元素特征，判断更适合哪种排列方式
+ * @param elements 元素列表
+ * @returns aspectRatioHint 建议的宽高比倾向 (>1倾向于横向, <1倾向于纵向)
+ */
+function analyzeElements(elements) {
+    if (elements.length === 0) {
+        return 1;
+    }
+    let totalWidth = 0;
+    let totalHeight = 0;
+    let tallCount = 0; // 高瘦元素数量
+    let wideCount = 0; // 矮胖元素数量
+    for (const el of elements) {
+        const size = el.box.getSize();
+        totalWidth += size.x;
+        totalHeight += size.y;
+        // 判断元素形状：宽高比 > 1.2 认为是宽胖的，< 0.8 认为是高瘦的
+        const aspectRatio = size.x / size.y;
+        if (aspectRatio < 0.8) {
+            tallCount++;
+        }
+        else if (aspectRatio > 1.2) {
+            wideCount++;
+        }
+    }
+    // 计算平均宽高比
+    const avgAspectRatio = totalWidth / totalHeight;
+    // 综合判断：高瘦元素多时倾向横向排列（行内堆叠）
+    // 矮胖元素多时倾向纵向排列（列内堆叠）
+    if (tallCount > wideCount) {
+        return Math.max(avgAspectRatio, 1.5);
+    }
+    else if (wideCount > tallCount) {
+        return Math.min(avgAspectRatio, 0.67);
+    }
+    return avgAspectRatio;
+}
+/**
+ * @description 计算元素总面积和最大尺寸
+ */
+function calculateElementsStats(elements, gap) {
+    let totalArea = 0;
+    let maxWidth = 0;
+    let maxHeight = 0;
+    for (const el of elements) {
+        const size = el.box.getSize();
+        const w = size.x + gap;
+        const h = size.y + gap;
+        totalArea += w * h;
+        maxWidth = Math.max(maxWidth, w);
+        maxHeight = Math.max(maxHeight, h);
+    }
+    return { totalArea, maxWidth, maxHeight };
+}
+/**
+ * @description 计算目标尺寸
+ * 根据元素总面积和目标宽高比，计算容器尺寸
+ */
+function calculateTargetSize(items, gap, targetAspectRatio = 1) {
+    if (items.length === 0) {
+        return { targetWidth: 0, targetHeight: 0 };
+    }
+    const { totalArea, maxWidth, maxHeight } = calculateElementsStats(items, gap);
+    // 减去最后一个元素的gap
+    const adjustedArea = totalArea - gap * gap * items.length;
+    // 根据目标宽高比计算容器尺寸
+    // width / height = targetAspectRatio
+    // width * height = totalArea
+    // => width = sqrt(totalArea * targetAspectRatio)
+    // => height = sqrt(totalArea / targetAspectRatio)
+    const targetWidth = Math.sqrt(adjustedArea * targetAspectRatio);
+    const targetHeight = Math.sqrt(adjustedArea / targetAspectRatio);
+    return {
+        targetWidth: Math.max(targetWidth, maxWidth),
+        targetHeight: Math.max(targetHeight, maxHeight),
+    };
+}
+/**
+ * @description 纵向排列策略（列优先）
+ * 元素在垂直方向堆叠，溢出后开新列
+ */
+function calculateColumnLayout(elements, gap, targetAspectRatio = 1) {
+    const { targetHeight } = calculateTargetSize(elements, gap, targetAspectRatio);
+    // 按高度从高到低排序
+    const sortedElements = [...elements].sort((a, b) => {
+        return b.box.getSize().y - a.box.getSize().y;
+    });
+    const columns = [];
+    const resultItems = [];
+    for (const element of sortedElements) {
+        const size = element.box.getSize();
+        const elementHeight = size.y + gap;
+        const elementWidth = size.x;
+        let placed = false;
+        for (const col of columns) {
+            if (col.filledHeight + elementHeight <= targetHeight + gap) {
+                resultItems.push({
+                    id: element.id,
+                    position: [
+                        col.x + elementWidth / 2,
+                        col.filledHeight + size.y / 2,
+                    ],
+                });
+                col.filledHeight += elementHeight;
+                col.maxWidth = Math.max(col.maxWidth, elementWidth);
+                placed = true;
+                break;
+            }
+        }
+        if (!placed) {
+            const lastCol = columns[columns.length - 1];
+            const newX = lastCol ? lastCol.x + lastCol.maxWidth + gap : 0;
+            resultItems.push({
+                id: element.id,
+                position: [
+                    newX + elementWidth / 2,
+                    size.y / 2,
+                ],
+            });
+            columns.push({
+                x: newX,
+                filledHeight: elementHeight,
+                maxWidth: elementWidth,
+            });
+        }
+    }
+    let maxX = 0;
+    let maxY = 0;
+    for (const col of columns) {
+        maxX = Math.max(maxX, col.x + col.maxWidth);
+        maxY = Math.max(maxY, col.filledHeight);
+    }
+    if (columns.length > 0) {
+        maxY -= gap;
+    }
+    const boundingBox = new Box2(new Vector2(0, 0), new Vector2(maxX, Math.max(0, maxY)));
+    const score = calculateLayoutScore(boundingBox);
+    return { items: resultItems, boundingBox, score };
+}
+/**
+ * @description 几何工具函数
+ */
+/**
+ * @description 判断矩形是否包含另一个矩形
+ */
+function rectContains(outer, inner) {
+    return inner.x >= outer.x &&
+        inner.y >= outer.y &&
+        inner.x + inner.width <= outer.x + outer.width &&
+        inner.y + inner.height <= outer.y + outer.height;
+}
+/**
+ * @description 判断两个矩形是否相交
+ */
+function rectIntersects(a, b) {
+    return a.x < b.x + b.width &&
+        a.x + a.width > b.x &&
+        a.y < b.y + b.height &&
+        a.y + a.height > b.y;
+}
+/**
+ * @description 计算布局结果分数（越接近正方形越好）
+ */
+function calculateLayoutScore(boundingBox) {
+    const size = boundingBox.getSize();
+    const aspect = size.x / Math.max(size.y, 1);
+    // 分数：越接近1（正方形）越好，同时考虑面积利用率
+    return -Math.abs(aspect - 1) * 100 + Math.min(size.x * size.y, 10000);
+}
+/**
+ * @description 分割空闲矩形，返回不与放置矩形重叠的部分
+ * 使用 MaxRects 的标准分割策略：四向分割
+ */
+function splitFreeRect(freeRect, placed) {
+    const result = [];
+    // 如果放置矩形与空闲矩形不相交，直接返回原矩形
+    if (!rectIntersects(freeRect, placed)) {
+        return [freeRect];
+    }
+    // 上方区域
+    if (placed.y > freeRect.y) {
+        result.push({
+            x: freeRect.x,
+            y: freeRect.y,
+            width: freeRect.width,
+            height: placed.y - freeRect.y,
+        });
+    }
+    // 下方区域
+    const placedBottom = placed.y + placed.height;
+    const freeBottom = freeRect.y + freeRect.height;
+    if (placedBottom < freeBottom) {
+        result.push({
+            x: freeRect.x,
+            y: placedBottom,
+            width: freeRect.width,
+            height: freeBottom - placedBottom,
+        });
+    }
+    // 左侧区域
+    if (placed.x > freeRect.x) {
+        result.push({
+            x: freeRect.x,
+            y: freeRect.y,
+            width: placed.x - freeRect.x,
+            height: freeRect.height,
+        });
+    }
+    // 右侧区域
+    const placedRight = placed.x + placed.width;
+    const freeRight = freeRect.x + freeRect.width;
+    if (placedRight < freeRight) {
+        result.push({
+            x: placedRight,
+            y: freeRect.y,
+            width: freeRight - placedRight,
+            height: freeRect.height,
+        });
+    }
+    return result;
+}
+/**
+ * @description 过滤掉被其他矩形包含的冗余矩形
+ * 优化：先按面积排序，面积大的只可能包含面积小的，不会相反
+ */
+function pruneFreeRects(rects) {
+    if (rects.length <= 1) {
+        return rects;
+    }
+    // 按面积从大到小排序
+    const sortedRects = [...rects].sort((a, b) => (b.width * b.height) - (a.width * a.height));
+    const result = [];
+    for (let i = 0; i < sortedRects.length; i++) {
+        const rect = sortedRects[i];
+        if (!rect) {
+            continue;
+        }
+        let contained = false;
+        // 只需要检查面积更大的矩形（前面的）
+        for (let j = 0; j < i; j++) {
+            const largerRect = sortedRects[j];
+            if (largerRect && rectContains(largerRect, rect)) {
+                contained = true;
+                break;
+            }
+        }
+        if (!contained) {
+            result.push(rect);
+        }
+    }
+    return result;
+}
+/**
+ * @description 从空闲矩形列表中找出最佳放置位置
+ * 使用 Bottom-Left 策略：优先 y 小，然后 x 小
+ */
+function findBestPlacement(freeRects, width, height) {
+    let best = null;
+    for (const rect of freeRects) {
+        // 检查是否能容纳（考虑间隙，但放置时不包含间隙）
+        if (rect.width >= width && rect.height >= height) {
+            // BLF 评分：y 坐标越小越好，y 相同则 x 越小越好
+            const score = rect.y * 10000 + rect.x;
+            if (!best || score < best.score) {
+                best = { rect, x: rect.x, y: rect.y, score };
+            }
+        }
+    }
+    return best ? { rect: best.rect, x: best.x, y: best.y } : null;
+}
+/**
+ * @description MaxRects 算法实现的布局
+ *
+ * MaxRects（Maximum Rectangles）是一种高效的 2D 矩形打包算法：
+ * 1. 维护一个"最大空闲矩形"列表，表示所有可用的放置空间
+ * 2. 每次放置元素时，从空闲矩形中选择一个最佳位置
+ * 3. 放置后，将相交的空闲矩形分割，并移除被完全包含的冗余矩形
+ * 4. 相比 BLF，MaxRects 能利用更多不规则的空间，生成更紧凑的布局
+ *
+ * 算法优势：
+ * - 能利用 L 型等不规则空隙
+ * - 支持多种放置策略（Bottom-Left、Best-Fit 等）
+ * - 布局密度通常比 Shelf 和 BLF 更高
+ */
+function calculateMaxRectsLayout(elements, gap, targetAspectRatio = 1) {
+    if (elements.length === 0) {
+        return {
+            items: [],
+            boundingBox: new Box2(new Vector2(0, 0), new Vector2(0, 0)),
+            score: 0,
+        };
+    }
+    void targetAspectRatio;
+    // 按面积从大到小排序（大的先放置有助于形成稳定的基础结构）
+    const sortedElements = [...elements].sort((a, b) => {
+        const sizeA = a.box.getSize();
+        const sizeB = b.box.getSize();
+        return sizeB.x * sizeB.y - sizeA.x * sizeA.y;
+    });
+    // 计算预估容器大小
+    let totalWidth = 0;
+    let totalHeight = 0;
+    const { maxWidth: maxElementWidth, maxHeight: maxElementHeight } = calculateElementsStats(sortedElements, 0);
+    for (const el of sortedElements) {
+        const size = el.box.getSize();
+        totalWidth += size.x;
+        totalHeight += size.y;
+    }
+    // 初始空闲矩形：足够容纳所有元素
+    const gridSize = Math.ceil(Math.sqrt(sortedElements.length));
+    const initialWidth = Math.max(totalWidth, maxElementWidth * gridSize);
+    const initialHeight = Math.max(totalHeight, maxElementHeight * gridSize);
+    // 空闲矩形列表，初始为一个大矩形
+    let freeRects = [{
+            x: 0,
+            y: 0,
+            width: initialWidth * 2,
+            height: initialHeight * 2,
+        }];
+    const placedItems = [];
+    const resultItems = [];
+    for (const element of sortedElements) {
+        const size = element.box.getSize();
+        const width = size.x;
+        const height = size.y;
+        // 包含间隙的实际占用大小
+        const occupiedWidth = width + gap;
+        const occupiedHeight = height + gap;
+        // 在空闲矩形中查找最佳位置
+        const placement = findBestPlacement(freeRects, occupiedWidth, occupiedHeight);
+        if (!placement) {
+            // 理论上不应该发生，但如果发生，扩大容器重试
+            console.warn(`MaxRects: 无法为元素 ${element.id} 找到放置位置`);
+            continue;
+        }
+        // 放置元素
+        const placedRect = {
+            id: element.id,
+            x: placement.x,
+            y: placement.y,
+            width: occupiedWidth,
+            height: occupiedHeight,
+        };
+        placedItems.push(placedRect);
+        resultItems.push({
+            id: element.id,
+            position: [
+                placement.x + width / 2,
+                placement.y + height / 2,
+            ],
+        });
+        // 更新空闲矩形列表
+        const newFreeRects = [];
+        for (const freeRect of freeRects) {
+            // 将相交的空闲矩形分割
+            const splitRects = splitFreeRect(freeRect, placedRect);
+            newFreeRects.push(...splitRects);
+        }
+        // 过滤掉被包含的冗余矩形
+        freeRects = pruneFreeRects(newFreeRects);
+        // 限制空闲矩形数量，避免性能问题
+        if (freeRects.length > 100) {
+            // 优先保留靠近原点的矩形（更可能被使用）
+            freeRects.sort((a, b) => (a.y + a.x) - (b.y + b.x));
+            freeRects = freeRects.slice(0, 100);
+        }
+    }
+    // 计算包围盒
+    let maxX = 0;
+    let maxY = 0;
+    for (const item of placedItems) {
+        // 减去间隙，只计算实际内容区域
+        maxX = Math.max(maxX, item.x + item.width - gap);
+        maxY = Math.max(maxY, item.y + item.height - gap);
+    }
+    const boundingBox = new Box2(new Vector2(0, 0), new Vector2(maxX, maxY));
+    const score = calculateLayoutScore(boundingBox);
+    return { items: resultItems, boundingBox, score };
+}
+/**
+ * @description 横向排列策略（使用 MaxRects 算法）
+ * MaxRects 算法能生成比 Shelf 和 BLF 更紧凑的二维布局
+ */
+function calculateRowLayout(elements, gap, targetAspectRatio = 1) {
+    // 使用 MaxRects 算法作为横向排列的实现
+    return calculateMaxRectsLayout(elements, gap, targetAspectRatio);
+}
+/**
+ * @description 基于顺序的流式行排布（Shelf算法）
+ * 保持元素输入顺序，每行尽可能多地放置元素
+ *
+ * 特点：
+ * - 不限制每行元素个数，只要空间够就继续放置
+ * - 通过目标行宽控制整体布局接近正方形
+ * - 保持输入顺序，行优先
+ *
+ * 例如：元素1,2在第一行放得下，元素3,4,5在第二行也能放下，则第二行放3,4,5
+ */
+function calculateOrderedGridLayout(elements, gap, targetAspectRatio = 1) {
+    if (elements.length === 0) {
+        return {
+            items: [],
+            boundingBox: new Box2(new Vector2(0, 0), new Vector2(0, 0)),
+        };
+    }
+    // 计算总面积
+    let totalArea = 0;
+    for (const el of elements) {
+        const size = el.box.getSize();
+        totalArea += (size.x + gap) * (size.y + gap);
+    }
+    // 估算目标行宽，使整体接近目标宽高比
+    // 总面积 ≈ 行宽 × 行高，目标：行宽 / 行高 ≈ targetAspectRatio
+    // => 行宽 ≈ sqrt(总面积 × targetAspectRatio)
+    const targetRowWidth = Math.sqrt(totalArea * targetAspectRatio);
+    const rows = [];
+    let currentRow = { elements: [], height: 0, y: 0 };
+    let currentRowWidth = 0;
+    for (const el of elements) {
+        const size = el.box.getSize();
+        const elementWidth = size.x + gap;
+        const elementHeight = size.y;
+        // 检查是否需要换行：当前行已有元素，且加上新元素会超过目标行宽
+        const shouldWrap = currentRow.elements.length > 0 &&
+            currentRowWidth + elementWidth > targetRowWidth + gap;
+        if (shouldWrap) {
+            // 保存当前行
+            rows.push(currentRow);
+            // 开始新行
+            currentRow = { elements: [], height: 0, y: 0 };
+            currentRowWidth = 0;
+        }
+        // 放置元素到当前行
+        currentRow.elements.push({ el, x: currentRowWidth });
+        currentRow.height = Math.max(currentRow.height, elementHeight);
+        currentRowWidth += elementWidth;
+    }
+    // 添加最后一行
+    if (currentRow.elements.length > 0) {
+        rows.push(currentRow);
+    }
+    // 计算每行的Y坐标
+    let currentY = 0;
+    for (const row of rows) {
+        row.y = currentY;
+        currentY += row.height + gap;
+    }
+    // 生成结果
+    const resultItems = [];
+    for (const row of rows) {
+        for (const item of row.elements) {
+            const size = item.el.box.getSize();
+            resultItems.push({
+                id: item.el.id,
+                position: [
+                    item.x + size.x / 2,
+                    row.y + size.y / 2,
+                ],
+            });
+        }
+    }
+    // 计算包围盒
+    let maxX = 0;
+    let maxY = 0;
+    for (const row of rows) {
+        if (row.elements.length === 0) {
+            continue;
+        }
+        const lastItem = row.elements[row.elements.length - 1];
+        if (!lastItem) {
+            continue;
+        }
+        const lastSize = lastItem.el.box.getSize();
+        const rowWidth = lastItem.x + lastSize.x;
+        maxX = Math.max(maxX, rowWidth);
+        maxY = Math.max(maxY, row.y + row.height);
+    }
+    const boundingBox = new Box2(new Vector2(0, 0), new Vector2(maxX, maxY));
+    return { items: resultItems, boundingBox };
+}
+/**
+ * @description 全局自适应排布
+ * 支持两种模式：
+ * 1. 'adaptive'（默认）: 基于元素包围盒自适应排布（MaxRects算法，更紧凑）
+ * 2. 'ordered': 基于元素顺序的流式行排布（保持输入顺序，每行尽可能多放元素）
+ *
+ * @param elements 元素列表（包含ID和包围盒）
+ * @param options 配置选项
+ * @returns 各元素位置和整体包围盒
+ */
+export function globalAutoLayout(elements, options = {}) {
+    const { gap = 10, targetAspectRatio = 1, mode = 'adaptive', } = options;
+    if (elements.length === 0) {
+        return {
+            items: [],
+            boundingBox: new Box2(new Vector2(0, 0), new Vector2(0, 0)),
+        };
+    }
+    if (mode === 'ordered') {
+        // 基于顺序的流式行排布
+        return calculateOrderedGridLayout(elements, gap, targetAspectRatio);
+    }
+    // 自适应模式：分析元素特征，获取宽高比倾向建议
+    const aspectHint = analyzeElements(elements);
+    // 调整目标宽高比：如果元素普遍高瘦，倾向于更宽的目标；反之亦然
+    const adjustedRatio = targetAspectRatio * (aspectHint > 1 ? 1.3 : aspectHint < 1 ? 0.7 : 1);
+    // 同时计算两种布局策略
+    const columnResult = calculateColumnLayout(elements, gap, adjustedRatio);
+    const rowResult = calculateRowLayout(elements, gap, adjustedRatio);
+    // 选择更接近正方形的方案（分数更高的）
+    const bestResult = columnResult.score >= rowResult.score ? columnResult : rowResult;
+    return {
+        items: bestResult.items,
+        boundingBox: bestResult.boundingBox,
+    };
+}
+/**
+ * @description 调整其他元素的行列信息
+ * 当被拖拽元素移动到新位置时，需要调整其他受影响的元素：
+ * 1. 同行内移动：原位置到新位置之间的元素需要相应调整列号
+ * 2. 跨行移动：原行中后面的元素前移，目标行中后面的元素后移
+ * @param parent 父画板
+ * @param draggedItemId 被拖拽的元素ID
+ * @param fromRow 原始行号
+ * @param fromColumn 原始列号
+ * @param toRow 目标行号
+ * @param toColumn 目标列号
+ */
+export function adjustOtherElementsLayoutInfo(parent, draggedItemId, fromRow, fromColumn, toRow, toColumn, getSDKItem) {
+    // 如果没有变化，不需要调整
+    if (fromRow === toRow && fromColumn === toColumn) {
+        return;
+    }
+    const layoutInfos = JSON.parse(JSON.stringify(parent.property.layoutInfos ?? {}));
+    if (fromRow === toRow) {
+        // ===== 情况1：同行内移动 =====
+        // 移动中间元素
+        for (const [id, info] of Object.entries(layoutInfos)) {
+            if (id === draggedItemId) {
+                continue;
+            }
+            if (info.row !== fromRow) {
+                continue;
+            }
+            if (fromColumn < toColumn) {
+                // 向前移动（如从列1移到列3）：between(1, 3)的元素列号-1
+                if (info.column > fromColumn && info.column <= toColumn) {
+                    info.column--;
+                }
+            }
+            else if (fromColumn > toColumn) {
+                // 向后移动（如从列3移到列1）：between(1, 3)的元素列号+1
+                if (info.column >= toColumn && info.column < fromColumn) {
+                    info.column++;
+                }
+            }
+        }
+    }
+    else {
+        // ===== 情况2：跨行移动 =====
+        // 2.1 原行：原列之后的元素前移（列号-1）
+        for (const [id, info] of Object.entries(layoutInfos)) {
+            if (id === draggedItemId) {
+                continue;
+            }
+            if (info.row === fromRow && info.column > fromColumn) {
+                info.column--;
+            }
+        }
+        // 2.2 目标行：目标列及之后的元素后移（列号+1）
+        // 按列号从大到小排序，避免前面元素后移影响后面元素的判断
+        const targetRowItems = Object.entries(layoutInfos)
+            .filter(([id, info]) => id !== draggedItemId && info.row === toRow && info.column >= toColumn)
+            .sort((a, b) => b[1].column - a[1].column);
+        for (const [, info] of targetRowItems) {
+            info.column++;
+        }
+    }
+    parent.property.layoutInfos = layoutInfos;
+}