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')。仅当导入失败时,再执行 npm install pptxgenjs。模型了解 API;以下是一些常见陷阱:
- 在添加幻灯片之前设置
pres.layout。 默认画布是LAYOUT_16x9= 10" × 5.625",而不是 13.3" 宽。超出边界的坐标会被写入,但不会被裁剪 —— 形状只是不存在于幻灯片上。(LAYOUT_WIDE是 13.3" × 7.5"。) - 十六进制颜色:永远不要加
#,永远不要用 8 位数字。color: "FF0000"。使用"#FF0000"或将透明度编入十六进制(如"00000020")会损坏文件。对于半透明效果:在填充和图片上使用transparency: 0-100,在阴影上使用opacity: 0.0-1.0—— 每个参数在对方身上都会被静默忽略。 - pptxgenjs 会原地修改选项对象(首次使用时将值转换为 EMU)。永远不要跨两个
add*调用共享同一个shadow/选项对象 —— 每次都要创建一个新对象。 - 阴影
offset必须 ≥ 0 —— 负偏移会损坏文件。要向上投射阴影,请使用angle: 270和正偏移。 letterSpacing会被静默忽略 —— 真正的选项是charSpacing。- 列表: 每个项目上设置
bullet: true,永远不要使用字面量•(会导致双项目符号)。除最后一项外,每个数组项都要设置breakLine: true。使用paraSpaceAfter调整项目符号段落的间距,不要用lineSpacing(会导致巨大间距)。 - 每个输出文件一个
new pptxgen()—— 永远不要重复使用一个实例。 rectRadius只对ROUNDED_RECTANGLE有效,不适用于RECTANGLE。- 不支持渐变填充 —— 改用渐变色图片作为背景。
- 文本框有内置内边距 —— 当文本需要与同一 x 位置上的形状、线条或图标对齐时,请设置
margin: 0。 - 演讲者备注使用
slide.addNotes("...")(纯文本,每张幻灯片一次),永远不要放在幻灯片上的文本框中。 - 保持图表原生。 对于 PowerPoint 可以绘制的所有图表类型,使用
addChart()(对于组合图,传入一个{type, data, options}数组)。对于库未暴露的 PowerPoint 原生功能(趋势线、误差线),自行计算附加系列或对生成的 OOXML 进行后处理 —— 不要退回到渲染图片。只有 PowerPoint 没有原生形式的图表类型(如桑基图、网络图、和弦图)才作为图片插入。 - 默认图表呈现得很简陋 —— 没有标题、没有数据标签、调色板过时。设置
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>的 children。 pptxgenjs 会将<p:notesMasterIdLst>紧接在<p:sldIdLst>之后写入,并将两个母版都指向同一个主题部件。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已预装 —— 仅当导入失败时,再执行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 种辅助色调和一种尖锐的强调色。永远不要给所有颜色相同的权重。
- 深色/浅色对比:标题和结论幻灯片用深色背景,内容用浅色(“三明治”结构)。或者全程使用深色以获得高级感。
- 确定一个视觉主题:选择一个独特的元素并重复使用 —— 圆角图片框、带颜色圆圈内的图标。在每张幻灯片上延续它。不要使用颜色条或强调条纹作为主题(请参阅避免项列表)。
调色板
选择与主题匹配的颜色 —— 不要默认使用通用蓝色。使用以下调色板作为灵感:
| 主题 | 主要色 | 次要色 | 强调色 |
|---|---|---|---|
| 暗夜执行 | 1E2761(藏青色) | CADCFC(冰蓝色) | FFFFFF(白色) |
| 森林与苔藓 | 2C5F2D(森林绿) | 97BC62(苔藓绿) | F5F5F5(奶油色) |
| 珊瑚能量 | F96167(珊瑚色) | F9E795(金色) | 2F3C7E(藏青色) |
| 温暖陶土 | B85042(陶土色) | E7E8D1(沙色) | A7BEAE(鼠尾草绿) |
| 海洋渐变 | 065A82(深蓝色) | 1C7293(蓝绿色) | 21295C(午夜蓝) |
| 炭黑极简 | 36454F(炭黑色) | F2F2F2(米白色) | 212121(黑色) |
| 青色信任 | 028090(青色) | 00A896(海泡绿) | 02C39A(薄荷绿) |
| 浆果与奶油 | 6D2E46(浆果色) | A26769(灰玫瑰粉) | ECE2D0(奶油色) |
| 鼠尾草宁静 | 84B59F(鼠尾草绿) | 69A297(桉树绿) | 50808E(石板蓝) |
| 樱桃醒目 | 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 柔和色 |
…
[省略部分内容以翻译]