75 lines
3.9 KiB
Markdown
75 lines
3.9 KiB
Markdown
# PPT Frame 素材插入经验
|
||
|
||
更新日期：2026-04-27
|
||
|
||
## 背景
|
||
|
||
用户在画布中选中 PPT 页面（底层为 `Frame`）后，从素材库或生成结果插入图片/视频，预期素材进入当前 PPT 页面并自适应页面尺寸。旧逻辑只把素材插入到选中元素下方，导致素材落在页面外，需要用户手动拖入和执行「素材自适应PPT」。
|
||
|
||
## 经验
|
||
|
||
### 1. 先复用 Frame 内部插入能力
|
||
|
||
`insertMediaIntoFrame` 已经覆盖 Frame 查找、contain/stretch 适配、居中放置和 `frameId` 绑定。新需求不要再在素材库、任务队列、AI 预览等入口各写一套几何逻辑，只在通用插入链路前置识别「单选 Frame」即可。
|
||
|
||
### 2. 单选 Frame 才改变插入语义
|
||
|
||
只有当前 selection 或 `appState.lastSelectedElementIds` 是单个 Frame 时，才插入到 Frame 内。多选、选中普通元素、拖拽指定坐标、显式传入 `startPoint/referenceDimensions` 时，应继续沿用原插入位置，避免破坏批量排列和拖拽语义。
|
||
|
||
### 3. PPT 自适应要用 contain，不要默认拉伸
|
||
|
||
插入到 PPT 页面内的图片/视频应保持媒体比例并居中适配 Frame。只有明确传 `{ fit: 'stretch' }` 时才铺满页面，避免素材变形。视频没有真实尺寸时可用 16:9 兜底，但如果上层已传媒体尺寸，必须尊重该尺寸计算适配。
|
||
|
||
### 4. 插入后必须绑定 `frameId`
|
||
|
||
PPT 导出、Frame 移动、预览缩略图和「素材自适应PPT」都依赖 `frameId` 或几何相交关系。插入时直接绑定 `frameId`，比后续靠最大相交面积补救更稳定。
|
||
|
||
### 5. 底层修复优先于入口补丁
|
||
|
||
素材插入入口很多：素材库、任务队列、AI 预览、MCP/工作流、快捷工具栏。修在 `insertImageFromUrl`、`insertVideoFromUrl` 和 `executeCanvasInsertion` 这类公共层，能覆盖更多路径，也减少后续漏改风险。
|
||
|
||
## 实现要点
|
||
|
||
- 新增 `getSelectedInsertionFrame`：优先读当前 selection，selection 为空时回退 `lastSelectedElementIds`。
|
||
- 新增 `insertMediaIntoSelectedFrame`：把选中 Frame 的 `points` 转为目标尺寸，再调用 `insertMediaIntoFrame`。
|
||
- 图片/视频通用插入函数在没有显式坐标和尺寸时，先尝试插入选中 Frame。
|
||
- `executeCanvasInsertion` 对单个图片/视频内容做同样前置处理，覆盖 `quickInsert`、任务队列和 AI 预览。
|
||
- 视频插入新增 `lockReferenceDimensions`，避免 Frame 适配后的尺寸再次被默认 16:9 逻辑改写。
|
||
|
||
## 注意事项
|
||
|
||
- 不要为了「当前 PPT」新增实体或全局状态；当前画布 selection 已经足够表达目标 Frame。
|
||
- 不要在插入前完整下载视频元数据；高并发文件处理场景下应保持轻量，必要时使用传入尺寸或默认比例。
|
||
- 不要让 `startPoint` 场景自动吸附 Frame；拖拽和批量排版需要尊重调用方坐标。
|
||
- 不要只改素材库按钮；生成结果、工作流和预览器也会走插入链路。
|
||
|
||
## 验证建议
|
||
|
||
1. 指定文件测试：
|
||
|
||
```bash
|
||
pnpm --dir packages/drawnix exec vitest run src/utils/__tests__/frame-insertion-utils.test.ts src/utils/__tests__/ppt-media-fit.test.ts
|
||
```
|
||
|
||
2. 类型检查：
|
||
|
||
```bash
|
||
pnpm nx run drawnix:typecheck
|
||
```
|
||
|
||
3. 注意测试命令：
|
||
|
||
```bash
|
||
pnpm --filter @aitu/drawnix test -- frame-insertion-utils.test.ts
|
||
```
|
||
|
||
该写法会被当前包脚本吞成更大范围测试，可能暴露仓库既有 unrelated 失败。需要精确验证单文件时，优先使用 `pnpm --dir packages/drawnix exec vitest run ...`。
|
||
|
||
## 检查清单
|
||
|
||
- 单选 PPT 页面后插入图片，图片出现在页面内部并保持比例。
|
||
- 单选 PPT 页面后插入视频，视频出现在页面内部并保持比例。
|
||
- 插入后的媒体元素带有目标页面 `frameId`。
|
||
- 未选中 Frame 时，素材仍插入到原来的默认位置。
|
||
- 传入显式 `startPoint` 的批量插入不被 Frame 逻辑劫持。
|