pptx-generator

PPTX 生成器

何时使用此技能

在以下情况下使用此技能：

• 根据数据或规范以编程方式创建演示文稿
• 在保留企业样式的同时，用动态内容填充品牌模板
• 提取现有 PPTX 文件中的文本和结构以供分析
• 合并来自获批模板库的幻灯片
• 自动化演示文稿生成工作流

在以下情况下不要使用此技能：

• 用户想要打开或查看演示文稿（请使用原生 PowerPoint 或查看器）
• 需要复杂动画或转场（支持有限）
• 处理较旧的 .ppt 格式（仅支持 PPTX）

前提条件

• 已安装 Deno（https://deno.land/）
• 用于基于模板执行操作的输入 PPTX 文件
• 用于从零开始生成的 JSON 规范

快速入门

两种操作模式

1. 模板模式：修改现有品牌模板

   • 分析并替换：查找 {{PLACEHOLDERS}} 并替换为内容
   • 幻灯片库：从模板库中选择并合并幻灯片

2. 从零开始模式：使用 JSON 规范创建演示文稿

说明

模式 1：基于模板生成

步骤 1a：分析模板

提取文本清单，以了解可以替换的内容：

deno run --allow-read scripts/analyze-template.ts corporate-template.pptx > inventory.json

输出（inventory.json）：

{
  "filename": "corporate-template.pptx",
  "slideCount": 10,
  "textElements": [
    {
      "slideNumber": 1,
      "shapeId": "shape-2",
      "shapeName": "Title 1",
      "placeholderType": "ctrTitle",
      "position": { "x": 1.5, "y": 2.0, "w": 7.0, "h": 1.2 },
      "paragraphs": [
        { "text": "{{TITLE}}", "fontSize": 44, "bold": true }
      ]
    }
  ]
}

步骤 1b：创建替换规范

创建 replacements.json：

{
  "textReplacements": [
    { "tag": "{{TITLE}}", "value": "Q4 2024 Results" },
    { "tag": "{{SUBTITLE}}", "value": "Financial Overview" },
    { "tag": "{{DATE}}", "value": "December 2024" },
    { "tag": "{{AUTHOR}}", "value": "Finance Team", "slideNumbers": [1] }
  ]
}

步骤 1c：生成输出

deno run --allow-read --allow-write scripts/generate-from-template.ts \
  corporate-template.pptx replacements.json output.pptx

模式 1（替代方案）：幻灯片库

步骤 2a：预览模板幻灯片

获取可用幻灯片的信息：

deno run --allow-read scripts/generate-thumbnails.ts slide-library.pptx

如需视觉预览，请提取缩略图：

deno run --allow-read --allow-write scripts/generate-thumbnails.ts \
  slide-library.pptx --extract-thumb --output-dir ./previews

步骤 2b：选择并合并幻灯片

创建 selections.json：

{
  "slideSelections": [
    { "slideNumber": 1 },
    { "slideNumber": 5 },
    { "slideNumber": 12 },
    { "slideNumber": 3 }
  ],
  "textReplacements": [
    { "tag": "{{TITLE}}", "value": "Custom Presentation" }
  ]
}

步骤 2c：生成合并后的演示文稿

deno run --allow-read --allow-write scripts/generate-from-template.ts \
  slide-library.pptx selections.json custom-deck.pptx

模式 2：从零开始生成

步骤 3a：创建规范

创建 spec.json：

{
  "title": "Product Launch 2025",
  "author": "Marketing Team",
  "slides": [
    {
      "background": { "color": "003366" },
      "elements": [
        {
          "type": "text",
          "x": 1, "y": 2.5, "w": 8, "h": 1.5,
          "options": {
            "text": "Product Launch 2025",
            "fontSize": 44,
            "bold": true,
            "color": "FFFFFF",
            "align": "center"
          }
        },
        {
          "type": "text",
          "x": 1, "y": 4, "w": 8, "h": 0.5,
          "options": {
            "text": "Revolutionizing the Industry",
            "fontSize": 24,
            "color": "CCCCCC",
            "align": "center"
          }
        }
      ]
    },
    {
      "elements": [
        {
          "type": "text",
          "x": 0.5, "y": 0.5, "w": 9, "h": 0.7,
          "options": {
            "text": "Key Features",
            "fontSize": 32,
            "bold": true,
            "color": "003366"
          }
        },
        {
          "type": "table",
          "x": 0.5, "y": 1.5, "w": 9, "h": 3,
          "options": {
            "rows": [
              ["Feature", "Description", "Benefit"],
              ["Speed", "2x faster processing", "Save time"],
              ["Quality", "HD output", "Better results"],
              ["Integration", "Works with existing tools", "Easy adoption"]
            ],
            "border": { "pt": 1, "color": "CCCCCC" }
          }
        }
      ]
    }
  ]
}

步骤 3b：生成演示文稿

deno run --allow-read --allow-write scripts/generate-scratch.ts spec.json output.pptx

示例

示例 1：企业季度报告

场景：根据品牌模板生成季度报告。

步骤：

# 1. Analyze template for replaceable content
deno run --allow-read scripts/analyze-template.ts quarterly-template.pptx --pretty

# 2. Create replacements.json with Q4 data
# 3. Generate report
deno run --allow-read --allow-write scripts/generate-from-template.ts \
  quarterly-template.pptx replacements.json Q4-2024-Report.pptx

示例 2：使用幻灯片库创建定制推介演示文稿

场景：为特定客户的推介选择并合并获批幻灯片。

步骤：

# 1. View available slides
deno run --allow-read scripts/generate-thumbnails.ts pitch-library.pptx

# 2. Create selections.json picking slides 1, 3, 7, 12, 15
# 3. Generate custom deck
deno run --allow-read --allow-write scripts/generate-from-template.ts \
  pitch-library.pptx selections.json acme-pitch.pptx

示例 3：数据驱动的演示文稿

场景：根据 JSON 数据（例如 API 响应）生成演示文稿。

步骤：

# 1. Transform your data into spec.json format
# 2. Generate presentation
deno run --allow-read --allow-write scripts/generate-scratch.ts data-spec.json report.pptx

脚本参考

脚本	用途	权限
analyze-template.ts	从 PPTX 提取文本清单	--allow-read
generate-thumbnails.ts	获取幻灯片信息并提取预览图	--allow-read --allow-write
generate-from-template.ts	修改模板（替换／合并）	--allow-read --allow-write
generate-scratch.ts	根据 JSON 规范创建 PPTX	--allow-read --allow-write

元素类型（从零开始模式）

类型	描述	关键选项
text	文本框	text、fontSize、bold、color、align
image	来自文件或 base64 的图像	path、data、sizing
table	数据表格	rows、colW、border、fill
shape	几何形状	type、fill、line、text
chart	图表	type、data、title、showLegend

常见问题及解决方案

问题：文本未被替换

症状：输出的 PPTX 仍包含 {{PLACEHOLDER}} 标签。

解决方案：

1. 运行 analyze-template.ts，确认标签的准确文本
2. 标签可能被拆分到多个 XML 文本片段中；请确保模板中的标签位于单个文本片段内
3. 检查 replacements 中的 slideNumbers 筛选条件

问题：幻灯片顺序不正确

症状：合并后幻灯片的顺序有误。

解决方案：

• 幻灯片会按照 slideSelections 中指定的顺序添加
• 确认幻灯片编号与原始模板一致（从 1 开始）

问题：图片未显示

症状：输出中的图片元素为空白。

解决方案：

1. 使用绝对路径或相对于 spec.json 位置的路径
2. 确认图片文件存在且可读取
3. 检查支持的格式：PNG、JPEG、GIF

OOXML 占位符继承（高级）

了解 PowerPoint 的 OOXML 格式如何处理占位符，对模板开发至关重要。

继承链

PowerPoint 使用分层继承模型：

Theme → Slide Master → Slide Layout → Slide

• 主题：定义颜色、字体和效果
• 幻灯片母版：定义占位符的默认位置和格式（包括项目符号）
• 幻灯片版式：针对特定版式类型（例如标题幻灯片、内容）覆盖母版设置
• 幻灯片：包含实际内容，并继承版式的格式

关键原则

1. 文本内容不会继承：幻灯片必须包含自己的文本内容。版式中的 {{placeholder}} 文本不会自动出现在使用该版式的幻灯片上。

2. 文本格式可以继承：当幻灯片形状包含空的 <a:lstStyle/> 时，会从版式的 <a:lstStyle> 继承格式（颜色、大小、项目符号）。

3. 占位符链接：幻灯片通过 <p:ph type="..." idx="..."/> 链接到版式。type（例如 "title"、"body"、"ctrTitle"）和 idx 必须匹配。

4. 禁止项目符号：若要阻止占位符使用通常会从母版 bodyStyle 继承的项目符号，请在版式的 lstStyle 中添加 <a:buNone/>。

定义可继承的格式

在版式占位符中，应在 <a:lstStyle>（可继承）而非 <a:rPr>（仅适用于文本运行）中定义颜色：

<p:txBody>
  <a:lstStyle>
    <a:lvl1pPr algn="ctr">
      <a:buNone/>  
      <a:defRPr sz="4400" b="1">
        <a:solidFill><a:srgbClr val="FFFFFF"/></a:solidFill>
      </a:defRPr>
    </a:lvl1pPr>
  </a:lstStyle>
  <a:p>
    <a:r><a:rPr lang="en-US"/><a:t>{{placeholder}}</a:t></a:r>
  </a:p>
</p:txBody>

幻灯片形状结构

若要让幻灯片正确继承版式设置：

<p:sp>
  <p:nvSpPr>
    <p:cNvPr id="2" name="title 2"/>
    <p:cNvSpPr><a:spLocks noGrp="1"/></p:cNvSpPr>
    <p:nvPr>
      <p:ph type="ctrTitle"/>  
    </p:nvPr>
  </p:nvSpPr>
  <p:spPr/>  
  <p:txBody>
    <a:bodyPr/>
    <a:lstStyle/>  
    <a:p>
      <a:r>
        <a:rPr lang="en-US"/>  
        <a:t>{{placeholder}}</a:t>  
      </a:r>
    </a:p>
  </p:txBody>
</p:sp>

常见问题

问题	原因	解决方案
文本显示为黑色而不是白色	颜色定义在 <a:rPr> 中，而不是 <a:lstStyle> 中	将颜色移至版式 <a:lstStyle> 中的 <a:defRPr>
出现不需要的项目符号	母版的 bodyStyle 包含项目符号，而版式未覆盖	在版式的 <a:lvl1pPr> 中添加 <a:buNone/>
占位符文本未显示	文本只在版式中，不在幻灯片中	在幻灯片的 <p:txBody> 中添加文本内容
格式未生效	幻灯片包含显式格式	使用空的 <a:lstStyle/> 和 <a:rPr lang="en-US"/>

参考：占位符类型

类型	用途
ctrTitle	居中标题（标题幻灯片）
title	标准标题
subTitle	副标题
body	内容区域（多个占位符时使用 idx）
pic	图片占位符
dt	日期/时间
ftr	页脚
sldNum	幻灯片编号

局限性

• 无法渲染幻灯片：无法直接将幻灯片渲染为图片（可使用 LibreOffice）
• 动画支持有限：仅在 scratch 模式下支持基本动画
• 无法编辑母版幻灯片：模板模式会保留母版，但不会修改母版
• 仅支持 PPTX：不支持旧版 .ppt 格式
• 文本运行拆分：模板中的复杂格式可能会导致标签被拆分到多个 XML 元素中

相关技能

• pdf-generator：用于创建 PDF 文档，而非演示文稿
• docx-generator：用于创建 Word 文档
• xlsx-generator：用于创建 Excel 电子表格