pptx

PPTX 创建、编辑和分析

概述

用户可能会要求你创建、编辑或分析 .pptx 文件的内容。.pptx 文件本质上是一个 ZIP 归档文件，其中包含 XML 文件和其他资源，你可以读取或编辑这些内容。针对不同任务，你可以使用不同的工具和工作流。

读取和分析内容

文本提取

如果你只需要读取演示文稿的文本内容，应将文档转换为 markdown：

# Convert document to markdown
python -m markitdown path-to-file.pptx

原始 XML 访问

以下情况需要访问原始 XML：批注、演讲者备注、幻灯片版式、动画、设计元素和复杂格式。对于任何这些功能，你都需要解包演示文稿并读取其原始 XML 内容。

解包文件

python ooxml/scripts/unpack.py <office_file> <output_dir>

注意：unpack.py 脚本位于相对于项目根目录的 skills/pptx/ooxml/scripts/unpack.py。如果该脚本不存在于此路径，请使用 find . -name "unpack.py" 定位它。

关键文件结构

• ppt/presentation.xml - 主演示文稿元数据和幻灯片引用
• ppt/slides/slide{N}.xml - 各个幻灯片内容（slide1.xml、slide2.xml 等）
• ppt/notesSlides/notesSlide{N}.xml - 每张幻灯片的演讲者备注
• ppt/comments/modernComment_*.xml - 特定幻灯片的批注
• ppt/slideLayouts/ - 幻灯片版式模板
• ppt/slideMasters/ - 幻灯片母版模板
• ppt/theme/ - 主题和样式信息
• ppt/media/ - 图片和其他媒体文件

字体和颜色提取

当给定示例设计以供仿照时：始终先使用以下方法分析演示文稿的字体和颜色：

1. 读取主题文件：检查 ppt/theme/theme1.xml 中的颜色（<a:clrScheme>）和字体（<a:fontScheme>）
2. 抽样幻灯片内容：检查 ppt/slides/slide1.xml 中的实际字体使用情况（<a:rPr>）和颜色
3. 搜索模式：使用 grep 在所有 XML 文件中查找颜色（<a:solidFill>、<a:srgbClr>）和字体引用

创建新的 PowerPoint 演示文稿 不使用模板

从头创建新的 PowerPoint 演示文稿时，使用 html2pptx 工作流将 HTML 幻灯片转换为 PowerPoint，并实现准确定位。

设计原则

关键：在创建任何演示文稿之前，分析内容并选择合适的设计元素：

1. 考虑主题内容：这个演示文稿是关于什么的？它暗示了什么样的语气、行业或氛围？
2. 检查品牌元素：如果用户提到某个公司/组织，请考虑其品牌颜色和标识
3. 让配色匹配内容：选择能反映主题的颜色
4. 说明你的方案：在编写代码之前解释你的设计选择

要求：

• ✅ 在编写代码之前，说明你基于内容的设计方案
• ✅ 仅使用网页安全字体：Arial、Helvetica、Times New Roman、Georgia、Courier New、Verdana、Tahoma、Trebuchet MS、Impact
• ✅ 通过大小、粗细和颜色创建清晰的视觉层次
• ✅ 确保可读性：强对比度、适当大小的文本、整洁的对齐
• ✅ 保持一致：在幻灯片中重复图案、间距和视觉语言

配色方案选择

创造性地选择颜色：

• 跳出默认思维：哪些颜色真正契合这个特定主题？避免惯性选择。
• 从多个角度考虑：主题、行业、情绪、活力程度、目标受众、品牌形象（如有提及）
• 大胆尝试：尝试意想不到的组合——医疗健康类演示不一定要用绿色，金融类不一定要用藏青色
• 构建你的调色板：挑选 3-5 种相互协调的颜色（主色 + 辅助色调 + 点缀色）
• 确保对比度：文字在背景上必须清晰可读

示例配色方案（用这些来激发创意——选择一种、加以调整，或创造你自己的）：

1. 经典蓝：深藏青（#1C2833）、石板灰（#2E4053）、银色（#AAB7B8）、米白（#F4F6F6）
2. 青绿与珊瑚：青绿（#5EA8A7）、深青绿（#277884）、珊瑚（#FE4447）、白色（#FFFFFF）
3. 醒目红：红色（#C0392B）、亮红（#E74C3C）、橙色（#F39C12）、黄色（#F1C40F）、绿色（#2ECC71）
4. 暖调腮红：淡紫灰（#A49393）、腮红（#EED6D3）、玫瑰（#E8B4B8）、奶油（#FAF7F2）
5. 勃艮第奢华：勃艮第红（#5D1D2E）、深红（#951233）、铁锈色（#C15937）、金色（#997929）
6. 深紫与祖母绿：紫色（#B165FB）、深蓝（#181B24）、祖母绿（#40695B）、白色（#FFFFFF）
7. 奶油与森林绿：奶油（#FFE1C7）、森林绿（#40695B）、白色（#FCFCFC）
8. 粉与紫：粉色（#F8275B）、珊瑚（#FF574A）、玫瑰（#FF737D）、紫色（#3D2F68）
9. 青柠与梅紫：青柠（#C5DE82）、梅紫（#7C3A5F）、珊瑚（#FD8C6E）、蓝灰（#98ACB5）
10. 黑与金：金色（#BF9A4A）、黑色（#000000）、奶油（#F4F6F6）
11. 鼠尾草与陶土：鼠尾草绿（#87A96B）、陶土（#E07A5F）、奶油（#F4F1DE）、炭黑（#2C2C2C）
12. 炭黑与红：炭黑（#292929）、红色（#E33737）、浅灰（#CCCBCB）
13. 活力橙：橙色（#F96D00）、浅灰（#F2F2F2）、炭黑（#222831）
14. 森林绿：黑色（#191A19）、绿色（#4E9F3D）、深绿（#1E5128）、白色（#FFFFFF）
15. 复古彩虹：紫色（#722880）、粉色（#D72D51）、橙色（#EB5C18）、琥珀（#F08800）、金色（#DEB600）
16. 复古大地色：芥末黄（#E3B448）、鼠尾草绿（#CBD18F）、森林绿（#3A6B35）、奶油（#F4F1DE）
17. 海岸玫瑰：旧玫瑰（#AD7670）、海狸棕（#B49886）、蛋壳白（#F3ECDC）、灰绿（#BFD5BE）
18. 橙与绿松石：浅橙（#FC993E）、灰绿松石（#667C6F）、白色（#FCFCFC）

视觉细节选项

几何图案：

• 使用对角线分区而非水平分隔
• 非对称列宽 (30/70、40/60、25/75)
• 90° 或 270° 旋转的文字标题
• 图像的圆形/六边形框架
• 角落的三角形装饰形状
• 重叠形状以营造深度感

边框与框架处理：

• 仅在一侧使用粗单色边框 (10-20pt)
• 使用对比色的双线边框
• 使用角括号而非完整框架
• L 形边框 (顶部+左侧或底部+右侧)
• 标题下方的下划线装饰 (3-5pt 粗)

字体处理：

• 极端的大小对比 (72pt 标题 vs 11pt 正文)
• 全大写标题并加宽字间距
• 超大展示字体中的编号章节
• 数据/统计/技术内容使用等宽字体 (Courier New)
• 密集信息使用压缩字体 (Arial Narrow)
• 使用轮廓文字以强调

图表与数据样式：

• 单色图表，使用单一强调色突出关键数据
• 使用水平条形图而非垂直条形图
• 使用点图而非条形图
• 最小化网格线或不使用
• 数据标签直接标在元素上 (不使用图例)
• 关键指标使用超大数字

布局创新：

• 全出血图像配合文字叠加
• 侧边栏列 (20-30% 宽度) 用于导航/上下文
• 模块化网格系统 (3×3、4×4 区块)
• Z 形或 F 形内容流
• 浮动的文本框置于彩色形状之上
• 杂志风格的多栏布局

背景处理：

• 占据幻灯片 40-60% 的纯色块
• 渐变填充 (仅垂直或对角线)
• 分割背景 (双色，对角线或垂直)
• 从边到边的色带
• 将负空间作为设计元素

布局提示

创建包含图表或表格的幻灯片时：

• 双栏布局（首选）：使用横跨全宽的标题，然后在下方分为两栏——一栏放置文本/项目符号，另一栏放置特色内容。这能提供更好的平衡，并使图表/表格更易读。使用不等列宽的 flexbox（例如 40%/60% 分割）来优化每种内容类型的空间。
• 全幻灯片布局：让特色内容（图表/表格）占据整个幻灯片，以实现最大冲击力和可读性
• 切勿垂直堆叠：不要在单栏中将图表/表格置于文本下方——这会导致可读性差和布局问题

工作流

1. 强制要求 - 阅读整个文件：从头到尾完整阅读 html2pptx.md。阅读此文件时绝不能设置任何范围限制。 在继续创建演示文稿之前，请阅读完整文件内容，了解详细语法、关键格式规则和最佳实践。
2. 为每张幻灯片创建一个尺寸合适的 HTML 文件（例如，16:9 使用 720pt × 405pt）
   • 所有文本内容使用 <p>、<h1>-<h6>、<ul>、<ol>
   • 对于将添加图表/表格的区域，使用 class="placeholder"（以灰色背景渲染以便识别）
   • 关键：先使用 Sharp 将渐变和图标栅格化为 PNG 图片，然后在 HTML 中引用
   • 布局：对于包含图表/表格/图片的幻灯片，使用全幻灯片布局或双栏布局以提高可读性
3. 使用 html2pptx.js 库创建并运行一个 JavaScript 文件，将 HTML 幻灯片转换为 PowerPoint 并保存演示文稿
   • 使用 html2pptx() 函数处理每个 HTML 文件
   • 使用 PptxGenJS API 将图表和表格添加到占位区域
   • 使用 pptx.writeFile() 保存演示文稿
4. 视觉验证：生成缩略图并检查布局问题
   • 创建缩略图网格：python scripts/thumbnail.py output.pptx workspace/thumbnails --cols 4
   • 阅读并仔细检查缩略图，检查以下问题：
     • 文本截断：文本被页眉栏、形状或幻灯片边缘截断
     • 文本重叠：文本与其他文本或形状重叠
     • 定位问题：内容过于靠近幻灯片边界或其他元素
     • 对比度问题：文本与背景之间的对比度不足
   • 如果发现问题，请调整 HTML 边距/间距/颜色并重新生成演示文稿
   • 重复此过程，直到所有幻灯片在视觉上正确无误

编辑现有 PowerPoint 演示文稿

在编辑现有 PowerPoint 演示文稿中的幻灯片时，你需要使用原始的 Office Open XML（OOXML）格式。这包括解包 .pptx 文件、编辑 XML 内容，然后重新打包。

工作流

1. 强制要求 - 阅读整个文件：从头到尾完整阅读 ooxml.md（约 500 行）。阅读此文件时绝不能设置任何范围限制。 在进行任何演示文稿编辑之前，请阅读完整文件内容，了解有关 OOXML 结构和编辑工作流的详细指导。
2. 解包演示文稿：python ooxml/scripts/unpack.py <office_file> <output_dir>
3. 编辑 XML 文件（主要是 ppt/slides/slide{N}.xml 及相关文件）
4. 关键：每次编辑后立即验证，并在继续之前修复所有验证错误：python ooxml/scripts/validate.py <dir> --original <file>
5. 打包最终演示文稿：python ooxml/scripts/pack.py <input_directory> <office_file>

使用模板创建新的 PowerPoint 演示文稿

当你需要创建遵循现有模板设计的演示文稿时，你需要先复制和重新排列模板幻灯片，然后替换占位内容。

工作流

1. 提取模板文本并创建视觉缩略图网格：

   • 提取文本：python -m markitdown template.pptx > template-content.md
   • 阅读 template-content.md：阅读整个文件以了解模板演示文稿的内容。阅读此文件时绝不能设置任何范围限制。
   • 创建缩略图网格：python scripts/thumbnail.py template.pptx
   • 更多详细信息请参阅创建缩略图网格部分

2. 分析模板并将清单保存到文件：

   • 视觉分析：查看缩略图网格以了解幻灯片布局、设计模式和视觉结构

   • 创建并保存模板清单文件到 template-inventory.md，包含：

     # 模板清单分析
     
     **幻灯片总数：[count]**
     **重要：幻灯片以 0 为起始索引（第一张幻灯片 = 0，最后一张幻灯片 = count-1）**
     ## [类别名称]
     
     - 幻灯片 0：[布局代码（如有）] - 描述/用途
     - 幻灯片 1：[布局代码] - 描述/用途
     - 幻灯片 2：[布局代码] - 描述/用途
       [... 每一张幻灯片都必须按其索引单独列出 ...]
     

   • 使用缩略图网格：参考可视化缩略图以识别：

     • 布局模式（标题幻灯片、内容布局、章节分隔页）
     • 图片占位符的位置和数量
     • 各幻灯片组之间的设计一致性
     • 视觉层级和结构

   • 此清单文件是下一步选择合适模板的必需文件

3. 根据模板清单创建演示文稿大纲：

   • 查看第 2 步中获得的可用模板。
   • 为第一张幻灯片选择一个引言或标题模板。这应当是排在最前面的模板之一。
   • 为其他幻灯片选择稳妥的、基于文本的布局。
   • 关键：将布局结构与实际内容相匹配：
     • 单栏布局：用于统一的叙述或单一主题
     • 双栏布局：仅当恰好有 2 个不同的条目/概念时使用
     • 三栏布局：仅当恰好有 3 个不同的条目/概念时使用
     • 图片 + 文本布局：仅当有实际图片需要插入时使用
     • 引语布局：仅用于人物的真实引语（附出处），绝不用于强调
     • 切勿使用占位符多于内容的布局
     • 如果有 2 个条目，不要强行套入三栏布局
     • 如果有 4 个或更多条目，考虑拆分为多张幻灯片或使用列表格式
   • 在选择布局之前，先清点实际的内容块数量
   • 确认所选布局中的每个占位符都将填入有意义的内容
   • 为每个内容部分选择一个代表最佳布局的选项。
   • 保存 outline.md，其中包含内容以及利用可用设计的模板映射
   • 模板映射示例：

     # Template slides to use (0-based indexing)
     # WARNING: Verify indices are within range! Template with 73 slides has indices 0-72
     # Mapping: slide numbers from outline -> template slide indices
     template_mapping = [
         0,   # Use slide 0 (Title/Cover)
         34,  # Use slide 34 (B1: Title and body)
         34,  # Use slide 34 again (duplicate for second B1)
         50,  # Use slide 50 (E1: Quote)
         54,  # Use slide 54 (F2: Closing + Text)
     ]
     

4. 使用 rearrange.py 复制、重新排序和删除幻灯片：

   • 使用 scripts/rearrange.py 脚本按所需顺序创建包含幻灯片的新演示文稿：

     python scripts/rearrange.py template.pptx working.pptx 0,34,34,50,52
     

   • 该脚本会自动处理重复幻灯片的复制、未使用幻灯片的删除以及重新排序
   • 幻灯片索引从 0 开始（第一张幻灯片为 0，第二张为 1，依此类推）
   • 同一个幻灯片索引可以出现多次，以复制该幻灯片

5. 使用 inventory.py 脚本提取所有文本：

   • 运行清单提取：

     python scripts/inventory.py working.pptx text-inventory.json
     

   • 读取 text-inventory.json：阅读整个 text-inventory.json 文件，以了解所有形状及其属性。读取此文件时切勿设置任何范围限制。

   • 清单 JSON 结构：

     {
       "slide-0": {
         "shape-0": {
           "placeholder_type": "TITLE", // 非占位符则为 null
           "left": 1.5, // 位置，单位为英寸
           "top": 2.0,
           "width": 7.5,
           "height": 1.2,
           "paragraphs": [
             {
               "text": "Paragraph text",
               // 可选属性（仅在非默认值时包含）：
               "bullet": true, // 检测到显式项目符号
               "level": 0, // 仅在 bullet 为 true 时包含
               "alignment": "CENTER", // CENTER、RIGHT（不包含 LEFT）
               "space_before": 10.0, // 段前间距，单位为磅
               "space_after": 6.0, // 段后间距，单位为磅
               "line_spacing": 22.4, // 行距，单位为磅
               "font_name": "Arial", // 取自首个 run
               "font_size": 14.0, // 单位为磅
               "bold": true,
               "italic": false,
               "underline": false,
               "color": "FF0000" // RGB 颜色
             }
           ]
         }
       }
     }
     

   • 主要特性：

     • 幻灯片：命名为 "slide-0"、"slide-1" 等。
     • 形状：按视觉位置排序（从上到下、从左到右），命名为 "shape-0"、"shape-1" 等。
     • 占位符类型：TITLE、CENTER_TITLE、SUBTITLE、BODY、OBJECT 或 null
     • 默认字体大小：从布局占位符中提取的 default_font_size，单位为磅（如可用）
     • 幻灯片编号会被过滤：占位符类型为 SLIDE_NUMBER 的形状会自动从清单中排除
     • 项目符号：当 bullet: true 时，始终包含 level（即使为 0）
     • 间距：space_before、space_after 和 line_spacing，单位为磅（仅在设置时包含）
     • 颜色：color 表示 RGB（例如 "FF0000"），theme_color 表示主题颜色（例如 "DARK_1"）
     • 属性：输出中仅包含非默认值

6. 生成替换文本并将数据保存到 JSON 文件 基于上一步得到的文本清单：

   • 关键：首先确认清单中存在哪些形状——只引用实际存在的形状
   • 校验：replace.py 脚本会校验替换 JSON 中的所有形状都存在于清单中
     • 如果引用了不存在的形状，会收到一个错误并列出可用形状
     • 如果引用了不存在的幻灯片，会收到一个错误，提示该幻灯片不存在
     • 所有校验错误会在脚本退出前一次性显示
   • 重要：replace.py 脚本内部使用 inventory.py 来识别所有文本形状
   • 自动清空：清单中的所有文本形状都会被清空，除非你为它们提供 "paragraphs"
   • 为需要内容的形状添加 "paragraphs" 字段（而不是 "replacement_paragraphs"）
   • 替换 JSON 中没有 "paragraphs" 的形状，其文本会被自动清空
   • 带项目符号的段落会自动左对齐。当 "bullet": true 时，不要设置 alignment 属性
   • 为占位符文本生成合适的替换内容
   • 根据形状大小确定合适的内容长度
   • 关键：包含来自原始清单的段落属性——不要只提供文本
   • 重要：当 bullet: true 时，不要在文本中包含项目符号（•、-、*）——它们会自动添加
   • 基本格式规则：
     • 页眉/标题通常应设置 "bold": true
     • 列表项应设置 "bullet": true, "level": 0（当 bullet 为 true 时必须提供 level）
     • 保留任何对齐属性（例如，居中文本使用 "alignment": "CENTER"）
     • 当与默认值不同时，包含字体属性（例如 "font_size": 14.0、"font_name": "Lora"）
     • 颜色：RGB 使用 "color": "FF0000"，主题颜色使用 "theme_color": "DARK_1"
     • 替换脚本期望的是格式正确的段落，而不仅仅是文本字符串
     • 重叠形状：优先选择 default_font_size 更大或 placeholder_type 更合适的形状
   • 将带有替换内容的更新后清单保存到 replacement-text.json
   • 警告：不同的模板布局具有不同的形状数量——在创建替换内容前务必检查实际清单

   示例 paragraphs 字段展示正确的格式：

   "paragraphs": [
     {
       "text": "New presentation title text",
       "alignment": "CENTER",
       "bold": true
     },
     {
       "text": "Section Header",
       "bold": true
     },
     {
       "text": "First bullet point without bullet symbol",
       "bullet": true,
       "level": 0
     },
     {
       "text": "Red colored text",
       "color": "FF0000"
     },
     {
       "text": "Theme colored text",
       "theme_color": "DARK_1"
     },
     {
       "text": "Regular paragraph text without special formatting"
     }
   ]
   

   未在替换 JSON 中列出的形状会被自动清空：

   {
     "slide-0": {
       "shape-0": {
         "paragraphs": [...] // This shape gets new text
       }
       // shape-1 and shape-2 from inventory will be cleared automatically
     }
   }
   

   演示文稿的常见格式模式：

   • 标题幻灯片：粗体文本，有时居中
   • 幻灯片内的章节标题：粗体文本
   • 项目符号列表：每个项需要 "bullet": true, "level": 0
   • 正文文本：通常不需要特殊属性
   • 引用：可能有特殊的对齐或字体属性

7. 使用 replace.py 脚本应用替换

   python scripts/replace.py working.pptx replacement-text.json output.pptx
   

   该脚本将：

   • 首先使用 inventory.py 中的函数提取所有文本形状的清单
   • 校验替换 JSON 中的所有形状都存在于清单中
   • 清空清单中识别出的所有形状的文本
   • 仅将新文本应用到替换 JSON 中定义了 "paragraphs" 的形状
   • 通过应用 JSON 中的段落属性来保留格式
   • 自动处理项目符号、对齐、字体属性和颜色
   • 保存更新后的演示文稿

   示例校验错误：

   ERROR: Invalid shapes in replacement JSON:
     - Shape 'shape-99' not found on 'slide-0'. Available shapes: shape-0, shape-1, shape-4
     - Slide 'slide-999' not found in inventory
   

   ERROR: Replacement text made overflow worse in these shapes:
     - slide-0/shape-2: overflow worsened by 1.25" (was 0.00", now 1.25")
   

创建缩略图网格

要创建 PowerPoint 幻灯片的可视化缩略图网格，以便快速分析和参考：

python scripts/thumbnail.py template.pptx [output_prefix]

功能：

• 创建：thumbnails.jpg（对于大型演示文稿，则为 thumbnails-1.jpg、thumbnails-2.jpg 等）
• 默认：5 列，每个网格最多 30 张幻灯片（5×6）
• 自定义前缀：python scripts/thumbnail.py template.pptx my-grid
  • 注意：如果要将输出保存到特定目录，输出前缀应包含路径（例如 workspace/my-grid）
• 调整列数：--cols 4（范围：3-6，影响每个网格的幻灯片数量）
• 网格限制：3 列 = 12 张幻灯片/网格，4 列 = 20，5 列 = 30，6 列 = 42
• 幻灯片从零开始编号（Slide 0、Slide 1 等）

使用场景：

• 模板分析：快速了解幻灯片布局和设计模式
• 内容审查：整个演示文稿的可视化概览
• 导航参考：通过视觉外观查找特定幻灯片
• 质量检查：验证所有幻灯片是否格式正确

示例：

# Basic usage
python scripts/thumbnail.py presentation.pptx

# Combine options: custom name, columns
python scripts/thumbnail.py template.pptx analysis --cols 4

将幻灯片转换为图像

要通过可视化方式分析 PowerPoint 幻灯片，请使用两步流程将它们转换为图像：

1. 将 PPTX 转换为 PDF：

   soffice --headless --convert-to pdf template.pptx
   

2. 将 PDF 页面转换为 JPEG 图像：

   pdftoppm -jpeg -r 150 template.pdf slide
   

   这会创建 slide-1.jpg、slide-2.jpg 等文件。

选项：

• -r 150：将分辨率设置为 150 DPI（在质量和大小之间调整平衡）
• -jpeg：输出 JPEG 格式（如果更喜欢 PNG，可使用 -png）
• -f N：要转换的第一页（例如 -f 2 从第 2 页开始）
• -l N：要转换的最后一页（例如 -l 5 在第 5 页停止）
• slide：输出文件的前缀

特定范围的示例：

pdftoppm -jpeg -r 150 -f 2 -l 5 template.pdf slide  # Converts only pages 2-5

代码风格指南

IMPORTANT：为 PPTX 操作生成代码时：

• 编写简洁的代码
• 避免冗长的变量名和冗余操作
• 避免不必要的 print 语句

依赖项

必需的依赖项（应已安装）：

• markitdown：pip install "markitdown[pptx]"（用于从演示文稿中提取文本）
• pptxgenjs：npm install -g pptxgenjs（用于通过 html2pptx 创建演示文稿）
• playwright：npm install -g playwright（用于 html2pptx 中的 HTML 渲染）
• react-icons：npm install -g react-icons react react-dom（用于图标）
• sharp：npm install -g sharp（用于 SVG 栅格化和图像处理）
• LibreOffice：sudo apt-get install libreoffice（用于 PDF 转换）
• Poppler：sudo apt-get install poppler-utils（用于通过 pdftoppm 将 PDF 转换为图像）
• defusedxml：pip install defusedxml（用于安全的 XML 解析）