项目地址：https://github.com/chenyuwebwawa/html2pptx
本文以辰语AI中的 AI PPT 产品的真实实现为样本，系统说明「如何把一页页 HTML 幻灯片，转化成一个文字可二次编辑的 .pptx 文件」。配套开源实现见仓库根目录的src/html2pptx.js与index.html演示。
1. 问题定义
在 AI 生成 PPT 的场景里，理想的「源格式」是 HTML：
- 设计师/模型可以用熟悉的 HTML/CSS 表达任意版式、渐变、形状、SVG、CSS 动画；
- 浏览器天然是最高保真的渲染器，所见即所得；
- 同一份 HTML 既能驱动在线预览（
<iframe srcdoc="">），又能作为导出真源。
但交付物往往必须是 PowerPoint（.pptx）：
- 客户要在 PowerPoint / WPS 里继续改字、改色、换图；
- 要能被检索、被投影、被合规审查。
矛盾点在于：HTML 是流式、像素级的；PPTX 是矢量、对象级的。
直接把一页 HTML 整页截图塞进 PPTX，文字就变成了一张不可编辑的图片——这不是用户想要的交付物。
于是核心命题变成：
怎样从「一页 HTML」构造一个 .pptx，使得背景/图形/图片高度保真，而文字又是 PowerPoint 里可读写的原生文本框？
2. 总体架构：前后端分工
该方案刻意把「生成 HTML」与「导出 PPTX」拆成两个阶段、两套环境。
关键认知：后端从不接触 PPTX。它只负责产出「干净、可被前端栅格化的 HTML」，并把这份 HTML 作为 slides 持久化进数据库。
所有 PPTX 构造都发生在用户浏览器里。这样做有三个好处：
- 服务端零渲染依赖：不需要在 PHP 环境装 headless Chrome / 无头浏览器，省去巨大的运维与性能成本；
- 导出与渲染解耦：改导出策略（比如换字号映射、加备注）只动前端，不动生成链路；
- 合规前置：后端
sanitize+ 模型约束，从源头消灭会让前端导出崩坏的写法（见 §6）。
3. 导出核心：混合模式（Hybrid Mode）
前端导出走的是「背景图 + 可编辑文字层」的混合叠加，而非整页截图。
对每一页幻灯片：
- 用同源
<iframe srcdoc>承载完整 slide HTML，离屏渲染（固定在画布坐标 1280×720）； 用 html2canvas 截图，但只截「背景」：通过
onclone钩子把克隆 DOM 里所有文本color设为transparent，于是截出来的 PNG 只包含形状、渐变、图片、图标——文字被「抠掉」；
- 同时用 DOM 度量抽取「文字」：遍历真实 DOM，拿到每个文字块的坐标、字号、颜色、字重、对齐、行高、行数；
- 在 PPTX 里：先
addImage铺满整页背景，再对每个文字块addText叠加一个原生文本框。
结果：视觉上 = 一张完整幻灯片；对象上 = 一张背景图 + 一堆可编辑文本框。
用户在 PowerPoint 里双击任意标题即可改字，而图形/配色仍由背景图保真承载。
4. 坐标与度量的还原（最容易翻车的地方）
PPTX 用「英寸」做画布单位（本方案 13.33×7.5in，标准 16:9），而 HTML 用「像素」（1280×720）。
转换很简单，但坑在细节：
画布缩放
SX = 13.33 / 1280 = 0.010414 in/pxSY = 7.5 / 720 = 0.010417 in/px文本框 x = px.x SX, y = px.y SY
字号换算
pt = px 72 / 96 = px 0.75而 72 SX = 72 0.010414 = 0.75 → 与上面一致所以 fontSize(pt) = round(px.fs 72 SX)
Border/Padding 补偿
getBoundingClientRect() 返回的是 border box；PowerPoint 的文本框定位的是 内容盒左上角。
如果不扣掉 border 与 padding，文字会整体向上、向左漂移——这是「错位」的头号成因。
实现里对每个文字块都扣除 border + padding 四边，把坐标收敛到内容盒。
行高与行数
行高倍数
lh = parseFloat(lineHeight) / fontSize，传给 PptxGenJS 的lineSpacingMultiple，让多行文字的竖排节奏和浏览器一致，避免「多行竖向漂移」；
行数用
Range.getClientRects()按行盒计数：单行文本在 PPTX 里关闭自动换行（wrap:false），因为不同字体在 PowerPoint 的度量与浏览器略有差异，开着自动换行会把本应单行的内容硬折成两行，导致溢出/错位。
真实背景色兜底
幻灯片根元素的 background-color 会被提取为 base 颜色，作为 PPTX 的 slide.background。
即使背景图因画布污染而缺失，透明缝隙也会显示真实底色而非惨白——这是降级体验的关键。
5. 字体与颜色的兼容性
字体映射（pptxMapFont）
背景图是 html2canvas 在本机栅格化的，用的是本机实际解析到的字体；文字层是 PowerPoint 后续用字体名渲染的。
若两份字体度量不同，文字就会相对背景图跑位。因此文字层必须按用户本机平台映射字体名：
- macOS：
PingFang SC - Windows：
Microsoft YaHei - 含 Arial/Helvetica →
Arial，含 黑体/宋体 → 对应中文字体
这样「背景图用的字体」与「PPTX 文字层声明的字体」在用户机器上是同一个，度量对齐。
颜色规范化（cssColorToHex）
PptxGenJS 只认 RRGGBB。实现把 rgb()/rgba()/#hex 统一转成 6 位大写十六进制；
rgba 的 alpha 被丢弃（PPTX 文本框不支持逐字透明度，由背景图承担层次）。
图标与渐变文字的特殊处理
图标（class 含
ri-/icon/material-icons…）不是文字，不抽；截图时onclone会把它和文字一起变透明，所以要提前记录每个图标的真实
color，在克隆里还原，否则图标会消失；渐变文字（
-webkit-text-fill-color:transparent+background-clip:text）字形已留在背景图里，若再叠加可编辑文字层会双重显示，因此这类元素不抽取，只保留背景图上的字形。
6. 后端为何要「清洗 + 约束」：导出可行性的前置条件
前端导出能否成功，很大程度取决于后端产出的 HTML 干不干净。这就是为什么 ai-ppt-api.php 做了两件事：
(1) sanitize_slide_html() 安全/兼容清洗
剥离 <script>、<iframe>、<link>、@import、@font-face、内联事件、javascript:、
以及外部 http(s) 图片。原因：
<script>/动画在导出时已被capture()阶段强制冻结到终态，没必要保留，且可能污染；
- 外部 webfont /
@import会让document.fonts.ready与 html2canvas 永远等待外部 CDN，直接卡到超时； - 外部 http 图片没有 CORS 头，html2canvas 截图后
toDataURL会因画布污染抛错。
(2) prompt 约束模型禁用危险 CSS
系统提示词明确禁止以下写法（它们 html2canvas 渲染不了，会导致该区域空白/变色）：
conic-gradient（只用linear/radial-gradient）；mix-blend-mode/background-blend-mode；filter: blur()/drop-shadow()（发光改用radial-gradient或box-shadow）；oklch()/color-mix()/lab()等非 hex/rgb 颜色（一律用#RRGGBB或rgb()）；- 外部 http(s) 图片（只允许本地同源图片，避免画布污染）。
结论：导出质量 = 前端混合算法 × 后端内容治理。两者缺一，都会退化成「文字错位的图片堆」。
7. 降级链（Defensive Pipeline）
真实环境充满意外，导出链路设计了多层兜底，保证「至少有一个能看的版本」：
- 库加载失败：PptxGenJS / html2canvas 先从本地主源加载，失败再回退 CDN（jsdelivr → unpkg）；
- html2canvas 未加载：退化为「纯文字层」——只有可编辑文本框、无背景图，但文字仍可编辑；
- 截图超时（单次 6s 看门狗）：判定失败，进入重试；
- 画布污染（toDataURL 抛错）：隐藏所有跨域
<img>与外部background-image后重试一次，保住形状/渐变/本地图； - 整页截图超时（15s）：退化为纯文字层，用真实背景色承托，绝不让整页空白；
- 动画卡在初态：
capture()在截图前把带animation/transition的元素强制落回可见终态（opacity:1, transform:none），避免截到opacity:0的空白或半途位移的残影。
8. 取舍与边界
维度本方案（混合模式）纯截图服务端无头浏览器转 OOXML文字可编辑✅ 原生文本框❌ 图片✅ 但需后端解析 DOM图形/渐变保真✅ 背景图承载✅✅服务端成本无（浏览器端）无高（headless Chrome）动画冻结终态（合理）冻结终态冻结终态复杂 CSS 容错依赖清洗/约束同左同左跨域图片需同源/转 dataURL同左同左
已知边界：
- 渐变文字、SVG 内文字不可二次编辑（留在背景图）；
- 不同字体在 PowerPoint 与浏览器的细微度量差，仍需
margin:0+ 单行关自动换行来抑制； - 背景图是位图，极度放大不如纯矢量清晰——这是「保真 vs 可编辑」的固有权衡。
9. 小结
这套方案的本质，是承认一个事实：HTML 与 PPTX 是两种范式，没有「无损直转」。
它用「前端混合导出」在两者之间取了一个工程上最优的折中——
- 后端负责把内容治理成「可被栅格化、可被度量」的干净 HTML；
- 前端用「背景图 + 可编辑文字层」把这份 HTML 重建成一个用户拿去就能改的 PPTX。
其价值不在某个神奇算法，而在对坐标/字体/颜色度量差异的逐项补偿，以及对失败路径的系统性降级。
这也正是 src/html2pptx.js 提炼出来、可被任意「HTML 幻灯片 → PPTX」需求复用的核心。
