补丁
通过三种方式修补现有 .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: {
children: [{ children: [{ text: "你好 {{name}}！" }] }],
},
},
},
],
},
],
});
// 修补模板
const result = await patchPresentation({
outputType: "nodebuffer",
data: templateBuffer,
placeholders: {
name: [{ text: "世界", bold: true, size: 24 }],
},
});
writeFileSync("output.pptx", result);
占位符
占位符名称用分隔符包裹（默认 {{ 和 }}），与幻灯片文本匹配。每个值是内联运行级内容，复用 generatePresentation 相同的 RunOptions 词汇表：单个 run、run 数组，或纯字符串简写。
默认保留原 run 的格式属性（字体、大小、颜色、加粗等）。你设置的任何属性（颜色、填充、字体、超链接等）都通过与 generatePresentation 相同的描述符序列化。
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: "已替换" },
},
},
],
},
},
},
});
追加的幻灯片经与生成相同的幻灯片序列化器处理，并接入 sldIdLst、演示文稿关系和 [Content_Types].xml。每张追加的幻灯片继承模板的第一个幻灯片布局 — 它无法引用模板中不存在的布局、母版或媒体。被替换的幻灯片保留其原有身份（sldId、rId 和关系）。
批注
向现有幻灯片追加批注，以 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, RunOptions | RunOptions[] | string> | — | 分隔符包裹的占位符名称 → 运行内容 |
findReplace | Record<string, RunOptions | RunOptions[] | string> | — | 字面查找字符串 → 运行内容（无分隔符） |
coreProperties | Partial<CorePropertiesOptions> | — | 核心元数据覆盖，与现有值合并 |
slides | { append?, replace? } | — | 追加幻灯片，或按 0-based 索引替换 |
comments | Record<number, SlideCommentOptions[]> | — | 按 0-based 索引追加幻灯片批注（与现有合并） |
keepOriginalStyles | boolean | true | 保留原始 run 格式属性 |
placeholderDelimiters | { start: string, end: string} | { start: "{{", end: "}}" } | 自定义占位符分隔符 |
提示
- PowerPoint 中跨分割运行的占位符会被库自动处理。
placeholders和findReplace共享同一引擎；可在一次调用中同时使用。- 扫描覆盖幻灯片、幻灯片母版、幻灯片版式和备注幻灯片 — 替换母版/版式中的文本会传播到所有依赖幻灯片。
- 补丁 run 引入的超链接会自动注册到每张幻灯片的关系部件中。