补丁 - Office Open

通过三种方式修补现有 .pptx 模板：替换 {{占位符}} 标记、查找并替换字面文本，或覆盖文档元数据。

#patchPresentation

替换现有 .pptx 文件中的占位符：

import { patchPresentation, generatePresentation } from "@office-open/pptx";
import { writeFileSync } from "node:fs";

// 创建带占位符的模板
const templateBuffer = await generatePresentation({
  title: "补丁演示",
  slides: [
    {
      children: [
        {
          shape: {
            x: "2.1cm",
            y: "3.2cm",
            width: "19.1cm",
            height: "2.1cm",
            textBody: {
              paragraphs: [{ children: [{ text: "你好 {{name}}！" }] }],
            },
          },
        },
      ],
    },
  ],
});

// 修补模板
const result = await patchPresentation({
  outputType: "nodebuffer",
  data: templateBuffer,
  placeholders: {
    name: [{ text: "世界", bold: true, size: 24 }],
  },
});

writeFileSync("output.pptx", result);

#占位符

占位符名称用分隔符包裹（默认 {{ 和 }}），与幻灯片文本匹配。每个值是内联运行级内容，复用 generatePresentation 相同的 TextRunOptions 词汇表：单个 run、run 数组，或纯字符串简写。

默认保留原 run 的格式属性（字体、大小、颜色、加粗等）。你设置的任何属性（颜色、填充、字体、超链接等）都通过与 generatePresentation 相同的描述符序列化。

json

{
  "placeholders": {
    "title": [
      {
        "text": "你好 ",
        "bold": true
      },
      {
        "text": "世界",
        "fill": {
          "type": "solid",
          "color": "FF0000"
        }
      }
    ],
    "link": {
      "text": "点击",
      "hyperlink": {
        "url": "https://example.com"
      }
    },
    "plain": "纯文本"
  }
}

#查找与替换

替换字面文本，无需分隔符 — 键按字面值匹配。适用于模板的品牌更换或固定措辞更新：

const result = await patchPresentation({
  outputType: "nodebuffer",
  data: templateBuffer,
  findReplace: {
    "Acme Corp": [{ text: "Globex", bold: true }],
    Draft: "Final",
  },
});

#核心属性

覆盖文档元数据（docProps/core.xml）。值会与现有核心属性合并 — 只需提供要修改的字段：

const result = await patchPresentation({
  outputType: "nodebuffer",
  data: templateBuffer,
  coreProperties: { title: "季度评审", creator: "张三" },
});

#幻灯片

追加新幻灯片、按索引（0-based，sldIdLst 顺序）替换现有幻灯片、或删除幻灯片。每项复用 generatePresentation 完整的 SlideOptions 词汇：

const result = await patchPresentation({
  outputType: "nodebuffer",
  data: templateBuffer,
  slides: {
    append: [
      {
        children: [
          {
            shape: {
              x: "0.0cm",
              y: "0.0cm",
              width: "15.9cm",
              height: "10.6cm",
              textBody: { text: "新幻灯片" },
            },
          },
        ],
      },
    ],
    replace: {
      0: {
        children: [
          {
            shape: {
              x: "0.0cm",
              y: "0.0cm",
              width: "15.9cm",
              height: "10.6cm",
              textBody: { text: "已替换" },
            },
          },
        ],
      },
    },
    // 从 10 页模板中删掉附录页 — 删除会解除 sldIdLst 条目、
    // 演示文稿关系、幻灯片 part 及其 rels、content-type Override 的全部接线。
    remove: [1, 2],
  },
});

追加的幻灯片经与生成相同的幻灯片序列化器处理，并接入 sldIdLst、演示文稿关系和 [Content_Types].xml。每张追加的幻灯片继承模板的第一个幻灯片布局 — 它无法引用模板中不存在的布局、母版或媒体。被替换的幻灯片保留其原有身份（sldId、rId 和关系）。被删除的幻灯片会连同其备注页一起移除；共享部件（布局、媒体、图表）为剩余幻灯片保留。remove 的索引以进入补丁时的原始 deck 顺序为准 — 与 replace 的键同一原始顺序；删除在追加之后执行。

#批注

向现有幻灯片追加批注，以 0-based 幻灯片索引（sldIdLst 顺序）为键。每条批注复用 generatePresentation 的 SlideCommentOptions 词汇（见批注）。作者合并入 commentAuthors.xml（按名称去重，id 续编），每张幻灯片的批注合并入 ppt/comments/commentN.xml：

const result = await patchPresentation({
  outputType: "nodebuffer",
  data: templateBuffer,
  comments: {
    0: [{ author: "Alice", text: "审阅开篇", x: "2.6cm", y: "4.0cm" }],
    1: [{ author: "Bob", text: "在此添加图表", x: "2.6cm", y: "4.0cm" }],
  },
});

现有作者和批注会保留 — 新条目被追加并重新序列化。

#自定义分隔符

默认分隔符为 {{ 和 }}。使用 placeholderDelimiters 自定义：

await patchPresentation({
  outputType: "nodebuffer",
  data: templateBuffer,
  placeholders: { name: [{ text: "John" }] },
  placeholderDelimiters: { start: "<<", end: ">>" },
});

#选项

选项	类型	默认值	说明
`outputType`	`string`	—	输出格式（见导出页面）
`data`	`Buffer \| Uint8Array \| ...`	—	输入 .pptx 文件数据
`placeholders`	`Record<string, TextRunOptions \| TextRunOptions[] \| string>`	—	分隔符包裹的占位符名称 → 运行内容
`findReplace`	`Record<string, TextRunOptions \| TextRunOptions[] \| string>`	—	字面查找字符串 → 运行内容（无分隔符）
`coreProperties`	`Partial<CorePropertiesOptions>`	—	核心元数据覆盖，与现有值合并
`slides`	`{ append?, replace?, remove? }`	—	追加幻灯片、按索引替换、或按索引删除
`comments`	`Record<number, SlideCommentOptions[]>`	—	按 0-based 索引追加幻灯片批注（与现有合并）
`keepOriginalStyles`	`boolean`	`true`	保留原始 run 格式属性
`placeholderDelimiters`	`{ start: string, end: string}`	`{ start: "{{", end: "}}" }`	自定义占位符分隔符

#提示

PowerPoint 中跨分割运行的占位符会被库自动处理。
每个占位符的所有出现都会被替换，而非仅第一处 — 覆盖所有幻灯片、母版、版式和备注。
placeholders 和 findReplace 共享同一引擎；可在一次调用中同时使用。
扫描覆盖幻灯片、幻灯片母版、幻灯片版式和备注幻灯片 — 替换母版/版式中的文本会传播到所有依赖幻灯片。
补丁 run 引入的超链接会自动注册到每张幻灯片的关系部件中。