JS生成PDF怎么添加自定义页眉页脚和页码
详解在前端使用JavaScript生成PDF文件时,如何正确添加自定义页眉、页脚及“第X页/共Y页”动态页码。涵盖jsPDF后置遍历渲染与pdfmake声明式回调两种主流方案、版面安全边距规划与常见问题解决方案。
在前端使用 JavaScript 生成 PDF 导出文档时,添加固定的页眉、页脚及“第 X 页 / 共 Y 页”页码的核心逻辑,依赖于页面生成生命周期控制或后置页面遍历注入。由于文档正文的数据量通常是动态变化的,在正文排版结束之前,程序无法预知总页数。因此,解决该问题的核心路径有两种:一种是在正文排版生成全部页面后,通过获取总页数并循环切入每一页进行绝对定位绘制;另一种是使用支持声明式动态回调的引擎(如 pdfmake),由引擎在计算完页码后自动调用页眉页脚函数。本文将围绕这两种主流场景,详解具体操作步骤、计算公式与防重叠排版细节。
一、页眉页脚与动态页码的生成机制
在普通的 HTML 页面打印中,开发者通常借助 CSS 打印规则(如 @page、@bottom-right)实现页眉页脚。但在浏览器客户端使用纯 JavaScript 引擎(例如 jsPDF、pdfmake)直接构建矢量 PDF 时,页面是由 JavaScript 坐标系统(Points 或 Millimeters)直接计算绘制的。
这一过程存在一个根本矛盾:页脚通常需要输出“第 X 页 / 共 Y 页”,但 Y(总页数)在正文排版过程中是动态递增的未知数。如果在一个页面刚创建时就立即写入页脚,此时程序并不知道后续还会产生多少页内容。为此,业界通用的处理机制分为两类:
- 后置遍历法(jsPDF 常用):先让正文流式输出(无论是绘制长文本还是自动分页表格),待全部页面构建完毕后,调用 API 读取当前总页数
N。接着通过循环重置页面指针,从第 1 页切换到第N页,在预留的安全边距区间中补充绘制页眉和页脚文字。 - 引擎钩子与声明式回调法(jspdf-autotable / pdfmake 常用):由表格插件或 PDF 引擎托管整个生命周期。引擎在计算完所有分页并确认总页数后,在每一页渲染时触发回调函数,将当前页码
currentPage和总页数pageCount作为参数直接传递给开发者。
二、使用 jsPDF 原生 API 添加页眉页脚与页码
在以 jsPDF(前端使用最广泛的轻量级 PDF 库)为基础的项目中,推荐采用后置循环遍历法。这种方法与业务正文代码解耦,无论正文是单段长文本还是分页表格,都不影响页眉页脚的统一样式追加。
1. 核心 API 说明
要完成精确的遍历绘制,需要掌握以下 4 个核心 API:
doc.internal.getNumberOfPages():返回当前文档已生成的总页数。doc.setPage(pageIndex):将文档的写入指针重置到指定页面(页码下标从1开始,而非0)。doc.internal.pageSize.getWidth()与getHeight():获取当前页面的物理宽度和高度(通常以毫米 mm 或像素 pt 为单位),避免因硬编码页面尺寸导致横向/纵向排版错乱。doc.text(text, x, y, { align: 'right' | 'center' | 'left' }):支持配置文字水平对齐方式。利用align: 'right'或align: 'center',可以直接用基准边距坐标居中或靠右对齐页码,无需手动测量字符宽度。
2. 完整代码示例
import { jsPDF } from "jspdf";
function generateReportWithHeaderFooter() {
// 1. 初始化 A4 纵向文档,单位为毫米 (mm)
const doc = new jsPDF({
orientation: "portrait",
unit: "mm",
format: "a4"
});
// 页面尺寸 A4: 210mm x 297mm
const pageWidth = doc.internal.pageSize.getWidth();
const pageHeight = doc.internal.pageSize.getHeight();
// 2. 模拟写入正文内容(留出顶部 25mm、底部 20mm 的排版边距)
doc.setFontSize(14);
doc.text("业务报表第一页主体内容", 20, 35);
// 添加第二页
doc.addPage();
doc.text("业务报表第二页主体内容", 20, 35);
// 添加第三页
doc.addPage();
doc.text("业务报表第三页主体内容", 20, 35);
// 3. 正文写入完成后,获取实际总页数
const totalPages = doc.internal.getNumberOfPages();
// 4. 遍历所有页面,逐页绘制页眉、页脚及动态页码
for (let i = 1; i <= totalPages; i++) {
// 切换当前激活页面
doc.setPage(i);
// ================= [绘制页眉] =================
doc.setFontSize(9);
doc.setTextColor(100, 135, 165); // 柔蓝色
// 页眉左侧文字:公司/系统标识
doc.text("企业数据分析系统 · 季度运营报表", 15, 12);
// 页眉右侧文字:生成日期
doc.text("导出日期: 2026-11-12", pageWidth - 15, 12, { align: "right" });
// 页眉底部分割装饰线 (X1, Y1, X2, Y2)
doc.setDrawColor(216, 222, 228); // 柔灰边框色
doc.setLineWidth(0.3);
doc.line(15, 15, pageWidth - 15, 15);
// ================= [绘制页脚] =================
// 页脚顶部分割线
doc.line(15, pageHeight - 15, pageWidth - 15, pageHeight - 15);
doc.setFontSize(9);
doc.setTextColor(90, 109, 128); // 次要文本灰
// 页脚左侧:保密标注
doc.text("机密材料 · 仅供内部审阅", 15, pageHeight - 9);
// 页脚右侧:当前页 / 总页数 动态页码
const pageText = `第 ${i} 页 / 共 ${totalPages} 页`;
doc.text(pageText, pageWidth - 15, pageHeight - 9, { align: "right" });
}
// 5. 保存或预览输出
doc.save("quarterly-report.pdf");
}
三、使用 jspdf-autotable 插件处理跨页表格的页眉页脚
如果在 PDF 中包含大量表格,开发者通常会搭配 jspdf-autotable 插件使用。该插件自带页面绘制生命周期钩子 didDrawPage,使页眉页脚的嵌入更自然。
在 didDrawPage 触发时,表格当前页已被绘制,但开发者仍需要处理总页数。可以通过以下两种配合方式实现:
- 方案 A(推荐):在
didDrawPage钩子中只绘制固定不变的页眉(如公司名、报表标题、分割线)。至于含有“共 Y 页”的页脚页码,依然保留到表格生成完成后统一后置遍历写入。这样可以避免在生命周期钩子中预先计算总页数的复杂 hack 操作。 - 方案 B:在表格配置中设置
margin: { top: 25, bottom: 20 },确保表格自动换页时不会覆盖顶部的页眉区与底部的页脚区。
import { jsPDF } from "jspdf";
import "jspdf-autotable";
const doc = new jsPDF();
const pageWidth = doc.internal.pageSize.getWidth();
const pageHeight = doc.internal.pageSize.getHeight();
// 使用 autoTable 生成跨页数据表
doc.autoTable({
head: [["ID", "客户名称", "订单金额", "交付日期", "状态"]],
body: dynamicDataArray,
margin: { top: 25, bottom: 20 }, // 严格留出页眉页脚安全区
didDrawPage: function(data) {
// 每绘制完一页表格,自动补齐该页的页眉
doc.setFontSize(10);
doc.setTextColor(100, 135, 165);
doc.text("销售明细清单(实时导出)", 15, 12);
doc.setDrawColor(200);
doc.line(15, 15, pageWidth - 15, 15);
}
});
// 表格生成完毕,总页数已知,遍历追加页脚页码
const totalPages = doc.internal.getNumberOfPages();
for (let i = 1; i <= totalPages; i++) {
doc.setPage(i);
doc.setFontSize(9);
doc.setTextColor(120);
doc.text(`第 ${i} 页 / 共 ${totalPages} 页`, pageWidth - 15, pageHeight - 10, { align: "right" });
}
四、使用 pdfmake 实现声明式动态页眉与页码
除了 jsPDF,另一个被广泛采用的前端库是 pdfmake。不同于 jsPDF 的底层坐标命令式绘制,pdfmake 采用数据驱动与声明式配置。它原生提供了支持函数的 header 与 footer 属性,直接解决了总页数获取的问题。
1. pdfmake 的回调参数
在 pdfmake 的文档定义对象中,header 和 footer 可以直接定义为一个函数,该函数接收三个核心参数:
currentPage:当前页的页码(数字,从 1 开始)。pageCount:整个文档计算后的总页数(数字)。pageSize:包含width和height的页面实际尺寸对象。
2. 完整声明式配置示例
import pdfMake from "pdfmake/build/pdfmake";
import pdfFonts from "pdfmake/build/vfs_fonts";
pdfMake.vfs = pdfFonts.pdfMake.vfs;
const docDefinition = {
// 必须配置全局边距:[左, 上, 右, 下]
// 上边距 50 为页眉留出空间,下边距 40 为页脚留出空间
pageMargins: [40, 50, 40, 40],
// 1. 动态页眉函数
header: function(currentPage, pageCount, pageSize) {
return [
{
columns: [
{ text: "智库研报 · 核心数据汇总", alignment: "left", fontSize: 9, color: "#6487A5" },
{ text: "密级:公开", alignment: "right", fontSize: 9, color: "#5A6D80" }
],
margin: [40, 18, 40, 0] // 页眉内容的自身内边距
},
{
canvas: [
{
type: "line",
x1: 40, y1: 6,
x2: pageSize.width - 40, y2: 6,
lineWidth: 0.5,
lineColor: "#D8DEE4"
}
]
}
];
},
// 2. 动态页脚函数:自动获取 currentPage 与 pageCount
footer: function(currentPage, pageCount) {
return {
columns: [
{ text: "系统自动生成,打印有效", fontSize: 8, color: "#8C9BA5" },
{
text: `第 ${currentPage} 页 / 共 ${pageCount} 页`,
alignment: "right",
fontSize: 8,
color: "#C28B68"
}
],
margin: [40, 15, 40, 0]
};
},
// 3. 正文内容
content: [
{ text: "年度财务审计与分析报告", style: "mainHeader" },
{ text: "此处为正文段落,pdfmake 会根据内容长度自动进行安全跨页排版..." }
],
styles: {
mainHeader: { fontSize: 18, bold: true, margin: [0, 0, 0, 15] }
}
};
pdfMake.createPdf(docDefinition).download("annual-audit.pdf");
五、页面版心与安全边距架构(避坑关键)
在实现自定义页眉页脚时,初学者最常遇到的故障是“正文文字或表格遮挡了页眉页脚”,或者“页脚被挤压出了打印纸张边界”。这类问题并非代码逻辑错误,而是缺乏对 PDF 绝对物理版心的边界规划。
无论是使用哪种库,PDF 页面本质上是一个从左上角 (0, 0) 延伸至右下角 (pageWidth, pageHeight) 的直角坐标系。必须明确划分出页眉专用区、正文活动区与页脚专用区三个隔离层:
六、核心注意事项与避坑指南
在生产环境下输出标准 PDF 文档时,除了掌握基本语法,还需要注意以下 4 个极易出错的细节:
1. 首页(封面页)排除页眉与页脚
在合同、报告等正式文档中,第一页通常是封面,不允许显示页眉、页脚及“第 1 页 / 共 X 页”标记。在 jsPDF 的遍历循环中,只需加入判断条件跳过即可:
for (let i = 1; i <= totalPages; i++) {
// 如果是封面页,直接跳过页眉页脚绘制
if (i === 1) {
continue;
}
doc.setPage(i);
// 执行常规页眉页脚绘制...
// 提示:如需页码从正文开始记为第 1 页,可将文本显示改为 `第 ${i - 1} 页 / 共 ${totalPages - 1} 页`
}
2. 中文字体支持与字符乱码
原生 jsPDF 仅内置了 Helvetica、Times、Courier 等标准西文字体。直接使用 doc.text("第 1 页", ...) 可能会出现乱码或空白字符。解决方案如下:
- 使用
doc.addFont('SourceHanSans-Regular.ttf', 'SourceHanSans', 'normal')挂载中文字体文件。 - 通过
doc.setFont('SourceHanSans')激活中文字体后,再进行中文页眉和页脚文字的绘制。
3. 横向页面(Landscape)与页面尺寸变动
部分报表可能存在纵向(Portrait)和横向(Landscape)混排的情况。如果硬编码 pageWidth = 210,一旦切换到横向页面(宽度变为 297mm),页脚右侧的页码就会停留在页面中央,而无法对齐右边距。
避坑准则:务必在 for 循环的每次迭代内部重新读取 doc.internal.pageSize.getWidth() 和 doc.internal.pageSize.getHeight(),以此作为每页独立的坐标基准。
4. 页码左右对齐与居中计算公式
避免使用手动追加空格或估算文字像素的方式排版页码。jsPDF 的 text 方法自带对齐配置:
| 对齐目标 | X 坐标传参 | text 配置项 | 适用场景 |
|---|---|---|---|
| 右下角对齐 | pageWidth - margin_right |
{ align: "right" } |
商务报表、技术手册常见右侧页码 |
| 底端水平居中 | pageWidth / 2 |
{ align: "center" } |
学术论文、政府公文标准中间页码 |
| 左下角对齐 | margin_left |
{ align: "left" } |
页脚左侧版权声明或保密等级说明 |
七、技术方案选型与全流程总结
为了帮助读者根据实际项目场景做出正确的技术选型,我们将 jsPDF 原生方案、AutoTable 方案与 pdfmake 方案的关键维度总结如下:
综上所述,在 JavaScript 环境中生成 PDF 时添加自定义页眉、页脚与页码,关键在于把握总页数确定的时序节点。对于 jsPDF 方案,坚持“先排版正文、再读取总页数、后置循环遍历切页写入”的流程;对于 pdfmake 方案,合理配置全局 pageMargins 并直接在 header/footer 函数中接收参数,即可稳定导出美观、规范且无内容遮挡的专业 PDF 文档。
JS字符串转数组遍历:split('')与[...str]的区别
2026-11-22 17:33:40
JS回调函数怎么写:从同步传参到异步执行的代码示例
2026-11-22 17:05:07
怎么避免JS原型继承中的引用类型属性共享问题
2026-11-22 15:46:54
SheetJS导出Excel时怎么保留前端表格合并结构
2026-11-22 15:29:28
Dreamweaver可以写JavaScript吗?代码提示与调试支持详解
2026-11-22 14:26:36








