JS生成PDF怎么添加自定义页眉页脚和页码

作者:小括号时间:2026-11-22 18:43:19浏览:597

详解在前端使用JavaScript生成PDF文件时,如何正确添加自定义页眉、页脚及“第X页/共Y页”动态页码。涵盖jsPDF后置遍历渲染与pdfmake声明式回调两种主流方案、版面安全边距规划与常见问题解决方案。

JS生成PDF怎么添加自定义页眉页脚和页码
图 0:JavaScript 客户端生成 PDF 文档的页眉、页脚与动态页码整体布局架构

在前端使用 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 作为参数直接传递给开发者。
JS生成PDF怎么添加自定义页眉页脚和页码
图 1:后置遍历注入法的两阶段核心运行机制流程

二、使用 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");
}
JS生成PDF怎么添加自定义页眉页脚和页码
图 2:jsPDF 操作全流程:从边距规划、内容排版到后置遍历绘制

三、使用 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) 的直角坐标系。必须明确划分出页眉专用区、正文活动区与页脚专用区三个隔离层:

JS生成PDF怎么添加自定义页眉页脚和页码
图 3:A4 纸物理坐标系统与页眉/页脚/正文安全隔离带设计规范

六、核心注意事项与避坑指南

在生产环境下输出标准 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 方案的关键维度总结如下:

JS生成PDF怎么添加自定义页眉页脚和页码
图 4:JavaScript 生成 PDF 两种核心架构选型与落地防错准则总结

综上所述,在 JavaScript 环境中生成 PDF 时添加自定义页眉、页脚与页码,关键在于把握总页数确定的时序节点。对于 jsPDF 方案,坚持“先排版正文、再读取总页数、后置循环遍历切页写入”的流程;对于 pdfmake 方案,合理配置全局 pageMargins 并直接在 header/footer 函数中接收参数,即可稳定导出美观、规范且无内容遮挡的专业 PDF 文档。

作者最新文章
相关文章
更多