PPT 演示文稿

pptx
分类Office
作者Anthropic
许可Proprietary. LICENSE.txt has complete terms
评分4.60/5
使用14.9K

PPTX 创建、编辑与分析

.pptx 文件本质上是一个包含 XML 文件的 ZIP 压缩包。请根据任务选择相应方法：

| 任务 | 方法 |
|---|---|
| 创建新演示文稿 | 编写 pptxgenjs 脚本 —— 详见下文的注意事项 |
| 编辑现有文稿或基于模板构建 | 解压 $\rightarrow$ 编辑 ppt/slides/slideN.xml $\rightarrow$ 重新压缩 |
| 读取内容 | 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）并处理所有包管理簿记录。支持直接传入 .pptx 并使用 -o out.pptx 输出 |
| scripts/clean.py unpacked/ | 删除不再被引用的幻灯片、媒体文件和关系文件。请在 <p:sldIdLst> 最终确定之后运行 |
| scripts/office/validate.py deck.pptx [--original src.pptx] | 检查 Schema、关系、内容类型、图表和幻灯片；每个错误都会提供修复方案。对于基于模板生成的文稿，请传递 --original —— 它将以模板为基准进行 Schema 检查，从而避免将模板自身的 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 或选项对象 —— 每次请构建新对象。
  • 阴影 offset 必须 $\ge 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 无法接受的 slide-XML 缺陷，并给出相应的修复方案。请在生成器中修复，不要手动编辑打包后的 XML。
  • 切勿重新排列 <p:presentation> 的子元素。 pptxgenjs 在 <p:sldIdLst> 之后紧接着写入 <p:notesMasterIdLst>，并将两个主页都指向同一个主题部分。PowerPoint 可以正常读取此结构 —— 但一旦移动该元素，同样的幻灯片将无法打开。
  • 图标： 将 react-icons 渲染为 SVG (ReactDOMServer.renderToStaticMarkup)，使用 sharp 以 $\ge 256\text{px}$ 分辨率光栅化，然后通过 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 使用，将每个内容章节映射到模板页，并多样化布局 —— 不要将所有章节都放在相同的“标题+项目符号”页面上。

bash
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 .)

在目录内部进行 zip 压缩；否则必须先删除，以免残留已删除的部分

python scripts/office/validate.py out.pptx --original deck.pptx
code
- 在编辑任何幻灯片内容之前，先完成所有结构性工作（添加、删除、重新排序）。 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 —— 请改为给 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 进行往返处理会重写命名空间前缀并损坏演示文稿。


  • 模板槽位 $\neq$ 源项目。 如果模板显示 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 种辅助色和一种亮眼的强调色。切勿让所有颜色权重相等。


  • 深浅对比：标题页和结论页使用深色背景，内容页使用浅色（“三明治”结构）。或者全程使用深色以营造高级感。


  • 坚持一种视觉基调 (Motif)：选择一个独特的元素并重复使用 —— 例如圆角图像框、彩色圆圈内的图标。将其贯穿于每张幻灯片中。不要将色条或强调条作为你的视觉基调（见“避免”列表）。


配色方案


选择与主题匹配的颜色 —— 不要默认使用通用蓝色。将这些配色方案作为灵感...
配色方案：


| 主题 | 主色 | 辅助色 | 强调色 |
|-------|---------|-----------|--------|
| 午夜行政 (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 柔和色 |


间距


  • 最小页边距 0.5"


  • 内容块之间保持 0.3-0.5" 间距


  • 留白——不要填满每一寸空间


避免（常见错误）


  • 不要重复相同的布局 —— 在不同幻灯片中变换列数、卡片和标注


  • 不要居中正文 —— 段落和列表应左对齐；仅标题居中


  • 不要忽视尺寸对比 —— 标题需 36pt 以上，以与 14-16pt 的正文区分开


  • 不要默认使用蓝色 —— 选择能反映具体主题的颜色


  • 不要随意混合间距 —— 统一选择 0.3" 或 0.5" 的间隙并保持一致


  • 不要只美化单页幻灯片而让其余页面保持空白 —— 要么全面美化，要么全程保持简洁


  • 不要创建纯文本幻灯片 —— 添加图片、图标、图表或视觉元素；避免简单的“标题 + 列表”形式


  • 不要忘记文本框内边距 —— 当线条或形状与文本边缘对齐时，将文本框设为 margin: 0 或偏移形状以抵消内边距


  • 不要使用低对比度元素 —— 图标和文本与背景之间需有强对比；避免浅色背景配浅色文字或深色背景配深色文字


  • 绝不要在标题下使用强调线 —— 这是 AI 生成幻灯片的典型标志；请改用留白或背景色


  • 绝不要添加装饰性色条或强调条 —— 包括：横跨幻灯片宽度的页眉/页脚条、沿边缘的垂直侧边条、卡片或内容块边缘的细强调条，以及矩形的“单边边框”。这些看起来像 AI 生成的填充物。如果想突出卡片，请使用微妙的背景色、投影或图标，而非边缘条。


  • 不要默认使用奶油色/米色背景 —— 未指定背景时，使用白色 (FFFFFF) 或用户品牌色；避免使用 F5F5DC, FAF0E6, FAEBD7, FFF8E1 等暖中性色


  • 不要交付文本溢出形状的内容 —— 如果文本不适配，请减小字号、拆分至多页或扩大容器；绝不能让内容被截断或超出边界


QA（必须执行）


首次渲染通常会出现一些实际问题 —— 重叠、溢出、对齐偏差。找出并修复这些问题，仅重新渲染修改过的幻灯片，然后停止。


内容 QA
bash markitdown output.pptx
code
检查是否有内容缺失、拼写错误或顺序错误。

使用模板时，检查是否残留占位符文本：
bash
markitdown output.pptx | grep -iE "\bx{3,}\b|lorem|ipsum|\bTODO|\insert|this.*(page|slide).*layout"
code
如果 grep 有返回结果，请在宣布成功前将其修复。


文件 QA（必须执行）
bash python scripts/office/validate.py output.pptx # 从零构建 python scripts/office/validate.py output.pptx --original src.pptx # 基于模板构建
code
如果幻灯片来自模板，务必传递 --original。 模板本身可能包含 XSD 拒绝的部分，直接运行可能会报告非你造成的错误 —— 而真正的回归问题可能会隐藏其中。--original 将架构和幻灯片检查以模板为基准，从而抑制模板原有的错误。结构检查（关系、内容类型、图表）会忽略 --original 并报告继承自模板的问题，请根据实际情况分析。

pptxgenjs 生成的图表 XML 可能会被 PowerPoint 拒绝打开，但其他工具均可接受：python-pptx 可以打开，LibreOffice 可以渲染，XSD 也能通过。每个失败项都会注明修复方法。在生成器中修复并重新构建。


视觉 QA


将幻灯片转换为图像
（参见 [转换为图像）并检查每一张。盯着生成代码看时，你往往会看到你“预期”的结果而非“实际”渲染的结果，因此请以全新的视角审视图像（如果你有子代理，用它来检查效果很好）。重点检查以下用户可见的缺陷：


  • 文本溢出或在方框/幻灯片边界处被截断 —— 优先检查此项。 这是最常见的缺陷，且用户可见度最高。（对于预览器渲染不稳定的字体，预览结果仅为近似值：请信任你预留的 ~10% 冗余空间，而非其表面的适配情况。）


  • 元素重叠（文本穿过形状、线条穿过文字、元素堆叠）


  • 来源引用或页脚与上方内容碰撞


  • 元素距离过近（间距 < 0.3"）或卡片/区块几乎接触


  • 间距不均（某处大面积空白，另一处过于拥挤）


  • 距离幻灯片边缘的页边距不足 (< 0.5")


  • 列或类似元素未对齐


  • 文本对比度低（例如：奶油色背景上的浅灰色文字）


  • 文本替换后模板装饰位置偏移 —— 例如：标题下划线原为单行设计，但替换后的标题换行成了两行


  • 图标对比度低（例如：深色背景上的深色图标且没有对比色圆圈）


  • 文本框过窄导致过度换行


  • 遗留的占位符内容


转换为图像


将演示文稿转换为单页幻灯片图像以便视觉检查：
bash
python scripts/office/soffice.py --headless --convert-to pdf output.pptx
rm -f slide-*.jpg
pdftoppm -jpeg -r 150 output.pdf slide
ls -1 "$PWD"/slide-*.jpg
``

将上述打印出的绝对路径直接传递给查看工具。 rm 命令用于清除之前运行产生的旧图像。pdftoppm 会根据页数进行补零：10 页以下为 slide-1.jpg，10-99 页为 slide-01.jpg，100 页以上为 slide-001.jpg。

修复后，请重新运行上述所有四条命令 —— 必须先从编辑后的 .pptx 重新生成 PDF，pdftoppm 才能反映你的更改。

依赖项

pptxgenjs (npm, 预装 —— 仅在 require('pptxgenjs') 失败时安装) · markitdown[pptx], Pillow, defusedxml, lxml (pip —— 用于文本导出、缩略图、清理、验证) · LibreOffice (soffice, 通过 scripts/office/soffice.py 为沙箱环境自动配置) · pdftoppm` (Poppler)