html2pptx

把「整页 HTML 幻灯片」导出为 文字可二次编辑 的 .pptx。

• 混合模式：背景（形状/渐变/图片/图标）用 html2canvas 栅格化成整页 PNG，文字用 DOM 度量抽取为 PowerPoint 原生可编辑文本框叠加其上。
• 纯前端、零服务端渲染依赖；依赖 PptxGenJS + html2canvas（自动加载，带 CDN 回退）。
• 提炼 辰语AI 的 AI PPT 产品，原理见 docs/principle.md。

🌐 双语文档：本文档提供中英双语文档—— 在线阅读器）：docs/index.html； en：README.en.md 与 docs/principle.en.md。

---

效果

输入	输出
每页一个 1280×720 的完整 HTML 文档	一个 .pptx，背景保真、文字可改

---

快速开始

# 1. 克隆
git clone https://github.com/<your-name>/html2pptx.git
cd html2pptx

# 2. 直接用浏览器打开演示页（需联网加载 PptxGenJS/html2canvas）
#    推荐起一个本地静态服务器避免 file:// 限制：
python3 -m http.server 8080
# 打开 http://localhost:8080/  →  点「导出 PPTX」

演示页 index.html 内置 3 页示例幻灯片，点按钮即可下载 html2pptx-demo.pptx。

---

在你的项目里使用

只需引入 src/html2pptx.js：

<script src="./src/html2pptx.js"></script>
<script>
  const slides = [
    `<!DOCTYPE html><html><head><meta charset="UTF-8"><style>
      html,body{margin:0;width:1280px;height:720px;overflow:hidden;font-family:-apple-system,"PingFang SC","Microsoft YaHei",sans-serif}
      .p{width:1280px;height:720px;display:flex;align-items:center;justify-content:center;background:#16213e;color:#fff}
      h1{font-size:60px}
    </style></head><body><div class="p"><h1>Hello PPTX</h1></div></body></html>`,
    // ... 更多页
  ];

  HTML2PPTX.export({
    slides,
    fileName: 'my-deck.pptx',
    title: 'My Deck',
    onProgress: (cur, total, phase) => console.log(phase, cur, '/', total)
  }).then(f => console.log('已下载', f));
</script>

---

API

HTML2PPTX.export(opts) → Promise<fileName>

参数	类型	默认	说明
slides	Array<string | {html, notes}>	必填	每页一个完整 HTML 文档；可带 notes 作为演讲备注
fileName	string	'export.pptx'	下载文件名（自动补 .pptx）
title	string	'HTML to PPTX'	PPTX 文档标题
author	string	'html2pptx'	作者
width / height	number	13.33 / 7.5	画布尺寸（英寸，16:9）
canvasW / canvasH	number	1280 / 720	幻灯片画布像素，需与 HTML 内 html,body 尺寸一致
backgroundColor	string	'FFFFFF'	无背景图时的兜底底色
scale	number	1.5	截图倍率（越高越清晰、越慢）
pptxUrl / h2cUrl	string	''	本地主源路径，优先于 CDN（国内部署强烈建议指向本地副本）
pptxCdns / h2cCdns	string[]	jsdelivr→unpkg	CDN 回退列表
onProgress	(cur, total, phase) => void	—	进度回调

---

幻灯片 HTML 的编写约束（非常重要）

导出质量直接取决于 HTML 是否「干净」。请遵循：

1. 每页必须是完整 HTML 文档，根容器尺寸 = canvasW × canvasH（默认 1280×720），内容不得溢出；
2. 禁止 <script>、<iframe>、外部 <link>、外部 CDN、内联事件；
3. 图片只用本地同源地址（或 dataURL）；外部 http(s) 图片会因画布污染导致背景丢失；
4. 禁用以下 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()（只用 #RRGGBB 或 rgb()）
5. 字体栈建议 -apple-system,"PingFang SC","Microsoft YaHei",sans-serif，导出会自动按平台映射到 PowerPoint 字体。

若后端用 AI 生成这些 HTML，务必像 ai-ppt-api.php 那样：① sanitize_slide_html() 清洗； ② prompt 约束模型遵守上面规则。详见 docs/principle.md §6。

---

已知边界

• 渐变文字（background-clip:text）、SVG 内 <text> 不可二次编辑（留在背景图）；
• 背景图是位图，极度放大不如纯矢量清晰（保真 vs 可编辑的固有权衡）；
• 不同字体在 PowerPoint 与浏览器的细微度量差，已用 margin:0 + 单行关自动换行抑制，极端字体仍可能轻微错位。

---

目录结构

html2pptx/
├── src/html2pptx.js        # 核心导出引擎（UMD，零构建）
├── index.html              # 演示页（含示例幻灯片）
├── docs/principle.md       # 原理文章（中文，专业向）
├── docs/principle.en.md    # 原理文章（英文）
├── docs/index.html         # 双语文档在线阅读器（中/EN 切换，标题「辰语」居中）
├── vendor/                 # 放本地 pptxgen.bundle.js / html2canvas.min.js（可选，国内部署用）
├── package.json
├── README.md               # 中文
└── README.en.md            # 英文

---

License

MIT