PPT 素材完整展示经验总结

更新日期：2026-04-26

背景

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

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

经验原则

PPT 图片默认应完整展示，而不是铺满裁切。
- 素材库替换 PPT 主图时使用 contain。
- 历史图片切换和 AI 图片回填也要走 contain。
- 只有明确需要铺满背景时，才显式使用 stretch。
不要把请求尺寸当成图片真实尺寸。
- 1024x1024、16x9 这类生成参数不是自然宽高。
- 图片真实比例未知时，应先加载图片尺寸，再按 Frame 计算最大可见矩形。
- 竖图适配 16:9 Frame 时，应按高度缩放并水平居中。
旧数据需要渲染兜底。
- 历史数据里可能已经有 16:9 图片元素框包着竖图 URL。
- Frame 内图片渲染应使用 object-fit: contain，避免旧元素继续下裁。
“素材自适应 PPT”应优先读自然宽高。
- 如果元素框已经被拉成 16:9，再按元素框比例计算会复现错误。
- 工具栏自适应动作应先尝试读取图片自然宽高，失败时再退回元素尺寸。
尺寸修复不要引入大对象存储。
- 只保存 URL、轻量元数据和元素点位。
- 不把 base64 图片或二进制写进 PPT 元数据，避免画布存储和内存压力。

代码层面固化的规则

1. `insertMediaIntoFrame` 默认 contain

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

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

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

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

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

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

3. Frame 图片渲染兜底 contain

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

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

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

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

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

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

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

检查清单

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

验证建议

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

提交备注模板

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

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

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

4.0 KiB Raw Blame History Unescape Escape