# PPT 素材完整展示经验总结

更新日期：2026-04-26

## 背景

PPT 场景里，页面主图本质上仍是画布图片元素。素材库图片替换、AI 回填、历史图切换和“素材自适应 PPT”如果把图片元素强制改成 PPT Frame 的 16:9 尺寸，再让 `<img>` 按 `width: 100%` 渲染，竖图会按宽度放大，底部被裁掉。

这类问题不能只在某一个入口修，要统一“插入尺寸计算”和“渲染兜底”两层逻辑。

## 经验原则

1. PPT 图片默认应完整展示，而不是铺满裁切。
   - 素材库替换 PPT 主图时使用 contain。
   - 历史图片切换和 AI 图片回填也要走 contain。
   - 只有明确需要铺满背景时，才显式使用 stretch。

2. 不要把请求尺寸当成图片真实尺寸。
   - `1024x1024`、`16x9` 这类生成参数不是自然宽高。
   - 图片真实比例未知时，应先加载图片尺寸，再按 Frame 计算最大可见矩形。
   - 竖图适配 16:9 Frame 时，应按高度缩放并水平居中。

3. 旧数据需要渲染兜底。
   - 历史数据里可能已经有 16:9 图片元素框包着竖图 URL。
   - Frame 内图片渲染应使用 `object-fit: contain`，避免旧元素继续下裁。

4. “素材自适应 PPT”应优先读自然宽高。
   - 如果元素框已经被拉成 16:9，再按元素框比例计算会复现错误。
   - 工具栏自适应动作应先尝试读取图片自然宽高，失败时再退回元素尺寸。

5. 尺寸修复不要引入大对象存储。
   - 只保存 URL、轻量元数据和元素点位。
   - 不把 base64 图片或二进制写进 PPT 元数据，避免画布存储和内存压力。

## 代码层面固化的规则

### 1. `insertMediaIntoFrame` 默认 contain

Frame 内插入媒体时，默认计算最大完整展示矩形：

- 图片更宽：按 Frame 宽度缩放，高度居中。
- 图片更高：按 Frame 高度缩放，宽度居中。
- 未知图片尺寸：先加载图片，再根据真实宽高重算居中点位。

`fit: 'stretch'` 只作为显式选项保留。

### 2. PPT 主图替换不传 Frame 尺寸作为图片尺寸

素材库替换、历史图切换和 AI 回填时，不应把 Frame 的 `1920x1080` 当作 `mediaDimensions` 传入。

正确做法是让插入工具自己加载真实尺寸并 contain，随后再调用 `replacePPTSlideImage` 更新主图元数据并删除旧主图。

### 3. Frame 图片渲染兜底 contain

Frame 内普通图片元素渲染时，应给图片节点设置：

```css
width: 100%;
height: 100%;
object-fit: contain;
```

音频卡片和视频元素不走这个兜底，避免破坏已有播放器展示。

### 4. 自适应工具使用自然比例

“素材自适应 PPT”应按如下优先级获取比例：

1. 图片自然宽高。
2. 元素 `width` / `height` 元数据。
3. 当前元素框点位尺寸。

这样能修复旧的 16:9 框 + 竖图 URL 数据。

## 检查清单

- 素材库图片替换：竖图完整显示，水平居中，不覆盖旧主图。
- PPT 历史图切换：竖图完整显示，并正确更新当前主图。
- AI PPT 图片回填：不再强制 stretch 到 16:9。
- 素材自适应 PPT：旧 16:9 框中的竖图能按自然高度重新适配。
- 视频、音频插入：仍保持原有插入行为。
- 性能约束：不引入 base64 大字段，不把批量图片读入内存。

## 验证建议

```bash
pnpm --dir packages/drawnix exec vitest run src/utils/__tests__/ppt-media-fit.test.ts
pnpm nx typecheck drawnix
git diff --check
```

## 提交备注模板

```text
问题描述:
- PPT 场景中图片替换和素材自适应会按宽度或 16:9 元素框缩放，竖图底部被裁切。

修复思路:
- PPT 主图替换、历史切换和 AI 回填统一走 contain。
- 图片真实尺寸未知时先加载自然宽高，再居中适配 Frame。
- Frame 内图片渲染增加 object-fit: contain 兜底。

更新代码架构:
- insertMediaIntoFrame 默认 contain，仅显式 stretch 时铺满。
- 素材自适应 PPT 新增自然宽高读取链路和回归测试。
```