PPTX 创建、编辑和分析
一个 .pptx 文件是 XML 文件的 ZIP 归档。根据任务选择方法:
| 任务 | 方法 |
|---|---|
| 创建 新演示文稿 | 编写 pptxgenjs 脚本 — 请查看下面的注意事项 |
| 编辑 现有演示文稿,或基于模板构建 | 解压 → 编辑 ppt/slides/slideN.xml → 重新压缩 |
| 读取 内容 | markitdown deck.pptx(在 <!-- Slide number: N --> 标记下每张幻灯片一个块);可视化网格:python scripts/thumbnail.py deck.pptx |
脚本
路径相对于此技能目录。其他均为纯 Python、node 或 shell。
| 脚本 | 功能说明 |
|---|---|
scripts/thumbnail.py deck.pptx [prefix] | 每张幻灯片的带标签网格,用于选择模板布局。仅限 .pptx。传递 prefix — 默认为 thumbnails,它会覆盖同一目录中任何其他演示文稿的网格 |
scripts/add_slide.py unpacked/ slide2.xml [--after slideN.xml] | 复制幻灯片(或 slideLayoutN.xml)并处理所有包内账务。也可通过 -o out.pptx 直接对 .pptx 文件操作 |
scripts/clean.py unpacked/ | 删除不再被引用的幻灯片、媒体和关联文件。在 <p:sldIdLst> 最终确定后运行 |
scripts/office/validate.py deck.pptx [--original src.pptx] | 架构、关联、内容类型、图表和幻灯片检查;每个失败项都会指明修复方法。传递 --original 用于任何基于模板的演示文稿 — 它会以模板为基准进行架构检查,这样模板自身的 XSD 错误就不会算作你的错误 |
scripts/office/soffice.py --headless --convert-to pdf deck.pptx | LibreOffice 包装器 — 裸 soffice 会在此沙盒中挂起 |
使用 pptxgenjs 创建 — 注意事项
pptxgenjs 已预装 — 不要运行 npm install;直接编写脚本并 require('pptxgenjs')。仅当 require 失败时才运行 npm install pptxgenjs。模型知道 API;以下是一些陷阱:
- 在添加幻灯片之前设置
pres.layout。 默认画布是LAYOUT_16x9= 10" × 5.625",而不是 13.3" 宽。超出边缘的坐标会被写入,但不会被裁剪 — 形状只是不在幻灯片上。(LAYOUT_WIDE是 13.3" × 7.5"。) - 十六进制颜色:永远不要用
#,永远不要用 8 位数字。 使用color: "FF0000"。"#FF0000"和嵌入十六进制的 Alpha 值("00000020")都会损坏文件。对于半透明:在填充和图像上使用transparency: 0-100,在阴影上使用opacity: 0.0-1.0— 每个属性在另一个属性上都会被静默忽略。 - pptxgenjs 会原地修改选项对象(首次使用时将值转换为 EMU)。永远不要跨两次
add*调用共享同一个shadow/options 对象 — 每次都构建一个新对象。 - 阴影
offset必须 ≥ 0 — 负偏移会损坏文件。要向上投射阴影,请使用angle: 270和正偏移。 letterSpacing会被静默忽略 — 实际选项是charSpacing。- 列表: 每个项目使用
bullet: true,永远不要使用文字•(会导致双项目符号)。除最后一项外,每个数组项都设置breakLine: true。使用paraSpaceAfter分隔带项目符号的段落,不要使用lineSpacing(会产生巨大间隙)。 - 每个输出文件一个
new pptxgen()— 永远不要重用实例。 rectRadius仅适用于ROUNDED_RECTANGLE,不适用于RECTANGLE。- 不支持渐变填充 — 请改用渐变图像作为背景。
- 文本框有内置内边距 — 当文本必须与同一 x 位置的形状、线条或图标对齐时,请设置
margin: 0。 - 演讲者备注写在
slide.addNotes("...")中(纯文本,每张幻灯片一次),永远不要放在幻灯片上的文本框中。 - 保留图表的原生性。 使用
addChart()处理所有 PowerPoint 可以绘制的图表(传递一个{type, data, options}数组用于组合图)。对于库未公开的 PowerPoint 原生功能(趋势线、误差线),请自行计算额外系列或后处理生成的 OOXML — 不要退回到渲染图像。仅当 PowerPoint 没有原生形式时才将图表类型(Sankey、网络、和弦图)作为图像导入。 - 默认图表渲染简陋 — 无标题、无数据标签、调色板过时。设置
showTitle+title、showValue: true+dataLabelPosition、来自你调色板的chartColors: [...],并静默框架(catAxisLabelColor/valAxisLabelColor、valGridLine: { color, size }、catGridLine: { style: "none" }、对于单一系列设置showLegend: false)。 - 在堆叠条形图或柱状图上,
dataLabelPosition必须为ctr、inEnd或inBase。outEnd会损坏文件。 - 使用
secondaryValAxis/secondaryCatAxis的组合系列需要在图表选项上同时提供valAxes和catAxes,每个各两个条目。 如果没有它们,pptxgenjs 会写入它从未声明的轴 ID,PowerPoint 会丢弃该图表并将文件报告为已损坏。仅提供valAxes是不够的。 - 在
writeFile()之后,运行python scripts/office/validate.py deck.pptx。 它会报告上述两个图表故障以及 PowerPoint 拒绝的幻灯片 XML 缺陷,并为每个缺陷指明修复方法。在你的生成器中修复它们,而不是手动编辑打包的 XML。 - 永远不要重新排序
<p:presentation>的子元素。 pptxgenjs 会在<p:sldIdLst>之后直接写入<p:notesMasterIdLst>,并将两个母版指向同一个主题部分。PowerPoint 可以愉快地读取它 — 移动该元素后,同一个演示文稿将无法打开。 - 图标: 将
react-icons渲染为 SVG(ReactDOMServer.renderToStaticMarkup),使用sharp以 ≥256px 大小进行光栅化,并通过addImage({ data: "image/png;base64," + buf.toString("base64") })插入 —image/png;base64,前缀是必需的(react-icons、react、react-dom和sharp已预装 — 仅在 require 失败时才运行npm install react-icons react react-dom sharp)。
编辑现有演示文稿和模板
首先选择布局:python scripts/thumbnail.py template.pptx template-thumbs 会为每张幻灯片生成一个带标签的网格,并打印它创建的文件 — template-thumbs.jpg,超过 12 张幻灯片后会拆分为 template-thumbs-N.jpg。始终传递第二个参数,并以演示文稿命名。 它默认为 thumbnails,因此同一目录中两个演示文稿的缩略图会静默覆盖彼此的网格 — 第一个演示文稿的网格就此消失(仅用于模板分析 — 视觉 QA 需要来自转换为图像的全分辨率渲染;它只接受 .pptx,因此请先将 .potx 复制为 .pptx 名称)。将其与 markitdown 结合使用,将每个内容部分映射到模板幻灯片,并变化布局 — 不要将所有部分放在同一张标题和项目符号幻灯片上。
python3 -c "import sys,zipfile; zipfile.ZipFile(sys.argv[1]).extractall('unpacked')" deck.pptx
python scripts/add_slide.py unpacked/ slide2.xml --after slide2.xml # 复制幻灯片(或 slideLayoutN.xml);打印新幻灯片的路径
# 重新排序/删除幻灯片 = 编辑 ppt/presentation.xml 中的 <p:sldIdLst>
python scripts/clean.py unpacked/ # 删除后:移除孤立的幻灯片、媒体、关联文件
# 编辑 ppt/slides/slideN.xml 中的幻灯片内容
(cd unpacked && rm -f ../out.pptx && zip -Xr ../out.pptx .) # 从目录**内部**压缩;先 rm 删除,否则删除的部分会保留
python scripts/office/validate.py out.pptx --original deck.pptx
- 在编辑任何幻灯片内容之前,完成所有结构性工作 — 添加、删除、重新排序。
add_slide.py会逐字复制幻灯片文件,因此在编辑后复制会克隆已编辑的内容;而clean.py会删除任何不在<p:sldIdLst>中的幻灯片,包括你刚写入的那张。 - 永远不要手动复制幻灯片文件 —
add_slide.py会完成新幻灯片所需的所有注册,并报告其内容(Created ppt/slides/slide17.xml from slide2.xml)。它也可以直接对文件操作:add_slide.py deck.pptx slide2.xml -o out.pptx— 传递-o,否则它会原地重写输入演示文稿。 复制的幻灯片仍然引用其来源的图表/SmartArt/嵌入对象部分,而不是克隆它们,因此编辑一张幻灯片的图表会更改另一张的图表。 - 如果你使用
python-pptx,它有三件事不能做:复制幻灯片(其唯一入口点是add_slide(layout));通过text_frame.text = "..."保留格式(这会将段落折叠为单个未样式化的运行 — 请改用run.text赋值);读取大多数模板艺术使用的 SVG/EMF(add_picture会引发UnidentifiedImageError)。 - 旧版
.ppt必须首先转换:python scripts/office/soffice.py --headless --convert-to pptx file.ppt。.potx模板的解压和打包方式完全相同 — 在输出上保留.potx扩展名。 - 要重用模板图标或图像,请复制已包含它的幻灯片或布局。
填充模板时:
- 如果你编写 XML 转换脚本,请使用
defusedxml.minidom解析 — 通过xml.etree.ElementTree往返处理 OOXML 会重写命名空间前缀并损坏演示文稿。 - 模板插槽 ≠ 源项目。 如果模板显示 4 个团队成员而你只有 3 个,请删除第 4 个成员的整个组(图像 + 文本框),而不仅仅是其文本 — 然后在 QA 中检查是否有孤立的视觉元素。
- 每个列表项一个
<a:p>— 永远不要将多个项目连接成单个段落。复制兄弟<a:pPr>以保留间距,并在标题、节标题和内联标签(Status:、Owner:)的<a:rPr>上设置b="1"。 - 让项目符号从布局继承;仅在需要覆盖时添加
<a:buChar>、<a:buAutoNum>(编号)或<a:buNone>— 永远不要在文本中使用文字•。 - 带有前导或尾部空格的文本需要在其
<a:t>上设置xml:space="preserve"。
设计创意
不要创建乏味的幻灯片。 白色背景上的纯项目符号不会给任何人留下深刻印象。考虑为每张幻灯片从以下列表中选择创意。
开始之前
- 选择大胆、内容相关的配色方案:调色板应该感觉是针对此主题设计的。如果将这些颜色换到完全不同的演示文稿中仍然“可行”,那说明你的选择不够具体。
- 主导性而非平等性:一种颜色应占主导地位(60-70% 的视觉权重),搭配 1-2 种辅助色调和一种锐利的强调色。永远不要给所有颜色相同的权重。
- 深色/浅色对比:标题和结论幻灯片使用深色背景,内容幻灯片使用浅色背景("三明治"结构)。或者坚持通篇深色以获得高级感。
- 确定一个视觉主题:选择一个独特的元素并重复使用它 — 圆角图像框、彩色圆圈中的图标。在每张幻灯片上贯彻使用它。不要使用颜色条或强调条纹作为你的主题(参见避免列表)。
配色方案
选择与主题匹配的颜色 — 不要默认使用通用的蓝色。使用这些调色板作为灵感:
| 主题 | 主要色 | 次要色 | 强调色 |
|---|---|---|---|
| Midnight Executive | 1E2761 (海军蓝) | CADCFC (冰蓝) | FFFFFF (白色) |
| Forest & Moss | 2C5F2D (森林绿) | 97BC62 (苔藓绿) | F5F5F5 (奶油色) |
| Coral Energy | F96167 (珊瑚红) | F9E795 (金色) | 2F3C7E (海军蓝) |
| Warm Terracotta | B85042 (陶土红) | E7E8D1 (沙色) | A7BEAE (鼠尾草绿) |
| Ocean Gradient | 065A82 (深蓝) | 1C7293 (蓝绿色) | 21295C (午夜蓝) |
| Charcoal Minimal | 36454F (炭灰色) | F2F2F2 (米白色) | 212121 (黑色) |
| Teal Trust | 028090 (蓝绿色) | 00A896 (海沫绿) | 02C39A (薄荷绿) |
| Berry & Cream | 6D2E46 (浆果紫) | A26769 (灰玫瑰色) | ECE2D0 (奶油色) |
| Sage Calm | 84B59F (鼠尾草绿) | 69A297 (桉树绿) | 50808E (石板灰) |
| Cherry Bold | 990011 (樱桃红) | FCF6F5 (米白色) | 2F3C7E (海军蓝) |
每张幻灯片
每张幻灯片都需要一个视觉元素 — 图像、图表、图标或形状。纯文本幻灯片容易被遗忘。
布局选项:
- 两栏(左侧文本,右侧插图)
- 图标 + 文本行(彩色圆圈中的图标,粗体标题,下方描述)
- 2x2 或 2x3 网格(一侧是图像,另一侧是内容块网格)
- 半出血图像(整个左侧或右侧)并带有内容叠加
数据显示:
- 大数字标注(60-72pt 的大号数字,下方带小标签)
- 对比栏(前后对比、优缺点、并排选项)
- 时间线或流程(带编号的步骤、箭头)
视觉润色:
- 部分标题旁边的小彩色圆圈中的图标
- 关键统计数据或标语的斜体强调文本
排版
你写入 .pptx 的字体名称由用户的 PowerPoint 渲染,而非此环境。 你的视觉 QA 通过 LibreOffice 渲染,它会替换没有的字体 — 对于某些字体,替代字体具有不同的宽度,因此你的 QA 预览可能显示文本溢出(或适应),而实际演示文稿不会出现这种情况。要使你的 QA 可信:
- 安全字体(在 QA 中按实际宽度渲染并且随 Office 提供):Arial, Calibri, Cambria, Times New Roman, Courier New, Bookman Old Style, Century Schoolbook。将这些用于正文文本和任何需要确定适配性的内容。
- 零 QA 风险下具有个性的标题:将安全列表中的衬线标题(Cambria, Bookman Old Style, Century Schoolbook)与安全列表中的无衬线正文(Calibri 或 Arial)配对。你可以在不放弃可靠溢出检查的情况下获得视觉对比。
- 如果用户要求使用安全列表之外的字体(例如 Georgia 或 Trebuchet MS):在用户要求的地方使用它,但将这些容器的大小留出额外的余量(约 10%),并且不要信任这些元素的 QA 文本适配 — 该字体的预览是近似的。如果用户未指定,正文文本首选安全列表中的字体。
- QA 不可靠的字体(替代字体具有不同的宽度 — 溢出检查可能出错):Georgia, Trebuchet MS, Impact, Arial Black, Garamond, Consolas, Palatino Linotype。Calibri Light 的替代字体因环境而异;将其视为 QA 不可靠。适用于带有余量的标题/强调文本;不要信任这些字体上的 QA 文本适配。
- 永远不要默认使用 Aptos — Office 2023 之后的默认字体在此处没有度量兼容的替代字体并且在旧版 Office 安装中缺失,因此它在两端都不可靠。
| 元素 | 字号 |
|---|---|
| 幻灯片标题 | 36-44pt 粗体 |
| 部分标题 | 20-24pt 粗体 |
| 正文文本 | 14-16pt |
| 说明文字 | 10-12pt 柔和 |