渲染一致性难保证
手写 HTML 模板与 Excel 设计对不齐,换浏览器 / 换 PDF 引擎样式就走样,反复调 CSS 仍难像素级还原。
报告单、票据、标签等固定模板要搬进后端批量生成 PDF,往往在渲染一致性、复杂元素拼接、国产打印链路与并发稳定性上翻车。
手写 HTML 模板与 Excel 设计对不齐,换浏览器 / 换 PDF 引擎样式就走样,反复调 CSS 仍难像素级还原。
Chromium 不写 /Rotate,WPS 打印预览 / Clodop 读不到方向标志,横向纸表现为「内容横向、纸张纵向」。
报告要嵌照片、条码、二维码、印章,手动定位与压缩易错、难维护,层级堆叠更是无从下手。
每个渲染标签页 +100MB 起步,无节制并发把宿主机 / 容器直接打到 OOM,服务被单个异常请求击穿。
Excel 单元格宽高在模板里就已定死,而实际文本长短千变万化;长内容装不下就撑破格子、被截断或挤到下一页,导致一份报告意外跨页、版式错乱。
小票纸等自定义尺寸被静默当成 A4 生成,版式全乱;ExcelJS 又不解析文件内的 paperWidth/Height。
从「像不像设计稿」「渲染准不准」「跑不跑得稳」「能不能扩展」四个维度,重构报表模板的 PDF 生成方式。点击卡片展开详情。
内置无头 Chrome,像素级还原

围绕「模板标记 → 数据注入 → 渲染打印」核心链路,提供标记替换、数字格式、页面适配、多页批量与生成 API 五大能力。
单元格写 ${字段|类型_参数} 即可,文本、图片、条形码、二维码四类内置标记两版通用(社区版 1.1.0 起内置富媒体),支持宽高 / 偏移 / 层级 / 透明度 / 默认值参数;水印为 Pro 专属。
作废 / 已审核叠章,宽度不足自动收敛换行,层级透明度可配
base64 / URL / 本地路径;社区按原图尺寸归一,Pro DPI 物理尺寸 + 压缩
barcode(code128) / qrcode,可配 zindex / opacity 堆叠
text 默认类型,单元格内局部加粗 / 斜体 / 字色自动继承

从在 Excel 写标记到拿到 PDF Buffer,每一步都由引擎自动完成,调用方只管传模板和数据。点击节点查看详情。
在 Excel 中排版、设样式、合并单元格,需要动态填充的格写 ${字段|类型_参数} 标记,页面设置一并保存,模板即设计稿。
字色 / 背景 / 局部富文本格式照搬
文本 / 图片 / 条码 / 二维码(水印 Pro)
纸张 / 方向 / 页边距 / 缩放
通过标记替换、格式自动继承、内置无头 Chrome 与生产级护栏,把传统「手写 HTML → 拼元素 → 调样式 → 导 PDF」的长链路压缩为「设计模板 → 注入数据」的短链路。
从依赖前端手写模板到业务在 Excel 自助设计,让报表 PDF 生成更高效、更一致、更可控。

文本 / 图片 / 条码 / 二维码四类内置标记两版通用,水印 Pro
百分比 / 货币 / 千分位 / 日期与 Excel 所见一致
像素级渲染一致,横向页自动补 /Rotate 标志
Pro 并发限流 + 内存准入守卫;社区版固定上限 + 单并发
标记格式为 ${字段|类型_参数},竖杠及其后可省略(省略按文本处理)。字段支持 a.b、a.0.b 点路径取嵌套 / 数组值,#数组.字段 用于明细行逐行递增(两版内置);文本、图片、条形码、二维码四类内置标记共用同一套参数体系,水印为 Pro 专属类型。
text默认类型,可省略竖杠。局部富文本格式自动继承。
${name} / ${name|text}imageimg 为别名;base64 / URL / 本地路径。社区按原图尺寸归一(@96DPI),Pro 按 DPI 物理尺寸 + 自动压缩。
${photo|image_w120_h40}barcodecode128 编码,值为要编码的文本,缺省宽 100 高 20。
${code|barcode_w200_h60}qrcode值为要编码的文本,可配 zindex / opacity 与其他元素堆叠。
${qr|qrcode_w80_h80}watermark浮在单元格上的文本层,作废 / 已审核叠章,字号自适应;社区版自定义 handler 可返回水印浮层。
${mark|watermark_zindex1_opacity0.3}图片 / 条码 / 二维码 / watermark 共用同一套层级与透明度规则;minsize / lineheight 随 Pro 单页自适应与水印生效。
w / h宽 / 高 px。缺省时社区按原图尺寸归一(@96DPI);Pro 按物理尺寸(像素÷DPI×96),只设一边另一边按宽高比。
ox / oy水平 / 垂直偏移 px,oy 可为负,用于精细定位浮层元素。
zindex层级:0 跟模板同层、负数在下方、正数在上方;设为非 0 后按纯浮层处理,不撑高所在行。
opacity不透明度 0~1(同 CSS);值 >1 时按百分数自动换算,旧写法无需改动。
minsize字号下限 pt:随 Pro 单页自适应生效,收敛后不低于该值;社区版不生效。
lineheightwatermark 专用(Pro):行高 pt,主要影响换行后的行间距,缺省按字体默认行高。
_默认: / _dft:标记末尾追加,字段缺值时生效,如 ${remark|text_默认:无}。
#数组.字段明细行语法,模板中逐行重复同一标记,每出现一次自动取数组下一项。
具名纸张两版直选;小票、标签等自定义纸张为 Pro 能力——优先从模板文件直读宽高,读不到再显式传参,绝不静默退成 A4。
option.pageSize 传 A3 / A4 / A5 / B4 / B5 / letter / legal 即按标准尺寸出纸,方向由 orientation 控制。
传 { width, height }(单位 mm)即可出任意尺寸,小票、标签、异形版面不受具名纸张限制。
第三方工具写入模板的 paperWidth / paperHeight 会绕过 ExcelJS 直接解包读取,无需显式传 pageSize。
支持 mm / cm / in / pt / pi / pc,无单位按 mm 处理;landscape 时反交换回纵向基准,语义与传参一致。
自定义 / 非标准代码读不到宽高时报错引导显式传参,绝不静默生成 A4;未写 paperSize 才按 Excel 内建默认兜底。
横向页自动补写 Excel/WPS 式 /Rotate 90,WPS 打印预览与 Clodop 能正确选到横向纸,可关闭。
一条命令安装,内置无头 Chrome 自动就绪;ESM / CJS 双模式消费,浏览器策略灵活,容器与小内存场景有专门护栏。
三层扩展点、两级注册(全局 use() / 调用级 option.plugins),自定义标记类型、字段解析器与模型后处理钩子,内部工具经 helpers 同源开放。
markerTypes 注册自定义类型,handler 签名 async (value, option, ctx)。取值链路已在 handler 之前自动完成,只管渲染;返回字符串 / images / watermarks,Pro 图片自动进入 sharp 压缩管线,社区按原图尺寸归一。
import { use, helpers } from 'xlsx2pdf'; use({ name: 'seal-plugin', markerTypes: { // 模板标记:stamp|seal_w100_h100 seal: async (value, option) => { if (!value) return null; // 空值清除标记 const buf = await helpers.getFileBuffer(value); return { images: [{ dataUrl: helpers.bufferToDataUrl(buf, 'png'), width: option.width || 100, height: option.height || 100, }], }; // Pro 自动走 sharp 压缩管线;社区按原图尺寸归一 }, }, });
handler 返回 images 自动进入 sharp 压缩管线(缩至显示尺寸 + JPEG 转换);社区版纯 JS 按原图尺寸归一,不压缩。
handler 抛异常不会中断生成,控制台打印 [engine] 错误后该标记按空值清除,其余照常。
自定义 handler 可通过 ctx.numFmt 读单元格格式、用 helpers.formatValue 复用同一格式化实现。
ctx.imageCache 按「类型|宽|高|值」缓存,自定义图片类 handler 可复用它避免重复下载 / 编码。
option.plugins 仅本次生成生效、同名覆盖全局,避免多租户并发下的插件污染。
1.0 起扩展点 API 视为稳定,破坏性变更走 major 版本,二开投入可长期沿用。
凡是「有固定 Excel 模板、需要在后端批量生成高保真 PDF」的业务,都可以用这个库搬上线。
检测报告、原始记录模板化,照片 / 条码 / 印章一键嵌入,批量出 PDF 支撑 CMA / CNAS 体系报告编制。
自定义纸张宽高直读模板文件,横向页自动补 /Rotate,WPS 打印预览与 Clodop 正确选到横向纸。
条形码 / 二维码标记两版内置,data 传数组逐页渲染(Pro),一份模板批量出成百上千张标签。
各类固定格式申报表、统计表模板化,数字格式自动继承,产出与 Excel 所见一致的规范 PDF。
watermark 文本水印浮层,作废 / 已审核 / 机密叠章,字号自适应、层级可置于模板上下方。
Node 服务批量生成,Pro 并发限流 + 内存准入守卫 + 参数化规模守卫,负载下始终为其他服务保留余量;社区版固定上限 + 单并发。
社区版以 Apache-2.0 开源免费,完整提供「模板标记 → HTML → PDF」核心链路,图片 / 条码 / 二维码富媒体标记与明细行内置,三层扩展机制,单份图文码报告可独立走通, 不是功能阉割的试用版;Pro 商业授权面向高要求生产场景,叠加专有保真、水印与图片压缩、批量出单与生产护栏, 按产品买断、随产品分发免版税。两版扩展同源同契约,插件与自定义标记一次编写、两版通用。
Apache-2.0 许可,商用自由。公开 npm 安装,5 分钟跑通「Excel 模板 → 高保真 PDF」核心链路,单份图文码报告可独立走通,适合评估验证与轻量单页出单。
按产品买断授权,随产品分发免版税。在社区版之上叠加专有保真、水印与图片压缩、批量出单与生产护栏,私有 npm 源授权交付,含 SLA 工单与专属群支持。
| 能力 | 社区版开源 Apache-2.0 · npm xlsx2pdf | Pro 商业版买断授权 · @krstation/xlsx2pdf-pro |
|---|---|---|
| 核心链路 · 双版同源 | ||
| excel2pdf / excel2html 核心链路 | ✓ | ✓ |
| text 标记 · 默认值 · 嵌套点路径取值 | ✓ | ✓ |
| 同格多标记混排 · 段级富文本继承 | ✓ | ✓另含段级独立 minsize |
| 样式保真合并格 / 字体 / 字色 / 背景 / 边框 / 富文本 | ✓ | ✓ |
| numFmt 数字格式自动继承 | ✓ | ✓ |
| 标准纸张 7 种 + 方向 + 边距 | ✓ | ✓ |
| 内置 Chrome 自动安装 / 外部浏览器复用 | ✓ | ✓ |
| ESM / CJS 双产物 + TypeScript 类型 | ✓ | ✓ |
| image / barcode / qrcode 富媒体标记本地路径 / URL / base64,bwip-js 生成码图 | ✓1.1.0 起内置,纯 JS 尺寸归一(@96DPI),不压缩 | ✓sharp 压缩 + DPI 感知物理尺寸 |
| 浮层参数 w/h/ox/oy/zindex/opacity层级堆叠 / 透明度 / 偏移定位 | ✓ | ✓ |
| #数组.字段 明细行索引映射逐行重复取数组下一项,行数由模板定 | ✓1.2.0 起内置 | ✓ |
| 三层扩展点 + 两级注册 + 自定义标记语法 | ✓helpers 7 件(含 generateCode / bufferToDataUrl) | ✓同机制 + watermark 内置类型 + optimizeImage(8 件) |
| 模板规模守卫文件体积 / 单元格数上限 | ✓固定上限,不可配 | ✓可参数化调整 |
| 保真与页面 · Pro 核心付费墙 | ||
| 列宽换算 | ◐公开公式近似 | ✓精确换算 + fontGuard 字体守卫 |
| 内容超页处理 | ◐Chrome 原生分页,可能截断 / 意外跨页 | ✓fitToPage 单页自适应 + minFontSize,超页不裁剪 |
| 自定义纸张{width,height} 传参 / 文件内宽高直读 / 单位换算 | — | ✓mm/cm/in/pt 换算,小票标签纸 |
| scale 1~400 精确缩放 | — | ✓ |
| pageRotate 国产打印链路适配 | — | ✓/Rotate 90,WPS / Clodop 正确选纸 |
| 富媒体增强与批量 · Pro | ||
| 图片自动压缩 + DPI 物理尺寸sharp 缩至显示尺寸 + JPEG 转换 | —纯 JS 尺寸归一,不压缩 | ✓高 DPI 图片自动缩小 |
| watermark 文本水印作废 / 已审核叠章,字号自适应 | —自定义 handler 可返回水印浮层 | ✓zIndex / opacity 堆叠,minsize / lineheight |
| autoInsertImage 无标记格自动插图 | — | ✓ |
| data 数组多页批量每元素渲染一页 | —单记录 + #明细行,数组传参报引导错 | ✓一份模板出百单 |
| 生产与服务 | ||
| maxConcurrency 并发限流 | —固定单并发,超限排队 | ✓标签页限流排队 |
| memoryGuard 内存准入守卫 | — | ✓cgroup / 宿主机探测 + 排队 |
| 技术支持 | 社区 issue | ✓SLA 工单 + 专属群 + 免费 POC |
| 授权方式 | Apache-2.0,商用自由 | 商业 EULA,按产品买断、随产品分发免版税 |
单个产品集成,小团队起步
多产品矩阵 / 私有化部署团队
平台厂商深度集成 / 源码可控诉求
提供 3 个真实业务模板,48 小时内出具基准对比报告(列宽 / 超页 / 富媒体 / 批量),并可申请 30 天 Pro 评估授权。先验证效果,再谈采购。
一条命令跑通开源核心链路,图文码单份报告直接生产可用;需要精确保真、水印压缩、批量出单与生产护栏时,Pro 买断授权随产品分发免版税。