[JS/TS] dompdf.js多页PDF生成功能详解：纯前端实现HTML到可编辑PDF转换

在前端开发中，生成PDF时你是否遇到过文件模糊不清、文字无法复制搜索、体积臃肿或分页位置错乱等问题？dompdf.js 在最新的V1.1.0版本中，通过新增的分页功能，让这些问题迎刃而解。它支持仅用一行代码，将复杂的HTML页面精准地分割并生成为可编辑、体积小巧的多页PDF文件，甚至能处理数千页的文档。

dompdf.js 是一个完全在前端生成PDF的开源库。它能够绕过服务器，直接在浏览器中将HTML内容渲染为非图片格式、文字可选、体积更优的PDF。此次版本更新的核心是分页功能，使得生成多页PDF成为可能，满足了众多开发者的迫切需求。

代码示例

导入库并启用分页功能非常简单：

import dompdf from "dompdf.js";
dompdf(document.querySelector("#capture"), { pagination: true }).then(function (blob) {
  // 后续文件操作
});

实现效果示例如下（可生成数千页PDF）：

注意：生成数千页是较为极端的情况，实际可生成的页数受文件内容影响。纯文字内容可生成更多页数，若包含大量图片，则页数会相应减少。

在线体验与源码

• 在线体验地址：https://dompdfjs.lisky.com.cn
• GitHub仓库：https://github.com/lmn1919/dompdf.js (欢迎Star)
• Gitee镜像：https://gitee.com/liu-facai/dompdf.js

V1.1.0 新功能特性

1. 精准的分页功能

分页算法能智能处理各类复杂元素，确保分割准确。

• 图片分页效果
  
• 左右布局分页效果
  
• 文本分页效果
  
• 复杂表格分页效果
  

2. 自定义页眉页脚

支持设置页眉页脚的高度、内容、字体大小、颜色及对齐方式。

3. 增强的PDF属性

支持为PDF文件设置密码、操作权限，并可选择进行压缩以减小体积。

分页实现原理浅析

dompdf.js 实现多页PDF生成的核心步骤：

1. 解析DOM树：将目标HTML元素解析为一棵包含位置信息（bounds）、样式和文本数据的DOM对象树。
2. 递归分页：递归遍历DOM树，根据预设的页面高度（如A4纸的1123px）和每个元素的 bounds.top + bounds.height 判断是否需要进行分页。将原始DOM树分割为多个“页面DOM树”数组，并重新计算跨页元素在新页面中的位置。
3. 循环绘制：遍历分页后的DOM树数组，为每一页调用 jspdf.addPage() 并绘制页眉页脚。最后根据元素类型（文本、图片等）及其位置信息，调用对应的 jspdf API（如 text(), image()）生成最终的PDF。

使用文档

安装与引入

• NPM安装:

  npm install dompdf.js --save

• CDN引入:

  <script src="https://cdn.jsdelivr.net/npm/dompdf.js@latest/dist/dompdf.js"></script>

基础用法

import dompdf from "dompdf.js";
dompdf(document.querySelector("#capture"), options)
  .then((blob) => {
    const url = URL.createObjectURL(blob);
    const a = document.createElement("a");
    a.href = url;
    a.download = "example.pdf";
    document.body.appendChild(a);
    a.click();
  })
  .catch((err) => {
    console.error(err);
  });

开启PDF分页渲染

默认生成单页PDF。通过设置 pagination: true 开启分页，并通过 pageConfig 自定义页眉页脚。
关键前置步骤：必须将要生成PDF的DOM节点的CSS宽度设置为目标纸张的像素宽度。例如，A4纸需设置为 794px。详细尺寸对照表请参考官方文档。

<div id="capture" style="width:794px">
  <!-- 你的内容 -->
</div>

import dompdf from "dompdf.js";
dompdf(document.querySelector("#capture"), {
  pagination: true,
  format: "a4",
  pageConfig: {
    header: {
      content: "这是页眉",
      height: 50,
      contentColor: "#333333",
      contentFontSize: 12,
      contentPosition: "center",
    },
    footer: {
      content: "第${currentPage}页/共${totalPages}页",
      height: 50,
      contentColor: "#333333",
      contentFontSize: 12,
      contentPosition: "center",
    },
  },
})
.then((blob) => { /* 下载逻辑 */ })
.catch((err) => console.error(err));

精准分页控制：divisionDisable 属性

若希望某个容器（如图片、表格）在分页时不被拆散，可以为其添加 divisionDisable 属性。跨页时，该元素将整体移至下一页。

<img src="example.jpg" alt="" crossorigin="anonymous" divisionDisable/>

右侧为使用了 divisionDisable 属性的效果：

核心配置参数 (Options)

参数名	必传	默认值	类型	说明
useCORS	否	false	boolean	允许加载跨域图片（需服务端配合CORS）
backgroundColor	否	自动解析/白色	string \| null	覆盖页面背景色；传 null 生成透明背景
fontConfig	否	-	object	非英文字体配置（见下文）
encryption	否	空配置	object	PDF加密与权限配置
precision	否	16	number	元素位置计算的精度
compress	否	false	boolean	是否压缩PDF文件
pagination	否	false	boolean	开启分页渲染
format	否	‘a4‘	string	页面规格，支持 a0–a10、letter 等
pageConfig	否	见下表	object	页眉页脚配置

pageConfig 字段详解：
支持为 header 和 footer 设置 content (内容，支持 ${currentPage}/${totalPages} 变量)、height (高度)、contentPosition (位置)、contentColor (颜色)、contentFontSize (字号) 等。

解决乱码：自定义字体支持

由于底层 jspdf 库对非英文字符支持有限，直接生成中文PDF会出现乱码。解决方案是导入对应的中文字体（如思源黑体，体积较小）。需要将 .ttf 字体文件转为 Base64 格式并引入。

<script type="text/javascript" src="./SourceHanSansSC-Normal-Min-normal.js"></script>
<script>
  dompdf(document.querySelector(‘#capture‘), {
    useCORS: true,
    fontConfig: {
      fontFamily: ‘SourceHanSansSC-Normal-Min‘,
      fontBase64: window.fontBase64 // 来自上一步引入的js文件
    }
  }).then(function(blob) { /* 下载逻辑 */ });
</script>

处理复杂样式：foreignObjectRendering 属性

对于渐变、阴影等 jsPDF 原生无法绘制的复杂CSS样式，可以为容器元素添加 foreignObjectRendering 属性。该功能会通过SVG的 foreignObject 将元素渲染为图片嵌入PDF。
注意事项：此方式会增大PDF体积；渲染依赖浏览器实现，建议在Chrome、Firefox、Edge中使用；IE浏览器不支持。

<div style="width: 100px;height: 100px;" foreignObjectRendering>
  <div style="width: 50px;height: 50px; border: 1px solid #000; box-shadow: 2px 2px 5px rgba(0,0,0,0.3); background: linear-gradient(45deg, #ff6b6b, #4ecdc4);">
    这是一个包含阴影和渐变的div
  </div>
</div>

浏览器兼容性

此基于JavaScript的库在大部分现代浏览器中均可工作（需要 Promise 支持，IE9+需polyfill）：

• Firefox 3.5+
• Google Chrome
• Opera 12+
• IE9+
• Safari 6+