` 在 PPTX 里没有对应的文本容器。 **也不能用 `` 承载主文字**——span 是行内元素，没法独立对齐成文本框。span 只能**夹在 p/h\* 里**做局部样式（加粗、换色）。 ### 规则 2：不支持 CSS 渐变 — 只能用纯色 ```css /* ❌ 错误 */ background: linear-gradient(to right, #FF6B6B, #4ECDC4); /* ✅ 正确：纯色 */ background: #FF6B6B; /* ✅ 如果必须多色条纹，用 flex 子元素各自纯色 */ .stripe-bar { display: flex; } .stripe-bar div { flex: 1; } .red { background: #FF6B6B; } .teal { background: #4ECDC4; } ``` **为什么**：PowerPoint 的 shape fill 只支持 solid/gradient-fill 两种，但 pptxgenjs 的 `fill: { color: ... }` 只映射 solid。渐变走 PowerPoint 原生 gradient 需要另写结构，目前工具链不支持。 ### 规则 3：背景/边框/阴影只能在 DIV 上，不能在文字标签上 ```html

重点内容

``` **为什么**：PowerPoint 里 shape（方块/圆角矩形）和 text frame 是两个对象。HTML 的 `

` 只翻译成 text frame，背景/边框/阴影属于 shape——必须在**包裹 text 的 div** 上写。 ### 规则 4：DIV 不能用 `background-image` — 用 `` 标签 ```html

``` **为什么**：`html2pptx.js` 只从 `` 元素提取图片路径，不解析 CSS 的 `background-image` URL。 --- ## Path A HTML 模板骨架每张 slide 一个独立 HTML 文件，彼此作用域隔离（避开单文件 deck 的 CSS 污染）。 ```html

标题用断言句，不是主题词

副标题补充说明

要点一

简短说明文字

第一条要点
第二条要点
第三条要点

``` --- ## 常见错误速查 | 错误信息 | 原因 | 修复方法 | |---------|------|---------| | `DIV element contains unwrapped text "XXX"` | div 里有裸文字 | 把文字包进 `

` 或 `

`-`

` | | `CSS gradients are not supported` | 用了 linear/radial-gradient | 改为纯色，或用 flex 子元素分段 | | `Text element
has background` | `
` 标签加了背景色 | 外套 `
` 承载背景，`
` 只写文字 | | `Background images on DIV elements are not supported` | div 用了 background-image | 改为 `` 标签 | | `HTML content overflows body by Xpt vertically` | 内容超出 540pt | 减少内容或缩小字号，或 `overflow: hidden` 截断 | | `HTML dimensions don't match presentation layout` | body 尺寸和 pres layout 对不上 | body 用 `960pt × 540pt` 配 `LAYOUT_WIDE`；或 defineLayout 自定义尺寸 | | `Text box "XXX" ends too close to bottom edge` | 大字号 `
` 距离 body 底边 < 0.5 inch | 往上挪，留足下边距；PPT 底部本身就会被遮住一部分 | --- ## 基本工作流（3 步出 PPTX） ### Step 1：按约束写每页独立 HTML ``` 我的Deck/ ├── slides/ │ ├── 01-cover.html # 每个文件都是完整 960×540pt HTML │ ├── 02-agenda.html │ └── ... └── illustration/ # 所有引用的图片 ├── chart1.png └── ... ``` ### Step 2：写 build.js 调用 `html2pptx.js` ```js const pptxgen = require('pptxgenjs'); const html2pptx = require('../scripts/html2pptx.js'); // 本 skill 脚本 (async () => { const pres = new pptxgen(); pres.layout = 'LAYOUT_WIDE'; // 13.333 × 7.5 inch，匹配 HTML 的 960×540pt const slides = ['01-cover.html', '02-agenda.html', '03-content.html']; for (const file of slides) { await html2pptx(`./slides/${file}`, pres); } await pres.writeFile({ fileName: 'deck.pptx' }); })(); ``` ### Step 3：打开检查 - PowerPoint/Keynote 打开导出 PPTX - 双击任意文字应能直接编辑（如果是图片说明第 1 条违反了） - 验证 overflow：每页应该在 body 范围内，没有被截 --- ## 这条路径 vs 其他选项（什么时候选什么） | 需求 | 选什么 | |------|------| | 同事会改 PPTX 里的文字 / 发给非技术人员继续编辑 | 本文路径（editable，需从头按 4 条约束写 HTML） | | 只是演讲用 / 发存档，不再改 | `export_deck_pdf.mjs`（多文件）或 `export_deck_stage_pdf.mjs`（单文件 deck-stage），出矢量 PDF | | 视觉自由度优先（动画、web component、CSS 渐变、复杂 SVG），接受不可编辑 | `export_deck_pptx.mjs --mode image`（图片铺底 PPTX） | 绝不要在视觉自由写好的 HTML 上硬跑 html2pptx——实测视觉驱动的 HTML pass 率 < 30%，剩下的逐页改造比重写还慢。 --- ## 为什么 4 条约束不是 Bug 而是物理约束这 4 条不是 `html2pptx.js` 作者偷懒——它们是 PowerPoint 文件格式（OOXML）本身的约束投射到 HTML 上的结果： - PPTX 里文字必须在 text frame（``），对应段落级 HTML 元素 - PPTX 的 shape 和 text frame 是两个对象，无法在同一 element 上同时画背景和写文字 - PPTX 的 shape fill 对 gradient 支持有限（仅某些 preset gradients，不支持 CSS 任意角度渐变） - PPTX 的 picture 对象必须引用真实图片文件，不是 CSS 属性理解这点后，不要期待工具变聪明 —— 是 HTML 写法要适配 PPTX 格式，不是反过来。

`-`

Q3营收增长23%

标题用断言句，不是主题词

要点一

`-`