PPTX 创建、编辑和分析

概述

用户可能会要求您创建、编辑或分析 .pptx 文件的内容。.pptx 文件本质上是一个包含 XML 文件和其他资源的 ZIP 存档，您可以读取或编辑。您有不同的工具和工作流程可用于不同的任务。

读取和分析内容

文本提取

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

# 将文档转换为 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. 陈述您的方法：在编写代码之前解释您的设计选择

要求：

• ✅ 在编写代码之前陈述基于内容的设计方法
• ✅ 仅使用 Web 安全字体：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 创建并保存模板清单文件，包含：

     # 模板清单分析
     **总幻灯片数：[数量]**
     **重要提示：幻灯片从 0 开始索引（第一张幻灯片 = 0，最后一张幻灯片 = 数量-1）**
     
     ## [类别名称]
     - 幻灯片 0：[布局代码（如果可用）] - 描述/用途
     - 幻灯片 1：[布局代码] - 描述/用途
     - 幻灯片 2：[布局代码] - 描述/用途
     [... 必须单独列出每张幻灯片及其索引 ...]
     

   • 使用缩略图网格：参考视觉缩略图以识别：
     • 布局模式（标题幻灯片、内容布局、分节符）
     • 图像占位符位置和数量
     • 幻灯片组之间的设计一致性
     • 视觉层次和结构
   • 此清单文件是下一步选择适当模板所必需的

3. 基于模板清单创建演示文稿大纲：

   • 查看步骤 2 中的可用模板。
   • 为第一张幻灯片选择介绍或标题模板。这应该是第一批模板之一。
   • 为其他幻灯片选择安全的、基于文本的布局。
   • 关键：将布局结构与实际内容匹配：
     • 单列布局：用于统一叙述或单个主题
     • 两列布局：仅当您有恰好 2 个不同的项目/概念时使用
     • 三列布局：仅当您有恰好 3 个不同的项目/概念时使用
     • 图像 + 文本布局：仅当您有实际图像要插入时使用
     • 引用布局：仅用于来自人物的实际引用（带归属），绝不用于强调
     • 绝不使用占位符多于您拥有的内容的布局
     • 如果您有 2 个项目，不要强制它们进入 3 列布局
     • 如果您有 4+ 个项目，请考虑分成多张幻灯片或使用列表格式
   • 在选择布局之前计算您的实际内容片段
   • 验证所选布局中的每个占位符将填充有意义的内容
   • 选择一个选项，代表每个内容部分的最佳布局。
   • 使用利用可用设计的内容和模板映射保存 outline.md
   • 示例模板映射：

     # 要使用的模板幻灯片（从 0 开始索引）
     # 警告：验证索引是否在范围内！具有 73 张幻灯片的模板具有索引 0-72
     # 映射：大纲中的幻灯片编号 -> 模板幻灯片索引
     template_mapping = [
         0,   # 使用幻灯片 0（标题/封面）
         34,  # 使用幻灯片 34（B1：标题和正文）
         34,  # 再次使用幻灯片 34（为第二个 B1 复制）
         50,  # 使用幻灯片 50（E1：引用）
         54,  # 使用幻灯片 54（F2：结束 + 文本）
     ]
     

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": "段落文本",
                 // 可选属性（仅在非默认时包含）：
                 "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（以点为单位）（仅在设置时包含）
     • 颜色：RGB 的 color（例如，”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\": [
     {
       \"text\": \"新演示文稿标题文本\",
       \"alignment\": \"CENTER\",
       \"bold\": true
     },
     {
       \"text\": \"节标题\",
       \"bold\
     },
     {
       \"text\": \"第一个要点（不带项目符号）\",
       \"bullet\": true,
       ": 0
     },
     {
       \"text\": \"红色文本\",
       \"color\": \"FF0000\"
     },
     {
    \"text\": \"主题颜色文本\",
       \"theme_color\": \"DARK_1\"
     },
     {
       \"text\": \"没有特殊格式的段落文本\"
     }
   ]
   

   替换 JSON 中未列出的形状会自动清除：

   {
     \"slide-0\": {
       \"shape-0\": {
         \"paragraphs\": [...] // 此形状获得新文本
       }
       // 清单中的 shape-1 和 shape-2 将自动清除
     }
   }
   

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

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

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

   pythts/replace.py working.pptx replacement-text.json output.pptx
   

脚本将：

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

示例验证错误：

错误：替换 JSON 中的无效形状：
  - 在 'slide-0' 上找不到形状 'shape-99'。可用形状：shape-0、shape-1、shape-4
  - 在清单中找不到幻灯片 'slide-999'

错误：替换文本使这些形状的溢出变得更糟：
  - slide-0/shape-2：溢出恶化了 1.25\"（原为 0.00\"，现为 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
• 幻灯片从零开始索引（幻灯片 0、幻灯片 1 等）

用例：

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

示例：

# 基本用法
python scripts/thumbnail.py presentation.pptx

# 组合选项：自定义名称、列
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  # 仅转换第 2-5 页

代码风格指南

重要：为 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 解析）