powerpoint

Powerpoint 技能

使用 python-pptx 库创建、检查和编辑 PowerPoint（.pptx）演示文稿。五个辅助脚本涵盖根据 JSON 规范创建演示文稿、结构化读取内容、就地编辑、基于模板创建品牌演示文稿，以及渲染幻灯片——整个过程均可离线进行，无需安装 PowerPoint。

适用场景

• 用户要求制作幻灯片、报告演示文稿或推介演示文稿。
• 需要从他人分享的 .pptx 中提取文本、备注、表格、图表数据或图片。
• 需要更新现有演示文稿：替换文本、刷新或修补图表数据、更换徽标、复制／删除／重新排序幻灯片、设置背景、页脚、超链接或演讲者备注。
• 必须使用公司的 .pptx 模板制作符合品牌风格的演示文稿。
• 请勿用于 .ppt（旧版二进制）文件——如果有 LibreOffice，请先使用 soffice --convert-to pptx old.ppt 转换。

前提条件

• 安装了 python-pptx 的 Python 3.10+ （pip install python-pptx）。
• 可选：LibreOffice（soffice）和 poppler（pdftoppm 或 pdftocairo），用于将幻灯片渲染为 PNG 以及导出 PDF。 pptx_render.py 会使用 shutil.which 检测这两者；如果缺少依赖，则会正常降级 （报告 {"rendered": false, "missing": [...]}，退出码为 0）——所有创建／读取／编辑操作均可在没有这些依赖的情况下运行。
• 通过 terminal 检查是否可用： python -c "import pptx; print(pptx.__version__)" 和 which soffice pdftoppm。

运行方法

所有脚本都位于 scripts/ 中，支持 --help，会将 JSON 打印到 stdout，失败时返回非零退出码。使用 terminal 运行：

python scripts/pptx_create.py deck.json out.pptx
python scripts/pptx_read.py deck.pptx --outline      # full JSON outline
python scripts/pptx_read.py deck.pptx --notes        # speaker notes
python scripts/pptx_read.py deck.pptx --images ./img # export pictures
python scripts/pptx_edit.py deck.pptx --replace-text "Old Corp" "New Corp"
python scripts/pptx_edit.py deck.pptx --chart-data update.json
python scripts/pptx_edit.py deck.pptx --duplicate-slide 2
python scripts/pptx_edit.py deck.pptx --remove-slide 3 --move-slide 2 0
python scripts/pptx_from_template.py brand.pptx out.pptx --values vals.json
python scripts/pptx_render.py deck.pptx --outdir ./render  # slide PNGs

使用 write_file 编写 JSON 规范；使用 read_file 检查脚本输出和生成的 JSON。

快速参考

任务	命令
根据规范创建演示文稿	pptx_create.py spec.json out.pptx
16:9 或 4:3	在规范中设置 "slide_size": "16:9" 或 "4:3"
以 JSON 格式输出大纲	pptx_read.py deck.pptx --outline
导出图片	pptx_read.py deck.pptx --images DIR
替换文本	pptx_edit.py deck.pptx --replace-text OLD NEW
替换图表数据	pptx_edit.py deck.pptx --chart-data spec.json
修补一个数据系列	使用相同标志，规范中包含 "ops"（见下文）
更换图片	pptx_edit.py deck.pptx --swap-image N NAME new.png
复制幻灯片	pptx_edit.py deck.pptx --duplicate-slide N
删除幻灯片	pptx_edit.py deck.pptx --remove-slide N
重新排序幻灯片	pptx_edit.py deck.pptx --move-slide FROM TO
幻灯片背景	pptx_edit.py deck.pptx --set-background N RRGGBB
添加超链接	pptx_edit.py deck.pptx --hyperlink N TEXT URL
启用幻灯片编号	pptx_edit.py deck.pptx --enable-slide-number N
页脚文本	pptx_edit.py deck.pptx --set-footer N TEXT
设置备注	pptx_edit.py deck.pptx --set-notes N TEXT
追加备注	pptx_edit.py deck.pptx --append-notes N TEXT
填充模板	pptx_from_template.py tpl.pptx out.pptx --values v.json
渲染幻灯片 PNG	pptx_render.py deck.pptx --outdir DIR

操作步骤

1. 创建演示文稿

编写 JSON 规范（完整格式请参见 pptx_create.py --help），然后 运行 pptx_create.py。每张幻灯片可设置：layout（title、 title_content、section、two_content、title_only、blank）、title、 subtitle、bullets（字符串，或包含 level 0-4、size pt、 bold、italic、font、color 十六进制值、超链接的 link URL 的字典）、 background（纯色十六进制值）、footer（文本；启用布局的页脚占位符）、 slide_number（true；启用布局的幻灯片编号占位符）、images（路径及以英寸为单位的 left/top/width/height）、tables （rows 为列表的列表）、shapes（rectangle、rounded_rectangle、oval、diamond、right_arrow、chevron，包含 fill 十六进制值和可选的 text）、 charts（bar、bar_h、line、pie，包含 categories 和 series），以及 notes（演讲者备注）。

2. 读取演示文稿

pptx_read.py deck.pptx --outline 返回幻灯片尺寸、版式清单， 以及每张幻灯片的以下信息：版式名称、所有形状文本、表格单元格、图像清单 （文件名/扩展名/字节数）、图表类别/系列/值和演讲者备注。 使用 --images DIR 将嵌入图片导出为文件，然后对任何导出图片运行 vision_analyze 即可查看其内容。

3. 编辑演示文稿

pptx_edit.py 在一次执行中组合多项操作；使用 --output 可保留 原文件。文本替换会扫描幻灯片形状、表格单元格和备注。 替换图片时，会重新指向图片的关系 ID，从而保留位置和大小。 删除幻灯片会移除该关系和 <p:sldId> 项；重排序会在 <p:sldIdLst> 内移动 <p:sldId> 元素 （python-pptx 对这两种操作都没有公开 API；该脚本会在 XML 层面 完成处理）。--duplicate-slide N 会追加幻灯片 N 的独立深拷贝： 克隆形状 XML 以及图像/媒体/超链接关系，并重新映射 rIds， 因此编辑副本绝不会影响原幻灯片。不支持含图表的幻灯片 （请参阅“常见问题”）。--set-notes/--append-notes 可编辑演讲者 备注；--set-background、--hyperlink、--enable-slide-number 和 --set-footer 可优化演示文稿。

通过 --chart-data 传入 JSON 规范即可更新图表。完全替换： {"slide": 0, "chart": 0, "categories": [...], "series": {...}}。对于 局部编辑，请改为传入 "ops"——一个由以下项目组成的列表： {"op": "update_series", "name": ..., "values": [...]}、 add_series、remove_series、rename_category（from/to 或 index）以及 set_title。python-pptx 只能替换图表的整个 数据集（replace_data），因此这些操作通过“读取现有数据 → 修改 → 替换”实现；局部编辑界面由包装器提供，任何无法用类别 + 数值系列表达的数据往返转换后都会被标准化。

4. 从模板构建

pptx_from_template.py 打开一个全新的 .pptx 文件，根据值 JSON 跨幻灯片、表格和备注 替换每个 {{token}}，并且可以追加使用模板自身版式的新幻灯片 （按版式名称或索引），使其继承母版的字体和颜色。提示：如需从 零张幻灯片的模板开始，可在此后使用 pptx_edit.py --remove-slide 删除已有幻灯片。

5. 视觉验证

pptx_render.py deck.pptx --outdir ./render 将演示文稿转换为 PDF， 通过 soffice --headless 进行转换，并通过 pdftoppm 将其拆分为每张幻灯片一个 PNG（或使用 pdftocairo）。输出 JSON 会列出 PNG 路径——请逐一使用 vision_analyze 检查。任一工具缺失时，脚本会退出， 退出代码为 0，并输出 {"rendered": false, "missing": [...]} 及相关提示；此时可改用 pptx_read.py 生成的 JSON 大纲，它能验证内容和 结构，但无法验证视觉效果。

转换为 PDF

如果已安装 LibreOffice，可直接将完成的演示文稿导出为 PDF：

soffice --headless --convert-to pdf --outdir ./out deck.pptx

输出文件位于 ./out/deck.pdf。主机上未安装的字体 会被替换，因此交付 PDF 前请执行渲染验证 （过程第 5 步）。不存在离线纯 Python .pptx→PDF 转换路径；如果缺少 soffice，请如实说明，不要使用近似方案。

注意事项

• 运行拆分：PowerPoint 会在拼写检查和编辑边界处将段落文本拆分为多个运行。--replace-text 会先合并格式相同的相邻运行，因此即使匹配内容被拆分在这些运行中，也能在完整保留格式的情况下替换。只有当匹配内容跨越格式确实不同的运行时，段落才会采用第一个运行的格式重写——替换后请检查这些幻灯片。
• 无法复制图表幻灯片：每个图表关系都会嵌入一个独立的 XLSX 工作簿部件；无法可靠地克隆这类关系图，因此 --duplicate-slide 会干净地拒绝复制图表幻灯片，而不是损坏演示文稿。请改为在新幻灯片上重建图表。外部超链接及图像／媒体关系会沿用；布局和备注关系则会重新创建。
• 图表操作只是包装层：python-pptx 会替换整个数据集；"ops" 会通过 replace_data 对现有绘图数据进行往返处理，且无法更改图表类型。
• 重新排序在 XML 层进行：python-pptx 没有受支持的重新排序 API。--move-slide 会直接操作 <p:sldIdLst>；对普通演示文稿来说是安全的，但之后请重新读取演示文稿进行确认。
• 不支持在不同演示文稿之间复制幻灯片——只能在同一演示文稿中复制，因为其中的布局和母版是共享的。
• 启用页脚／幻灯片编号时，会从幻灯片布局复制占位符；如果布局中没有这些占位符，--set-footer 会失败并给出明确提示（请改为添加文本框）。
• 超链接应用于整个运行；--hyperlink 会为该幻灯片中包含指定文本的每个运行添加链接。
• 默认的 python-pptx 模板为 4:3；除非规范另有说明，否则创建脚本会设置为 16:9。自定义模板会保留自身尺寸。
• 布局索引因模板而异。对于品牌模板，请先列出布局名称：pptx_read.py template.pptx --outline（layouts_available）。
• 空白布局中的 slide.shapes.title 为 None——创建脚本会处理这种情况，但编写临时的 python-pptx 代码时也请记住这一点。
• 写入规范文件时，始终传入 encoding="utf-8"；{{city}} 之类的标记可能会填入非 ASCII 值。

验证

1. 每次创建／编辑后，运行 pptx_read.py OUT.pptx --outline，检查幻灯片数量、文本、表格、备注和图表值是否符合预期。
2. 使用 --images DIR，然后检查文件大小，以确认图片已嵌入。
3. 使用 pptx_render.py deck.pptx --outdir ./render 渲染每张幻灯片，并通过 vision_analyze 检查每个 PNG——这可以发现大纲无法检测的形状重叠、文本截断和颜色问题。如果缺少渲染工具，脚本会给出提示；请依据大纲进行检查。
4. 附带的测试套件就是完整的验收标准：python -m pytest tests/ -q（需要 python-pptx 和 pytest）。