补丁修改
通过三种方式修补已有的 .xlsx 模板：替换单元格中的 {{占位符}} 标记、查找并替换字面文本，或覆盖文档元数据。
patchWorkbook
替换已有 .xlsx 文件中的占位符：
import { patchWorkbook } from "@office-open/xlsx";
import { readFileSync, writeFileSync } from "node:fs";
const result = await patchWorkbook({
outputType: "nodebuffer",
data: readFileSync("template.xlsx"),
placeholders: {
name: "张三",
amount: 1500,
date: new Date("2024-12-31"),
},
});
writeFileSync("output.xlsx", result);
工作原理
修补器扫描每个工作表中匹配占位符模式（默认 {{key}}）的单元格，查找范围包括共享字符串表、内联字符串和打印页眉页脚。跨多个运行（因格式拆分）的占位符会被自动处理。
占位符值
每个占位符是普通标量 —— string、number、boolean 或 Date：
placeholders: {
name: "Alice", // 字符串
quantity: 42, // 数字
active: true, // 布尔值
deadline: new Date("2024-12-31"), // 日期
}
当占位符独占整个单元格内容时，修补会把单元格重写为对应类型化值：
| 值类型 | 结果单元格 |
|---|---|
string | 文本替换（单元格保持字符串） |
number | 数值单元格（<v>，无 t，默认数值） |
boolean | 布尔单元格（t="b"，<v>1/0） |
Date | 数值单元格，存放 Excel 序列日期 |
当占位符嵌在更大的文本中（如 总计: {{amount}}）时，值作为文本替换，单元格保持字符串。
查找与替换
替换字面文本，无需分隔符 — 键按字面值匹配。作用于单元格值和打印页眉页脚：
const result = await patchWorkbook({
outputType: "nodebuffer",
data: templateBuffer,
findReplace: {
"Acme Corp": "Globex Inc.",
Draft: "Final",
},
});
核心属性
覆盖文档元数据（docProps/core.xml），与现有值合并：
const result = await patchWorkbook({
outputType: "nodebuffer",
data: templateBuffer,
coreProperties: { title: "Q4 报告", creator: "张三" },
});
工作表
追加新工作表，或按工作表名替换现有工作表。每项复用 generateWorkbook 完整的 WorksheetOptions 词汇：
const result = await patchWorkbook({
outputType: "nodebuffer",
data: templateBuffer,
worksheets: {
append: [
{
name: "汇总",
rows: [{ cells: [{ reference: "A1", value: "追加的工作表" }] }],
},
],
replace: {
Sheet1: { rows: [{ cells: [{ reference: "A1", value: "已替换" }] }] },
},
},
});
共享字符串表会先从模板重建，因此追加和替换的工作表会在正确的偏移处继续索引字符串 — 现有的单元格引用保持有效。追加的工作表会接入 workbook.xml、工作簿关系和 [Content_Types].xml。追加行的单元格样式不受支持 — 只能引用模板中已存在的样式。
批注
向现有工作表追加单元格批注（备注），以工作表名为键。每条批注复用 generateWorkbook 的 CommentOptions 词汇（见）— cell、author 和 text：
const result = await patchWorkbook({
outputType: "nodebuffer",
data: templateBuffer,
comments: {
Report: [
{ cell: "B2", author: "Alice", text: "高于目标" },
{ cell: "B3", author: "Bob", text: "需跟进" },
],
},
});
工作表上的现有批注会保留 — 新批注被追加，作者被重新收集，当相关 part 为新建时才添加工作表关系、VML 绘图和 content-type 接线。
自定义分隔符
默认分隔符为 {{ 和 }}。可通过 placeholderDelimiters 修改：
await patchWorkbook({
outputType: "nodebuffer",
data: templateBuffer,
placeholders: { name: "John" },
placeholderDelimiters: { start: "<<", end: ">>" },
});
输出类型
outputType 参数控制返回类型：
outputType | 返回值 |
|---|---|
"nodebuffer" | Buffer |
"uint8array" | Uint8Array |
"arraybuffer" | ArrayBuffer |
"base64" | string |
"blob" | Blob |
"string" | string |
选项
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
outputType | string | — | 输出格式（见上表） |
data | Buffer | Uint8Array | ... | — | 输入 .xlsx 文件数据 |
placeholders | Record<string, ScalarValue> | — | 分隔符包裹的占位符 → 值（string | number | boolean | Date） |
findReplace | Record<string, ScalarValue> | — | 字面查找字符串 → 值（无分隔符） |
coreProperties | Partial<CorePropertiesOptions> | — | 核心元数据覆盖，与现有值合并 |
worksheets | { append?, replace? } | — | 追加工作表，或按工作表名替换 |
comments | Record<string, CommentOptions[]> | — | 按工作表名追加单元格批注（与现有合并） |
placeholderDelimiters | { start: string, end: string} | { start: "{{", end: "}}" } | 自定义占位符分隔符 |
提示
- 所有工作表、共享字符串和打印页眉页脚中的占位符都会被替换。
- 替换值时会保留原始单元格的样式。
- 当占位符独占整个单元格时，
number、boolean、Date会成为真正的类型化单元格（而非字符串化副本）。 placeholders和findReplace共享同一引擎；可在一次调用中同时使用。