使用Python ReportLab库遇问题：无法在每页添加页眉和页脚

核心思路 #

ReportLab的页眉页脚要全局生效，关键是把页眉页脚的绘制逻辑绑定到每一页的渲染流程里，常用的可靠方式是结合BaseDocTemplate、PageTemplate和Frame，或者正确使用onPage回调。

方法一：使用onPage回调（最简方案） #

如果之前用onPage没成功，大概率是没在文档build时正确传入，或者回调函数里的坐标计算有误。

示例代码 #

from reportlab.lib.pagesizes import letter
from reportlab.pdfgen import canvas
from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer
from reportlab.lib.styles import getSampleStyleSheet

def draw_header_footer(canvas, doc):
    # 保存当前画布状态，避免影响正文渲染
    canvas.saveState()
    
    # 绘制居中页眉
    header_text = "全局页眉"
    canvas.setFont("Helvetica", 10)
    canvas.drawCentredString(doc.pagesize[0]/2, doc.pagesize[1]-20, header_text)
    
    # 绘制带页码的居中页脚
    footer_text = f"第 {doc.page} 页"
    canvas.drawCentredString(doc.pagesize[0]/2, 20, footer_text)
    
    # 恢复画布状态
    canvas.restoreState()

# 创建文档实例
doc = SimpleDocTemplate("test.pdf", pagesize=letter)
styles = getSampleStyleSheet()
flowables = []

# 添加多页测试内容
for i in range(50):
    flowables.append(Paragraph(f"测试内容第{i+1}段", styles["BodyText"]))
    flowables.append(Spacer(1, 12))

# 关键：build时传入onPage回调，首尾页用同一个函数
doc.build(flowables, onFirstPage=draw_header_footer, onLaterPages=draw_header_footer)

注意点 #

• onFirstPage和onLaterPages可分开设置不同样式，也可共用同一函数
• 坐标基于页面尺寸计算：doc.pagesize[0]是宽度，doc.pagesize[1]是高度，原点在页面左下角
• 必须调用saveState()和restoreState()，防止页眉页脚的字体、颜色设置污染正文

方法二：使用PageTemplate和Frame（复杂布局适配） #

如果需要更灵活的页眉页脚布局（比如左侧logo、右侧标题），可以自定义页面模板，把页眉页脚设为固定区域。

示例代码 #

from reportlab.lib.pagesizes import letter
from reportlab.platypus import BaseDocTemplate, Frame, Paragraph, Spacer, PageTemplate
from reportlab.lib.styles import getSampleStyleSheet
from reportlab.lib.units import inch

class CustomDocTemplate(BaseDocTemplate):
    def __init__(self, filename, **kw):
        super().__init__(filename, **kw)
        # 定义正文区域：上下左右各留1英寸，顶部额外留0.5英寸给页眉
        main_frame = Frame(inch, inch, self.pagesize[0]-2*inch, self.pagesize[1]-2.5*inch, id='main')
        # 添加绑定了页眉页脚逻辑的页面模板
        self.addPageTemplates([PageTemplate(id='custom', frames=[main_frame], onPage=self.draw_header_footer)])
    
    def draw_header_footer(self, canvas, doc):
        # 绘制左侧加粗页眉
        canvas.setFont("Helvetica-Bold", 12)
        canvas.drawString(inch, doc.pagesize[1]-1.2*inch, "自定义页眉")
        # 绘制右侧页码页脚
        canvas.setFont("Helvetica", 10)
        canvas.drawRightString(doc.pagesize[0]-inch, 0.5*inch, f"页码: {doc.page}")

# 创建自定义文档
doc = CustomDocTemplate("test_template.pdf", pagesize=letter)
styles = getSampleStyleSheet()
flowables = []

# 添加多页测试内容
for i in range(50):
    flowables.append(Paragraph(f"测试内容第{i+1}段", styles["BodyText"]))
    flowables.append(Spacer(1, 12))

doc.build(flowables)

注意点 #

• Frame的位置要避开页眉页脚区域，防止正文覆盖固定内容
• 自定义模板时，必须将onPage绑定到PageTemplate实例上
• 若需多种页面布局，可添加多个PageTemplate并在内容中指定切换

常见错误排查 #

• partial update无效：该方法仅适用于动态更新局部内容，无法全局绑定每页渲染逻辑
• 新模板不生效：未将自定义模板添加到文档的pageTemplates列表，或Frame区域坐标设置错误
• 页眉页脚位置偏移：混淆了ReportLab的坐标原点（左下角），需重新计算顶部/底部的坐标值

内容的提问来源于stack exchange，提问作者Akshat Kulshreshtha