jsPDF与pdfmake对比:前端生成PDF该选哪个库
深入对比前端两大主流PDF生成库jsPDF与pdfmake:从命令式坐标与声明式文档流的设计哲学、中文字体配置与打包、多页自动分页与复杂表格支持,到实际业务选型决策指南。
在前端纯客户端生成与下载 PDF 文件时,jsPDF 与 pdfmake 是最常被提及的两个主流 JavaScript 库。两者的核心差异并不在于能否导出文件,而在于排版思维与底层渲染范式:如果你的业务场景是单页固定版面、绝对位置打标,或者已有成型的 HTML 页面需要截图转 PDF,应首选 jsPDF;如果你的业务场景是包含多页长文本、需要自动跨页断行、包含复杂多行表格以及统一动态页码的业务报告或对账单,则应首选 pdfmake。理解这两个库的底层机制与适用边界,可以避免在项目开发中后期遭遇难以逾越的排版瓶颈。
一、设计哲学与编程范式差异:命令式画板 vs 声明式文档树
选择这两个库的第一个决定性维度是代码编写方式。jsPDF 采用命令式画板(Canvas-like Imperative)模式,开发者需要像在画布上绘图一样,精准指定每一个图元(文字、线段、矩形、图片)的绝对 X 轴与 Y 轴物理坐标;而 pdfmake 采用声明式文档定义(Declarative Document Definition)模式,开发者通过一个嵌套的 JSON 对象描述文档的逻辑层次,排版与断页由 pdfmake 内部的排版引擎自动测算并流式展开。
1. jsPDF 代码编写方式:手动控制物理坐标
在 jsPDF 中,每打印一行文本或绘制一个元素,都需要明确传入定位坐标。如果下一行内容由后端接口动态返回,开发者必须自行测量字体高度与行距,并手动递增 Y 轴偏移量:
import { jsPDF } from 'jspdf';
const doc = new jsPDF({ orientation: 'p', unit: 'mm', format: 'a4' });
// 设置字体大小与内容,必须提供确切的 X, Y 坐标 (单位: mm)
doc.setFontSize(16);
doc.text('结算凭证单据', 20, 25);
doc.setFontSize(10);
doc.text('客户名称:北京科技有限公司', 20, 35);
doc.text('流水单号:TX20261118001', 20, 42);
// 绘制分割线:必须计算起止点坐标
doc.setLineWidth(0.5);
doc.line(20, 46, 190, 46);
// 触发浏览器直接下载
doc.save('receipt.pdf');
2. pdfmake 代码编写方式:结构化数据声明
与 jsPDF 逐行计算坐标不同,pdfmake 的核心是编写 docDefinition 配置对象。文本会自动根据容器宽度折行,后续内容会自动往下推挤,无需关心上一行究竟占用了多少毫米:
import pdfMake from 'pdfmake/build/pdfmake';
const docDefinition = {
pageSize: 'A4',
pageMargins: [40, 60, 40, 60],
content: [
{ text: '结算凭证单据', fontSize: 16, bold: true, margin: [0, 0, 0, 10] },
{
columns: [
{ text: '客户名称:北京科技有限公司', width: '*' },
{ text: '流水单号:TX20261118001', width: 'auto' }
],
margin: [0, 0, 0, 8]
},
// 原生下划线或线条只需定义 canvas 图元,或直接利用 border
{ canvas: [{ type: 'line', x1: 0, y1: 0, x2: 515, y2: 0, lineWidth: 0.5 }] }
]
};
// 编译并下载
pdfMake.createPdf(docDefinition).download('receipt.pdf');
yOffset += lineHeight; if (yOffset > pageHeight) doc.addPage(); 的胶水代码,维护负担成倍上升。
二、中文字体配置与引入流程对比
在前端生成 PDF 时,新手最常遇到的问题就是导出中文出现乱码或空白黑块。由于 PDF 规范自带的标准 14 种核心字体(如 Helvetica、Times-Roman、Courier)只涵盖西文字符集,无论是 jsPDF 还是 pdfmake,在未额外注入中文字体前均无法正确渲染中文。两者的中文字体集成流程均遵循“获取字体 -> 转为二进制/Base64 -> 注册到引擎 -> 调用样式”的四步闭环,但在具体实现方式上有所区别。
1. 字体文件的预处理(必须先进行体积裁剪)
一份完整的中文字体(例如思源黑体 SourceHanSansSC-Regular.ttf)原始体积通常在 15MB 到 25MB 之间。如果直接把几十兆的字体打包进前端 bundle,会导致首屏加载白屏或内存溢出。因此,无论选用哪个库,都必须先对字体进行子集裁剪:
- 全量中文需求:提取常用《现代汉语常用字表》3500 字,压缩后的 TTF 体积大约在 1.2MB ~ 2MB 左右。
- 特定业务凭证:使用
font-spider(字蛛)按业务模板文字定向裁剪,字体体积可压缩至 100KB 以内。 - 格式规范:两库均要求标准的 TrueType (.ttf) 格式,不可直接注入 WOFF2 或 OTF 格式。
2. jsPDF 中文字体注册完整代码示例
在 jsPDF 中,先将 TTF 文件转为 Base64 编码字符串,随后使用虚拟文件系统方法 addFileToVFS 载入,再通过 addFont 设置字体别名与字重:
import { jsPDF } from 'jspdf';
// 假设 base64FontString 为裁剪后的字体 Base64 串
import { base64FontString } from './my-chinese-font.base64.js';
const doc = new jsPDF();
// 1. 将字体写入 jsPDF 虚拟文件系统
doc.addFileToVFS('SimHei.ttf', base64FontString);
// 2. 注册字体到引擎:文件名、字体名称别名、字重
doc.addFont('SimHei.ttf', 'SimHei', 'normal');
// 3. 切换字体并输出中文
doc.setFont('SimHei');
doc.setFontSize(14);
doc.text('你好,这是通过 jsPDF 输出的中文字符', 20, 30);
doc.save('chinese-jspdf.pdf');
3. pdfmake 中文字体注册完整代码示例
pdfmake 采用统一的全局 pdfMake.vfs 虚拟文件系统与 pdfMake.fonts 字典配置。配置完成后,在 defaultStyle 中指定字体,全局所有文本节点均会自动应用该字体,无需逐处调用:
import pdfMake from 'pdfmake/build/pdfmake';
import { base64FontString } from './my-chinese-font.base64.js';
// 1. 注册到虚拟文件系统
pdfMake.vfs = pdfMake.vfs || {};
pdfMake.vfs['SourceHanSansSC-Regular.ttf'] = base64FontString;
// 2. 定义字体族字典(支持分别定义 normal, bold, italics 等)
pdfMake.fonts = {
SourceHanSans: {
normal: 'SourceHanSansSC-Regular.ttf',
bold: 'SourceHanSansSC-Regular.ttf' // 若未准备单独粗体,可回退到 regular
}
};
// 3. 在文档定义中全局生效
const docDefinition = {
content: [
{ text: '你好,这是通过 pdfmake 声明式渲染的中文报表', fontSize: 14 }
],
defaultStyle: {
font: 'SourceHanSans'
}
};
pdfMake.createPdf(docDefinition).download('chinese-pdfmake.pdf');
fetch('/fonts/font.ttf') 异步拉取二进制流,转成 ArrayBuffer 后载入,从而避免污染主应用的初始加载体积。
三、复杂版面与多页排版能力实战对照
对于工业级前端 PDF 导出项目,单页居中打印几行文字往往不是难点,跨页长表格、动态页眉页脚、总页码计算以及网页现有 DOM 还原才是检验工具上限的关键指标。
1. 跨页数据表格的处理
jsPDF 核心库本身不具备表格能力。在原生 jsPDF 中画一个 10 行 3 列的表格,需要用循环调用 doc.rect() 画边框,并手动计算每格的 X, Y 偏移。为了应对表格,社区普遍采用 jspdf-autotable 插件。虽然该插件提供了自动分页和表头重复功能,但它脱离了 jsPDF 本身命令式风格,语法形态与主库产生割裂。
pdfmake 原生将表格作为一等公民对待。它的表格语法极其完善,支持 headerRows: 1(当表格跨越多页时,第二页顶部自动重新绘制表头)、widths: ['30%', '*', 'auto'] 自适应列宽,以及原生单元格 rowSpan 与 colSpan:
// pdfmake 声明跨页表格核心属性
const tableContent = {
table: {
headerRows: 1,
widths: [80, '*', 100],
body: [
[{ text: 'ID', bold: true }, { text: '项目名称', bold: true }, { text: '金额 (元)', bold: true }],
// 即使 body 包含 500 行数据,pdfmake 排版引擎也会在页尾自动整齐截断并换页
...dataSource.map(item => [item.id, item.name, item.amount])
]
}
};
2. 页眉、页脚与动态“第 X 页 / 共 Y 页”
在正式的报表或商业合同中,每一页的右下角通常需要打印“第 3 页,共 12 页”。在 jsPDF 中,因为它是即时绘制写入的,当你在绘制第 1 页页脚时,根本无法预知由于后续文字动态扩展整份文档最终会有多少页。要实现总页码,必须在整篇文档绘制完毕后,通过 doc.internal.getNumberOfPages() 获取总数,再编写 for (let i = 1; i <= total; i++) { doc.setPage(i); doc.text(...); } 进行全量页面后置“盖章”。
而在 pdfmake 中,引擎采用先虚拟排版、后输出渲染的双阶段机制,天然提供了动态页脚回调:
const docDefinition = {
content: [ /* 动态文档内容 */ ],
footer: function(currentPage, pageCount) {
return {
text: `第 ${currentPage} 页 / 共 ${pageCount} 页`,
alignment: 'center',
fontSize: 9,
margin: [0, 10, 0, 0]
};
}
};
3. HTML/DOM 节点转 PDF(所见即所得)
如果现有前端页面已经通过 Vue / React / CSS 排布好了一个复杂的看板、大屏或订单详情,产品经理要求“把页面原样导出一份 PDF”,此时 jsPDF 拥有绝对优势。jsPDF 拥有极其成熟的 html2canvas + jsPDF 组合方案,甚至内置了基于 html2canvas 的 doc.html(element, callback) 方法,能够将 DOM 树光栅化为高清位图或切片后置入 PDF,无需重新手写任何排版代码。
相反,pdfmake 并不识别浏览器 DOM。虽然有第三方库 html-to-pdfmake 可以将简单的 HTML 字符串解析成 pdfmake 的 JSON 对象,但它对 Flex 布局、复杂 CSS3 样式、伪元素、阴影等现代 CSS 特性支持非常有限,转换出来的排版经常发生错位变形。
四、工程化维度与综合指标对照
在引入项目构建时,除了语法 API,还需要权衡包体积、依赖复杂度以及运行时的性能表现:
| 特性 / 评估维度 | jsPDF (v2.5+) | pdfmake (v0.2+) |
|---|---|---|
| 核心设计哲学 | 命令式 (Imperative)、直接操作 Canvas 坐标 | 声明式 (Declarative)、文档流排版引擎 |
| 核心包体积 (Gzipped) | 约 80KB ~ 120KB(不含字体) | 约 180KB ~ 250KB(不含字体) |
| 多页自动断行/换页 | 较弱,需手动计算 Y 轴或借助外部插件 | 极强,内置虚拟测量与自适应分页机制 |
| 表格支持 | 需依赖外部插件(jspdf-autotable) | 内置原生支持(支持跨页表头重复、列宽自适应) |
| 动态页眉页脚与总页码 | 需在文档生成后手动遍历页面打补丁 | 原生声明式支持,通过回调直接获取总页数 |
| 现有 DOM / HTML 导出 | 生态极佳(与 html2canvas 深度整合) | 支持较弱,需转换中间 JSON,CSS 丢失较多 |
| 中文字体配置成本 | 需手动将 TTF 转 Base64 并调用 addFont | 需注入 VFS 并在全局 fonts 字典中定义 |
五、前端选型决策指南与适用场景
结合上述核心技术差异,在面临前端 PDF 生成需求时,可以通过以下逻辑树快速决策:
1. 坚决推荐选择 jsPDF 的场景
- 需求已有成型的前端界面:页面本身已经用 CSS 样式精细调整完毕(例如 ECharts 可视化图表看板、统计分析页),目标是“原汁原味”导出为 PDF。使用
jsPDF + html2canvas能够在极短时间内交付,无需重新手写排版逻辑。 - 版面位置严格受限的单页单据:如快递面单、仓储货架标签、准考证、结业证书、发票套打。这类文档尺寸固定,每个文字与条形码必须落在绝对毫米坐标处,jsPDF 的
doc.text(str, x, y)最直接直观。 - 轻量级应用与极致体积要求:对首屏体积非常敏感,仅需输出几行简短文本或单张图片,不需要加载复杂的文档流排版运行时。
2. 坚决推荐选择 pdfmake 的场景
- 多页数据分析报告与长篇合同:包含前言、多个层级标题、正文、说明条款、签署栏。文本长度由后端接口动态决定,无法预知是否超出一页,必须依赖自动断行与自然分页。
- 大量复杂表格与明细对账单:如银行流水单、ERP 采购清单、财务审计账本。需要表头在每一页顶部自动重现、列宽根据内容自适应分布、支持跨行跨列。
- 规范化排版与品牌统一:需要全局统一定义标题字号、段落间距、标准边距、企业统一页眉 Logo 与“第 X 页 / 共 Y 页”页码格式。pdfmake 的声明式样式表能够实现高度工程化的组件封装与复用。
选型一句话总结
画板思维选 jsPDF,排版引擎选 pdfmake。需要“像素级绝对定位”或“直接截取网页 DOM”,用 jsPDF;需要“纯数据驱动、自适应多页流式排版、复杂跨页表格”,用 pdfmake。
JS遍历含Emoji字符串乱码怎么办?
2026-11-20 23:22:48
JS数组简单倒序与sort降序排列有什么区别?
2026-11-20 21:17:36
JavaScript函数定义实例:声明式、表达式与箭头函数的代码对比
2026-11-20 19:08:47
为什么JS clearInterval清除无效?常见ID丢失与作用域陷阱
2026-11-20 12:31:25
怎么遍历JavaScript对象中的Symbol属性?
2026-11-20 12:26:25








