什么是 ReportLab？

reportlab 是一个功能强大的开源 Python 库，专门用于在程序中动态生成 PDF 文档，它不需要任何外部依赖（如 Adobe Acrobat 或 LaTeX），非常适合用于：

• 生成发票、合同、报告等商业文档。
• 创建图表、表格和图形。
• 制作标签、条形码等。
• 将 HTML 或其他格式的文件转换为 PDF。

安装 ReportLab

安装 reportlab 非常简单，通常使用 Python 的包管理工具 pip 即可。

步骤 1：打开终端或命令提示符

• Windows: 打开 "命令提示符" (CMD) 或 "PowerShell"。
• macOS: 打开 "终端" (Terminal)。
• Linux: 打开 "终端" (Terminal)。

步骤 2：使用 pip 安装

在终端中输入以下命令并按回车：

pip install reportlab

验证安装

安装完成后,你可以通过 Python 解释器来验证是否安装成功，在终端中输入 python 或 python3 进入交互式环境，然后尝试导入 reportlab：

>>> import reportlab
>>> print(reportlab.Version)
# 如果安装成功，它会打印出版本号，'3.6.12'

如果没有任何错误提示,并且能打印出版本号，说明 reportlab 已经成功安装。

一个简单的入门示例

让我们从一个最简单的例子开始：创建一个 "Hello, World!" 的 PDF 文件。

创建一个名为 hello_pdf.py 的文件，并粘贴以下代码：

# 1. 导入必要的模块
from reportlab.pdfgen import canvas
from reportlab.lib.pagesizes import letter, A4
from reportlab.lib.units import inch
# 2. 创建一个 Canvas 对象
# 'hello.pdf' 是要生成的文件名
# pagesizes=A4 指定页面大小为 A4，也可以使用 letter
c = canvas.Canvas("hello.pdf", pagesize=A4)
# 3. 在画布上绘制文本
# c.drawString(x坐标, y坐标, "要显示的文本")
# 坐标原点(0, 0) 在左下角
c.drawString(100, 750, "Hello, World! from ReportLab!")
# 4. 保存并关闭 PDF 文件
# 这个步骤非常重要，否则文件会是空的或不完整的
c.save()
print("PDF 文件 'hello.pdf' 已成功生成！")

如何运行？

在终端中,导航到你保存 hello_pdf.py 文件的目录，然后运行：

python hello_pdf.py

运行后,你会在同一目录下找到一个名为 hello.pdf 的文件，用 PDF 阅读器打开它，你就能看到 "Hello, World!" 的文本了。

更丰富的 PDF 生成示例

下面是一个更复杂的例子,展示如何添加字体、段落、表格和图片。

创建一个名为 advanced_pdf.py 的文件：

from reportlab.pdfgen import canvas
from reportlab.lib.pagesizes import A4
from reportlab.lib.units import cm
from reportlab.lib.styles import getSampleStyleSheet, ParagraphStyle
from reportlab.platypus import SimpleDocTemplate, Paragraph, Table, TableStyle, Image
from reportlab.lib import colors
# --- 1. 准备数据 ---
# 定义文档的基本信息= "高级 PDF 报告示例"
doc_author = "ReportLab 教程"
# 定义要写入的段落文本
story_text = """
这是一个使用 ReportLab 生成的更高级的 PDF 报告。
ReportLab 是一个非常强大的 Python 库，可以用来创建复杂的布局、表格和图表。
你可以用它来生成发票、报告、证书等各种文档。
"""
# 定义表格数据
table_data = [
    ['项目', '数量', '单价', '总价'],
    ['服务费', '1', '¥500.00', '¥500.00'],
    ['硬件费用', '2', '¥1200.50', '¥2401.00'],
    ['税费', '', '', '¥190.10'],
    ['总计', '', '', '¥3091.10']
]
# --- 2. 创建文档和画布 ---
# 使用 SimpleDocTemplate 简化文档创建过程
# 它会自动处理分页、页边距等
doc = SimpleDocTemplate(
    "advanced_report.pdf",
    pagesize=A4,
    rightMargin=72,
    leftMargin=72,
    topMargin=72,
    bottomMargin=18
)
# --- 3. 构建文档内容 ---
# 一个 Platypus 文档由一个 "流" 对象列表构成
story = []
# 获取样式表
styles = getSampleStyleSheet()
title_style = ParagraphStyle(
    'CustomTitle',
    parent=styles['Heading1'],
    fontSize=24,
    spaceAfter=30,
    alignment=1  # 1 表示居中
)
story.append(Paragraph(doc_title, title_style))
# 添加作者信息
author_style = ParagraphStyle(
    'CustomAuthor',
    parent=styles['Normal'],
    fontSize=12,
    textColor=colors.grey,
    alignment=1
)
story.append(Paragraph(f"作者: {doc_author}", author_style))
# 添加一个空行
story.append("")
# 添加段落
p = Paragraph(story_text, styles['Normal'])
story.append(p)
# 添加一个空行
story.append("")
# 添加表格
table = Table(table_data, colWidths=[4*cm, 2*cm, 2*cm, 2*cm])
# 设置表格样式
style = TableStyle([
    ('BACKGROUND', (0, 0), (-1, 0), colors.grey),  # 标题行背景色
    ('TEXTCOLOR', (0, 0), (-1, 0), colors.whitesmoke), # 标题行文字颜色
    ('ALIGN', (0, 0), (-1, -1), 'CENTER'), # 所有单元格居中
    ('FONTNAME', (0, 0), (-1, 0), 'Helvetica-Bold'), # 标题行字体
    ('FONTSIZE', (0, 0), (-1, 0), 14), # 标题行字号
    ('BOTTOMPADDING', (0, 0), (-1, 0), 12), # 标题行底部内边距
    ('BACKGROUND', (0, 1), (-1, -1), colors.beige), # 数据行背景色
    ('GRID', (0, 0), (-1, -1), 1, colors.black) # 添加网格线
])
table.setStyle(style)
story.append(table)
# (可选) 添加图片
# 确保 'logo.png' 文件和你的 Python 脚本在同一目录下
# try:
#     img = Image("logo.png", width=4*cm, height=2*cm)
#     story.append(img)
# except FileNotFoundError:
#     story.append(Paragraph("注意: 未找到 logo.png 文件", styles['Normal']))
# --- 4. 生成 PDF ---
# build() 方法会处理所有内容并生成 PDF
doc.build(story)
print("高级 PDF 报告 'advanced_report.pdf' 已成功生成！")

如何运行？

python advanced_pdf.py

运行后,你会得到一个名为 advanced_report.pdf 的文件，其中包含了标题、作者、段落和格式化的表格。

常见问题与解决方案

Q1: 安装时出现 Permission denied 错误

问题: pip install reportlab 后提示 Permission denied: '.../site-packages/reportlab'。

原因: 尝试将包安装到系统级的 Python 环境中，而当前用户没有权限。

解决方案 (推荐):

1. 使用虚拟环境: 这是最佳实践，它可以为每个项目创建一个隔离的环境，避免包版本冲突。

   # 1. 创建虚拟环境 (推荐使用 venv)
   python -m venv myenv
   # 2. 激活虚拟环境
   # Windows:
   myenv\Scripts\activate
   # macOS / Linux:
   source myenv/bin/activate
   # 3. 在激活后的环境中安装 (现在不需要管理员权限)
   pip install reportlab

2. 使用 --user 标志: 如果不想用虚拟环境，可以安装到用户目录下。

   pip install --user reportlab

Q2: 运行脚本时出现 ModuleNotFoundError: No module named 'reportlab'

问题: Python 脚本提示找不到 reportlab 模块。

原因:

1. reportlab 没有安装。
2. 你在一个错误的 Python 环境中运行脚本（安装在了 python3，但用 python 运行）。

解决方案:

1. 确认已正确安装。
2. 检查你的终端/命令行提示符，确保你是在安装了 reportlab 的那个 Python 环境中，如果你使用了虚拟环境，请确保它已被激活（命令行前通常会显示环境名称，如 (myenv) C:\...>）。

Q3: 如何处理中文（或其他非 ASCII 字符）？

reportlab 默认不支持中文字体，如果你直接写入中文，很可能会得到一堆方框 口 或报错。

解决方案:

你需要明确指定一个支持中文的字体文件（如 .ttf 文件）。

from reportlab.pdfgen import canvas
from reportlab.pdfbase import pdfmetrics
from reportlab.pdfbase.ttfonts import TTFont
# 1. 注册 TrueType 字体
# 'SimSun.ttf' 是一个常见的宋体字体文件，你需要确保这个文件存在
# 你可以从你的系统或网上下载一个中文字体文件
try:
    pdfmetrics.registerFont(TTFont('SimSun', 'SimSun.ttf'))
except:
    print("错误: 未找到 SimSun.ttf 字体文件，请下载一个中文字体文件并放在脚本同目录下。")
    # 如果没有中文字体，回退到默认字体
    font_name = 'Helvetica'
else:
    font_name = 'SimSun'
c = canvas.Canvas("chinese_test.pdf")
# 2. 使用注册的字体
c.setFont(font_name, 16)
c.drawString(100, 750, "你好，世界！")
c.save()
print("中文 PDF 'chinese_test.pdf' 已生成。")

注意: 你需要自己准备一个中文字体文件（如 SimSun.ttf, SimHei.ttf, msyh.ttc 等），并确保代码能找到它。

• 安装: pip install reportlab
• 核心概念:
  • canvas: 底层画布，适合直接绘制图形和简单文本。
  • SimpleDocTemplate 和 Platypus (流/列表): 高层接口，适合构建复杂、多页的文档，包含段落、表格、图片等。
• 处理中文: 必须手动注册和加载支持中文的 .ttf 字体文件。

希望这份详细的指南能帮助你顺利开始使用 reportlab！