XLSX
补丁修改
通过替换占位符修改已有的 .xlsx 文件
修补已有的 .xlsx 模板，将 {{placeholder}} 占位符替换为新的单元格值。
patchWorkbook
替换已有 .xlsx 文件中的占位符：
import { patchWorkbook } from "@office-open/xlsx";
import { readFileSync, writeFileSync } from "node:fs";
const result = await patchWorkbook({
outputType: "nodebuffer",
data: readFileSync("template.xlsx"),
patches: {
name: { value: "John Doe" },
amount: { value: 1500 },
date: { value: "2024-12-31" },
},
});
writeFileSync("output.xlsx", result);
工作原理
修补器会扫描每个工作表中所有单元格，查找匹配占位符模式（默认 {{key}}）的文本。找到后，将单元格值替换为修补内容。
跨多个运行（因格式拆分）的占位符会被自动处理。
修补值
每个修补项将单元格值替换为新值：
patches: {
name: { value: "Alice" }, // 字符串
quantity: { value: 42 }, // 数字
active: { value: true }, // 布尔值
deadline: { value: new Date("2024-12-31") }, // 日期
}
修补值的类型决定了输出中的单元格类型。
自定义分隔符
默认分隔符为 {{ 和 }}。可通过 placeholderDelimiters 修改：
await patchWorkbook({
outputType: "nodebuffer",
data: templateBuffer,
patches: { name: { value: "John" } },
placeholderDelimiters: { start: "<<", end: ">>" },
});
输出类型
outputType 参数控制返回类型：
outputType | 返回值 |
|---|---|
"nodebuffer" | Buffer |
"uint8array" | Uint8Array |
"arraybuffer" | ArrayBuffer |
"base64" | string |
"blob" | Blob |
"string" | string |
选项
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
outputType | string | — | 输出格式（见上表） |
data | Buffer | Uint8Array | ... | — | 输入 .xlsx 文件数据 |
patches | Record<string, IPatch> | — | 占位符名称到新值的映射 |
placeholderDelimiters | { start: string, end: string} | { {{, }} } | 自定义占位符分隔符 |
提示
- 占位符会在工作簿的所有工作表中被替换。
- 替换值时会保留原始单元格的样式。
- 在 Node.js 中使用
nodebuffer进行文件 I/O，在浏览器中使用blob进行下载。 - 修补值是普通值（不需要类实例）。