107 lines
4.0 KiB
Markdown
107 lines
4.0 KiB
Markdown
# 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 新增自然宽高读取链路和回归测试。
|
||
```
|