![使用 Python 为 PDF 文档添加页眉和页脚](https://developer.qcloudimg.com/http-save/yehe-2596118/a795792c8d30f0e915bce69bbabdbc64.png)

PDF 是文档分发和存档的标准格式，而页眉和页脚是正式文档中不可或缺的组成部分——公司名称、文档标题、章节信息、页码等元素都依赖它们来呈现。对于开发人员来说，手动为一份几十页甚至上百页的 PDF 添加页眉页脚显然不现实，尤其是当文档需要定期批量生成时，编程方式几乎是唯一可行的选择。

本文将介绍如何使用 Python 为 PDF 文档添加页眉和页脚，包括纯文本页眉页脚、图片页眉、为不同页面设置不同页眉，以及通过页面模板自动生成页码等内容。

## 为什么需要编程添加页眉页脚

在代码中处理 PDF 页眉页脚，相比手动编辑有几点实际优势：

- **批量处理** - 用循环遍历所有页面，一次调用即可为整份文档添加统一的页眉页脚
- **动态内容** - 页码、章节号等内容可以根据文档状态自动生成，无需人工维护
- **样式一致** - 字体、颜色、对齐方式由代码统一控制，避免人工操作产生的差异

## 环境准备

本文使用 Spire.PDF 库实现 PDF 文档的处理，安装命令如下：

```bash
pip install Spire.PDF
```

该库提供完整的 PDF 创建和编辑能力。页眉页脚本质上是通过在页面画布（Canvas）上绘制文本、图片和线条来实现的。需要注意的是，PDF 的坐标系以页面左下角为原点，单位为点（1 点 = 1/72 英寸）。

## 添加文本页眉和页脚

为整份文档添加统一的文本页眉页脚，最常见的做法是遍历所有页面，在每个页面的画布上绘制内容。以下代码在每页顶部添加右对齐的页眉文本，在底部添加分隔线和页码：

```python
from spire.pdf.common import *
from spire.pdf import *

doc = PdfDocument()
doc.LoadFromFile("Input.pdf")
margin = doc.PageSettings.Margins

# 定义画笔、字体和对齐方式
pen = PdfPen(PdfBrushes.get_Black(), 0.75)
font = PdfTrueTypeFont("微软雅黑", 12.0, PdfFontStyle.Italic, True)
brush = PdfBrushes.get_Black()
format = PdfStringFormat(PdfTextAlignment.Right)
format.MeasureTrailingSpaces = True
space = font.Height * 0.75

for i in range(doc.Pages.Count):
    page = doc.Pages.get_Item(i)
    x = margin.Left
    width = page.Canvas.ClientSize.Width - margin.Left - margin.Right

    # 页眉：绘制分隔线 + 文本
    y = margin.Top - space
    page.Canvas.DrawLine(pen, x, y, x + width, y)
    page.Canvas.DrawString("内部资料", font, brush, x + width, y - font.Height, format)

    # 页脚：绘制分隔线 + 页码
    y = page.Canvas.ClientSize.Height - margin.Bottom + space
    page.Canvas.DrawLine(pen, x, y, x + width, y)
    label = "{0} / {1}".format(i + 1, doc.Pages.Count)
    page.Canvas.DrawString(label, font, brush, x + width, y + 1, format)

doc.SaveToFile("HeaderAndFooter.pdf")
doc.Close()
```

输出文档预览：

![用Python添加文本页眉页脚到PDF](https://developer.qcloudimg.com/http-save/yehe-2596118/ed642c4f7fdb7ca87c5f1bb00aff54f0.png)


几个关键点的说明：

- `PdfTrueTypeFont` 指定字体名称、字号和样式，`PdfFontStyle.Italic` 表示斜体，最后一个布尔参数表示是否嵌入字体
- `PdfStringFormat` 控制文本对齐方式；`MeasureTrailingSpaces = True` 让右对齐时也计算尾随空格，保证位置精确
- 页眉位于上边距上方、页脚位于下边距下方，`font.Height * 0.75` 用于在文本与分隔线之间留出合理间距

## 在页眉中插入图片

很多文档会在页眉放置公司 Logo。图片的插入同样在画布上进行，使用 `PdfImage.FromFile()` 加载图片后，调用 `DrawImage()` 指定绘制位置即可：

```python
headerImage = PdfImage.FromFile("Logo.png")
page.Canvas.DrawImage(headerImage, PointF(0.0, 0.0))
```

`DrawImage()` 的第二个参数是图片左上角的坐标。如果需要控制图片大小，可以额外传入宽度和高度参数（单位为点），例如将 Logo 缩小一半：

```python
page.Canvas.DrawImage(headerImage, 50.0, 20.0,
    headerImage.Width / 2.0, headerImage.Height / 2.0)
```

## 为不同页面设置不同的页眉

章节较多的文档通常需要每章使用不同的页眉。由于页眉是通过在具体页面上绘制实现的，因此只需按页面索引分别绘制即可：

```python
rect = RectangleF(PointF(0.0, 20.0), SizeF(doc.PageSettings.Size.Width, 50.0))

# 第 1 页：红色加粗、居中对齐
font1 = PdfTrueTypeFont("微软雅黑", 15.0, PdfFontStyle.Bold, True)
format1 = PdfStringFormat()
format1.Alignment = PdfTextAlignment.Center
doc.Pages[0].Canvas.DrawString("第一章 概述", font1, PdfBrushes.get_Red(), rect, format1)

# 第 2 页：黑色常规、左对齐
font2 = PdfTrueTypeFont("微软雅黑", 15.0, PdfFontStyle.Regular, True)
format2 = PdfStringFormat()
format2.Alignment = PdfTextAlignment.Left
doc.Pages[1].Canvas.DrawString("第二章 实现", font2, PdfBrushes.get_Black(), rect, format2)
```

这里通过 `doc.Pages[索引]` 直接访问指定页面，再为每页设置不同的字体、颜色和对齐方式。如果文档章节较多，可以先计算各章节对应的页码范围，再结合循环批量绘制。

## 使用页面模板统一管理页眉页脚

当页眉页脚需要作用于文档所有页面、且希望内容自动生效时，使用页面模板（`PdfPageTemplateElement`）是更优雅的方案。模板与页面内容分离，后续新增页面时会自动应用：

```python
from spire.pdf.common import *
from spire.pdf import *

# 创建文档，设置页面尺寸和边距
doc = PdfDocument()
doc.PageSettings.Size = PdfPageSize.A4()
doc.PageSettings.Margins = PdfMargins(50.0, 50.0, 50.0, 50.0)
pageSize = doc.PageSettings.Size

# 创建页眉模板：绘制 Logo 和分隔线
headerSpace = PdfPageTemplateElement(pageSize.Width, 50.0)
headerSpace.Foreground = False
image = PdfImage.FromFile("Logo.png")
headerSpace.Graphics.DrawImage(image, 50.0, 20.0, image.Width / 2.0, image.Height / 2.0)
pen = PdfPen(PdfBrushes.get_LightGray(), 1.0)
headerSpace.Graphics.DrawLine(pen, 50.0, 45.0, pageSize.Width - 50.0, 45.0)

# 创建页脚模板：使用自动字段绘制“第 x 页，共 y 页”
footerSpace = PdfPageTemplateElement(pageSize.Width, 50.0)
footerSpace.Foreground = False
footerSpace.Graphics.DrawLine(pen, 50.0, 0.0, pageSize.Width - 50.0, 0.0)
number = PdfPageNumberField()
count = PdfPageCountField()
compositeField = PdfCompositeField(
    PdfTrueTypeFont("微软雅黑", 10.0, PdfFontStyle.Regular, True),
    PdfBrushes.get_Black(), "第 {0} 页，共 {1} 页", [number, count])
compositeField.StringFormat = PdfStringFormat(PdfTextAlignment.Left, PdfVerticalAlignment.Top)
compositeField.Bounds = RectangleF(PointF(50.0, 5.0), SizeF(200.0, 20.0))
widget = PdfGraphicsWidget(compositeField.Ptr)
widget.Draw(footerSpace.Graphics)

# 将模板应用到文档的顶部和底部
doc.Template.Top = headerSpace
doc.Template.Bottom = footerSpace

# 添加页面并保存
doc.Pages.Add()
doc.SaveToFile("TemplateHeaderFooter.pdf", FileFormat.PDF)
doc.Close()
```

这里的关键是 `PdfPageNumberField` 和 `PdfPageCountField` 两个自动字段：它们不存储具体数值，而是在渲染时自动替换为当前页码和总页数，因此无需手动遍历页面计算。`PdfCompositeField` 负责把多个字段组合到一段格式化文本中。模板对象的 `Foreground` 属性设为 `False`，表示模板内容位于页面内容的底层，不会遮挡正文。

## 实用技巧

- **保留原有页面内容**：直接向已有页面绘制页眉页脚会覆盖正文。可以先通过 `page.CreateTemplate()` 将原页面保存为模板，在新页面中先绘制页眉页脚，再通过 `PdfGraphicsWidget` 将原内容绘制到底层，从而在不损坏内容的前提下添加页眉页脚。
- **半透明效果**：调用 `page.Canvas.SetTransparency(0.5)` 可以降低后续绘制内容的透明度，让页眉页脚以类似水印的形式呈现，视觉上更柔和。
- **注意字体嵌入**：`PdfTrueTypeFont` 构造函数的最后一个布尔参数控制字体是否嵌入文档，设为 `True` 可以保证文档在其他设备上打开时字体显示一致。

## 总结

本文介绍了使用 Python 为 PDF 文档添加页眉页脚的几种方式：通过画布绘制文本和图片实现自定义页眉页脚、按页面索引为不同页面设置不同内容，以及使用页面模板配合自动字段统一管理页码。实际开发中可以根据文档结构选择合适的方式——简单的统一页眉页脚用遍历绘制即可，需要自动页码或批量生成时，页面模板是更省心的选择。

掌握这些方法后，可以进一步结合查找替换、水印、图层等操作，构建完整的文档自动化处理流程。


PDF 是文档分发和存档的标准格式，而页眉和页脚是正式文档中不可或缺的组成部分——公司名称、文档标题、章节信息、页码等元素都依赖它们来呈现。对于开发人员来说，手动为一份几十页甚至上百页的 PDF 添加页眉页脚显然不现实，尤其是当文档需要定期批量生成时，编程方式几乎是唯一可行的选择。

如何通过 Python 自动添加 PDF 页眉和页脚

本文将介绍如何使用 Python 为 PDF 文档添加页眉和页脚，包括纯文本页眉页脚、图片页眉、为不同页面设置不同页眉，以及通过页面模板自动生成页码等内容。

编程语言

学习Python编程为PDF添加页眉页脚技巧，包括文本、图片、页码设置方法。掌握Spire.PDF库批量处理、动态生成内容、保持样式一致等优势，实现文档自动化处理，提升工作效率。

代码解释

Python

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

如何通过 Python 自动添加 PDF 页眉和页脚-腾讯云开发者社区-腾讯云

如何通过 Python 自动添加 PDF 页眉和页脚

如何通过 Python 自动添加 PDF 页眉和页脚

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐