pptx

PPTX 的创建、编辑和分析

概述

根据需要创建、编辑或分析 .pptx 文件的内容。.pptx 文件本质上是一个 ZIP 归档，其中包含 XML 文件和其他资源。针对不同任务，有不同的工具和工作流可供使用。

重要：先阅读所有文档

开始任何演示文稿任务之前，请完整阅读所有相关文档文件，以了解完整工作流：

1. 创建新演示文稿：完整阅读 html2pptx.md 和 css.md
2. 编辑现有演示文稿：完整阅读 ooxml.md
3. 基于模板创建演示文稿：阅读本文档中的相关部分以及 css.md

阅读这些文件时，切勿设置任何范围限制。 开始之前充分了解完整的工作流、限制和最佳实践，对于制作高质量演示文稿至关重要。了解不全面会导致错误、样式不一致和视觉缺陷，进而需要返工。

阅读和分析内容

文本提取

如需只读取演示文稿的文本内容，请将文档转换为 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/public/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. 阅读文档：完整阅读 html2pptx.md 和 css.md（请参阅上文“重要：先阅读所有文档”部分）

2. 前置条件 - 提取 html2pptx 库：

   • 将库提取到脚本旁边：mkdir -p html2pptx && tar -xzf skills/public/pptx/html2pptx.tgz -C html2pptx
   • 这会创建一个 html2pptx/ 目录，其中包含库文件和 CLI 二进制文件

3. 规划演示文稿：遵循 html2pptx.md 的“设计理念”部分，确定：

   • 美学方向和大胆的设计选择
   • 配色方案（请参阅“创建配色方案”）
   • 字体排版策略
   • 编写详细的大纲，包含幻灯片布局和演讲者备注（每张幻灯片 1-3 句）

4. 设置 CSS 变量：在共享的 .css 文件中覆盖 CSS 变量，以设置颜色、字体排版和间距（请参阅 css.md 的“设计系统变量”）

5. 创建 HTML 幻灯片（16:9 尺寸为 960px × 540px）：遵循 html2pptx.md 中有关以下内容的说明：

   • 幻灯片布局区域（标题、内容、脚注）
   • 关键文本规则（正确的 HTML 标签）
   • 支持的元素和样式

6. 使用 html2pptx 库创建并运行 JavaScript 文件，将 HTML 幻灯片转换为 PowerPoint 并保存演示文稿

   • 运行命令：NODE_PATH="$(npm root -g)" node your-script.js 2>&1

   • 使用 html2pptx 函数处理每个 HTML 文件

   • 使用 PptxGenJS API 在占位区域添加图表和表格

   • 使用 pptx.writeFile() 保存演示文稿

   • **⚠️ 重要：**脚本必须遵循此示例结构。编写脚本前，请先逐步说明思路，确保正确使用 API。不要调用 pptx.addSlide。

   const pptxgen = require("pptxgenjs");
   const { html2pptx } = require("./html2pptx");
   
   // Create a new pptx presentation
   const pptx = new pptxgen();
   pptx.layout = "LAYOUT_16x9"; // Must match HTML body dimensions
   
   // Add an HTML-only slide
   await html2pptx("slide1.html", pptx);
   
   // Add a HTML slide with chart placeholders
   const { slide: slide2, placeholders } = await html2pptx("slide2.html", pptx);
   slide.addChart(pptx.charts.LINE, chartData, placeholders[0]);
   
   // Save the presentation
   await pptx.writeFile("output.pptx");
   

7. 视觉验证：将幻灯片转换为图像，并检查布局问题

   • 先将 PPTX 转换为 PDF：soffice --headless --convert-to pdf output.pptx
   • 然后将 PDF 转换为图像：pdftoppm -jpeg -r 150 output.pdf slide
     • 这会生成 slide-1.jpg、slide-2.jpg 等文件
   • 读取每个生成的图像文件，并仔细检查以下问题：
     • 文本裁切：文本被标题栏、形状或幻灯片边缘裁切
     • 文本重叠：文本与其他文本或形状重叠
     • 位置问题：内容过于靠近幻灯片边界或其他元素
     • 对比度问题：文本与背景之间的对比度不足
     • 对齐问题：元素之间未正确对齐
     • 视觉层次：重要内容是否得到了适当强调
   • **重要：交付给用户前，所有幻灯片都必须通过这些验证检查。**请勿跳过此步骤，也不要交付存在视觉缺陷的演示文稿。
   • 如果发现问题，请按以下优先顺序修复：
     1. 增大边距 - 为有问题的元素增加内边距或间距
     2. 调整字体大小 - 缩小文本以适应可用空间
     3. 彻底重新设计布局 - 如果以上方法无效，请重新设计幻灯片布局
   • 修改后重新生成演示文稿
   • 重复上述流程，直到所有幻灯片的视觉效果都正确

编辑现有 PowerPoint 演示文稿

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

工作流

1. 阅读文档：完整阅读 ooxml.md（请参阅上文“重要：先阅读所有文档”部分）
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，内容如下：

     # Template Inventory Analysis
     
     **幻灯片总数：[count]**
     **重要提示：幻灯片索引从 0 开始（第一页 = 0，最后一页 = count-1）**
     
     ## [Category Name]
     
     - 幻灯片 0：[可用时填写布局代码] - 描述/用途
     - 幻灯片 1：[布局代码] - 描述/用途
     - 幻灯片 2：[布局代码] - 描述/用途
       [... 必须逐一列出每张幻灯片及其索引 ...]
     

   • 使用缩略图网格：参照视觉缩略图，识别以下内容：

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

   • 下一步需要使用此清单文件来选择合适的模板

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

   • 查看第 2 步中整理的可用模板。
   • 为第一页选择引言或标题模板。应从靠前的模板中选择。
   • 为其他幻灯片选择安全的纯文本布局。
   • 关键：将布局结构与实际内容匹配：
     • 单栏布局：用于统一的叙述或单一主题
     • 双栏布局：仅在恰好有 2 个不同项目/概念时使用
     • 三栏布局：仅在恰好有 3 个不同项目/概念时使用
     • 图片 + 文本布局：仅在有实际图片要插入时使用
     • 引言布局：仅用于人物的真实引言（需注明出处），切勿用于强调
     • 切勿使用占位符数量多于可用内容数量的布局
     • 有 2 个项目时，避免强行放入三栏布局
     • 有 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，了解所有形状及其属性

   • 清单 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", // 取自第一个文本运行
               "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 文件 根据上一步的文本清单：

   • CRITICAL：首先确认清单中有哪些形状——仅引用实际存在的形状
   • VALIDATION：replace.py 脚本会验证替换 JSON 中的所有形状是否存在于清单中
     • 引用不存在的形状会产生错误，并显示可用形状
     • 引用不存在的幻灯片会产生错误，指出该幻灯片不存在
     • 脚本退出前会一次性显示所有验证错误
   • IMPORTANT：replace.py 脚本会在内部使用 inventory.py 来识别所有文本形状
   • 自动清除：除非为清单中的文本形状提供了「paragraphs」，否则所有文本形状都会被清除
   • 对需要内容的形状添加「paragraphs」字段（而不是「replacement_paragraphs」）
   • 替换 JSON 中未包含「paragraphs」的形状，其文本会自动清除
   • 带项目符号的段落会自动左对齐。避免在 "bullet": true 时设置 alignment 属性
   • 为占位符文本生成合适的替换内容
   • 根据形状大小确定合适的内容长度
   • CRITICAL：包含原始清单中的段落属性——不要只提供文本
   • IMPORTANT：当 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"
     • 替换脚本需要的是格式正确的段落，而不只是文本字符串
     • 重叠形状：优先选择默认字体大小更大或占位符类型更合适的形状
   • 将包含替换内容的更新后清单保存到 replacement-text.json
   • WARNING：不同的模板布局包含的形状数量不同——创建替换内容前务必检查实际清单

   显示正确格式的 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 张
• 幻灯片从 0 开始编号（幻灯片 0、幻灯片 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

代码风格指南

重要：为 PPTX 操作生成代码时：

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

依赖项

所需依赖项（应该已安装）：

• 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（用于 SVG 格式的图标）
• LibreOffice：用于 PDF 转换（视觉验证步骤所必需）
  • macOS：brew install --cask libreoffice
  • Linux：sudo apt-get install libreoffice
• Poppler：sudo apt-get install poppler-utils（用于通过 pdftoppm 将 PDF 转换为图像）
• defusedxml：pip install defusedxml（用于安全解析 XML）