# 批量插入画布流式布局经验总结

更新日期：2026-05-25

## 背景

批量插入最初是按纵向顺序堆叠，宽屏桌面下会浪费大量横向空间。后来改成视口流式排布后，又遇到一个更隐蔽的问题：图片在插入后仍会按原始比例回写尺寸，导致同一批内容的间距忽大忽小。

## 相关文档

- **2026-05-25 重要更新**：[批量插入图片叠加问题修复经验总结](./CANVAS_BATCH_INSERTION_FIX_LESSONS.md)
  - 详细记录了素材库批量插入图片叠加问题的完整修复过程
  - 包括问题根源分析、正确的解决方案、风险评估
  - 新增 `calculateImageDisplayDimensions` 统一尺寸计算函数

## 架构变更

### 1. 布局层抽成共享流式布局器

批量插入不再由服务层、MCP 层、自动入画布各自维护 `currentX/currentY`，而是统一走共享布局器。

- 先读取画布容器宽度和 `zoom`
- 按插入顺序横向排布
- 超过当前行宽后换行
- 每行高度由当行最高元素决定

这让“怎么算点位”只剩一处实现。

### 2. 尺寸层改成“批量固定参考尺寸”

图片和视频批量插入时，不再允许加载完成后按原始比例悄悄改写最终尺寸。

- 批量路径统一传入参考尺寸
- 图片插入显式开启 `lockReferenceDimensions`
- `skipImageLoad` 继续保留，保证批量插入是流式的

这样布局阶段和渲染阶段看到的是同一套尺寸，间距就会稳定。

### 3. 插入入口统一收敛

服务层、MCP、自动入画布都复用同一个批量执行入口，而不是各自拼自己的插入循环。

好处是：

- 行为一致
- 日志一致
- 修复一次能覆盖多条路径

### 4. 滚动目标改为整批中心

批量完成后，滚动不再盯第一项，而是对准整批内容包围盒中心。这样宽屏和窄屏都更容易看到整批结果。

## 经验

### 1. 不要把“预估尺寸”当成“最终尺寸”

只要插入后还可能回写尺寸，后面的布局游标就一定会漂。

### 2. 批量链路只保留一个布局源

多个入口各自维护排布逻辑，最后一定会分叉。共享布局器比“各处抄一份”更省心，也更容易加日志定位。

### 3. `groupId` 只负责相邻语义，不负责硬性竖排

同组内容可以相邻，但不再强制单独竖排。空间不足时自然换行，比手工维护特殊分支更稳。

### 4. 调试要能看见“点位”和“最终尺寸”

批量插入日志最好同时包含：

- 解析出的视口宽度
- `zoom`
- 每项的估算尺寸
- 每项的实际插入点
- 批次 bounds 和 center

只看“开始/结束”日志，很难抓到漂移来源。

## 回归检查清单

- 宽屏下是否先横排再换行
- `zoom` 变化时换行点是否正确
- 图片批量插入后间距是否稳定
- 服务层、MCP 层、自动入画布是否共用同一套布局
- 批量结束后的滚动中心是否覆盖整批内容
- 只改批量路径，单项插入是否保持原有行为