补丁修改 - Office Open

通过三种方式修补已有的 .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 条目、
    // 工作簿关系、工作表 part 及其 rels、content-type Override 的全部接线。
    remove: ["Report Draft"],
  },
});

共享字符串表会先从模板重建，因此追加和替换的工作表会在正确的偏移处继续索引字符串 — 现有的单元格引用保持有效。追加的工作表会接入 workbook.xml、工作簿关系和 [Content_Types].xml。追加行的单元格样式不受支持 — 只能引用模板中已存在的样式。

删除还会重编指向工作表列表的内容：作用域为被删工作表的 definedName 条目会被丢弃，存活条目的 localSheetId（以及工作簿视图的 activeTab）移位到删除后的索引。

#批注

向现有工作表追加单元格批注（备注），以工作表名为键。每条批注复用 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?, remove? }`	—	追加工作表、按名替换、或按名删除
`comments`	`Record<string, CommentOptions[]>`	—	按工作表名追加单元格批注（与现有合并）
`placeholderDelimiters`	`{ start: string, end: string}`	`{ start: "{{", end: "}}" }`	自定义占位符分隔符

#提示

所有工作表、共享字符串和打印页眉页脚中的占位符都会被替换。
替换值时会保留原始单元格的样式。
当占位符独占整个单元格时，number、boolean、Date 会成为真正的类型化单元格（而非字符串化副本）。
placeholders 和 findReplace 共享同一引擎；可在一次调用中同时使用。