使用 Python 在 PDF 中绘制线条、矩形和自定义图形

在日常文档处理工作中，PDF 格式以其跨平台一致性成为分发和存档的首选。但在生成 PDF 时，仅仅包含文字内容往往不够------许多场景需要在文档中添加视觉元素，例如绘制分隔线、标注矩形区域、添加形状装饰等。无论是对报表进行区域划分，还是在设计稿中绘制原型元素，编程绘制图形都是一项基础而实用的能力。

本文将介绍如何使用 Python 在 PDF 文档中绘制常见的图形元素，包括直线、矩形、椭圆以及更复杂的自定义路径。

为什么需要编程绘制图形

通过代码在 PDF 中绘制图形，相比手动操作有几点实际优势：

精确控制 - 图形的坐标、尺寸、颜色和透明度均可通过参数精确定义，避免手动拖动带来的偏差
批量生成 - 结合循环和条件逻辑，可以一次性生成大量带有图形元素的文档
动态内容 - 根据数据源自动调整图形的位置和样式，适合报表和模板场景

环境准备

本文使用 Spire.PDF 库来实现 PDF 文档的创建和图形绘制。安装方式如下：

bash 复制代码

pip install Spire.PDF

该库提供了完整的 PDF 操作能力，包括页面管理、图形绘制、文字渲染等。

绘制基本图形

Spire.PDF 通过 PdfCanvas 对象提供了一系列绘制方法，所有绘图操作都在页面的画布（Canvas）上进行。画布使用坐标系定位，原点位于页面左下角，单位为点（point，1 点 = 1/72 英寸）。

绘制直线

绘制直线是最基本的图形操作，使用 DrawLine() 方法指定起点和终点坐标即可。

python 复制代码

from spire.pdf.common import *
from spire.pdf import *

# 创建 PDF 文档
doc = PdfDocument()
page = doc.Pages.Add()

# 保存画布状态
state = page.Canvas.Save()

# 创建画笔（黑色，线宽 1 点）
pen = PdfPen(PdfRGBColor(Color.get_Black()), 1.0)

# 绘制一条从 (50, 100) 到 (400, 100) 的水平线
page.Canvas.DrawLine(pen, 50.0, 100.0, 400.0, 100.0)

# 绘制一条从 (50, 100) 到 (225, 300) 的斜线
pen2 = PdfPen(PdfRGBColor(Color.get_Red()), 1.0)
page.Canvas.DrawLine(pen2, 50.0, 100.0, 225.0, 300.0)

# 恢复画布状态
page.Canvas.Restore(state)

# 保存文档
doc.SaveToFile("DrawLines.pdf")
doc.Close()

PdfPen 是绘制线条的核心工具，它决定了线条的颜色和宽度。DrawLine() 的前两个参数是起点坐标，后两个是终点坐标。需要注意的是，每次绘制前后通过 Save() 和 Restore() 保存和恢复画布状态是一个好习惯，可以避免后续操作影响之前的绘图设置。

绘制虚线

实际开发中，虚线常用于分隔区域或标注范围。通过设置画笔的 DashStyle 和 DashPattern 属性即可实现。

python 复制代码

# 创建红色画笔，线宽 3 点
pen = PdfPen(PdfRGBColor(Color.get_Red()), 3.0)

# 设置虚线样式
pen.DashStyle = PdfDashStyle.Dash
pen.DashPattern = [1, 4, 1]  # 虚线模式：1点实线、4点空白、1点实线

# 绘制虚线
page.Canvas.DrawLine(pen, 50.0, 200.0, 400.0, 200.0)

PdfDashStyle 枚举提供了预定义的虚线样式（Dash、Dot、DashDot 等），而 DashPattern 则允许自定义更精细的虚线模式------数组中的数字交替表示实线和空白的长度。

绘制矩形

矩形是文档标注中最常用的形状之一，可以绘制纯边框矩形或带填充色的矩形。

python 复制代码

# 绘制矩形边框
pen = PdfPen(PdfRGBColor(Color.get_Black()), 0.5)
# 参数：画笔、x、y、宽度、高度
page.Canvas.DrawRectangle(pen, 100.0, 150.0, 200.0, 120.0)

# 绘制带填充色的矩形
pen2 = PdfPen(PdfRGBColor(Color.get_Black()), 1.0)
brush = PdfSolidBrush(PdfRGBColor(Color.get_OrangeRed()))
rect = RectangleF(PointF(100.0, 300.0), SizeF(200.0, 120.0))
page.Canvas.DrawRectangle(pen2, brush, rect)

DrawRectangle() 有两种常见重载：一种只画边框，接受画笔和位置参数；另一种同时绘制填充色，需要额外传入 PdfBrush 对象。PdfSolidBrush 是最常用的填充画刷，使用单一颜色填充图形内部。

绘制椭圆

椭圆和圆形在流程图的辅助标注中比较常见，通过 DrawEllipse() 方法实现。

python 复制代码

# 绘制椭圆边框（以矩形边界定义椭圆范围）
pen = PdfPen(PdfRGBColor(Color.get_CadetBlue()), 1.0)
# 参数定义外接矩形的范围，椭圆会被绘制在该矩形内部
page.Canvas.DrawEllipse(pen, 220.0, 320.0, 100.0, 90.0)

# 绘制填充椭圆
brush = PdfSolidBrush(PdfRGBColor(Color.get_CadetBlue()))
page.Canvas.DrawEllipse(brush, 380.0, 325.0, 80.0, 80.0)

# 第三个和第四个参数分别控制水平半径和垂直半径
# 当两者相等时即为正圆
page.Canvas.DrawEllipse(brush, 100.0, 450.0, 50.0, 50.0)  # 这行会绘制一个正圆

椭圆本质上是由外接矩形定义的：外接矩形越接近正方形，椭圆就越接近正圆。这种方法与 HTML Canvas 中的椭圆绘制思路是相通的。

绘制自定义路径

对于五角星、多边形等复杂形状，可以使用 PdfPath 对象组合多条线段，再通过 DrawPath() 方法统一绘制。

python 复制代码

import math

# 计算五边形的五个顶点
points = [None] * 5
for i in range(5):
    x = float(math.cos(i * 2 * math.pi / 5))
    y = float(math.sin(i * 2 * math.pi / 5))
    points[i] = PointF(x, y)

# 创建路径并添加线段
path = PdfPath()
path.AddLine(points[2], points[0])
path.AddLine(points[0], points[3])
path.AddLine(points[3], points[1])
path.AddLine(points[1], points[4])
path.AddLine(points[4], points[2])

# 绘制路径轮廓
pen = PdfPen(PdfRGBColor(Color.get_DeepSkyBlue()), 0.02)
page.Canvas.ScaleTransform(50.0, 50.0)
page.Canvas.TranslateTransform(5.0, 5.0)
page.Canvas.DrawPath(pen, path)

# 绘制填充路径
brush = PdfSolidBrush(PdfRGBColor(Color.get_DeepSkyBlue()))
page.Canvas.DrawPath(pen, brush, path)

PdfPath 支持分段构建图形，通过 AddLine()、AddArc()、AddCurve() 等方法逐步组装。ScaleTransform() 和 TranslateTransform() 用于对坐标系统进行缩放和平移，方便在不同位置绘制相同形状。

控制图形透明度

透明度的控制让图形叠加时产生更丰富的视觉效果。通过 SetTransparency() 方法可以设置后续绘制的透明度。

python 复制代码

# 设置透明度（参数范围 0.0~1.0，0.0 完全透明，1.0 不透明）
page.Canvas.SetTransparency(0.5, 0.5)

# 在此之后绘制的图形将以 50% 透明度显示
pen = PdfPen(PdfRGBColor(Color.get_Black()), 1.0)
brush = PdfSolidBrush(PdfRGBColor(Color.get_Red()))
page.Canvas.DrawRectangle(pen, brush, RectangleF(PointF(200.0, 300.0), SizeF(200.0, 100.0)))

# 设置不同的透明度
page.Canvas.SetTransparency(0.2, 0.2)
page.Canvas.DrawRectangle(pen, brush, RectangleF(PointF(300.0, 250.0), SizeF(200.0, 100.0)))

透明度在多层图形叠加时尤其有用，比如在产品设计稿中区分不同层级的标注区域。

完整示例：综合绘制多种图形

以下代码将前面介绍的各种图形绘制操作整合到一个文档中，生成一个包含线条、矩形、椭圆和自定义路径的综合示例。

python 复制代码

from spire.pdf.common import *
from spire.pdf import *
import math

# 创建文档
doc = PdfDocument()
page = doc.Pages.Add()

# 保存画布状态
state = page.Canvas.Save()

# 1. 绘制直线
pen = PdfPen(PdfRGBColor(Color.get_Black()), 1.0)
page.Canvas.DrawLine(pen, 50.0, 50.0, 200.0, 50.0)

# 2. 绘制虚线
pen_dash = PdfPen(PdfRGBColor(Color.get_Red()), 2.0)
pen_dash.DashStyle = PdfDashStyle.Dash
page.Canvas.DrawLine(pen_dash, 50.0, 80.0, 200.0, 80.0)

# 3. 绘制矩形边框
pen_rect = PdfPen(PdfRGBColor(Color.get_Blue()), 1.0)
page.Canvas.DrawRectangle(pen_rect, 50.0, 120.0, 150.0, 100.0)

# 4. 绘制填充矩形
pen_fill = PdfPen(PdfRGBColor(Color.get_Black()), 0.5)
brush_fill = PdfSolidBrush(PdfRGBColor(Color.get_OrangeRed()))
page.Canvas.DrawRectangle(pen_fill, brush_fill, 
    RectangleF(PointF(50.0, 250.0), SizeF(150.0, 100.0)))

# 5. 绘制椭圆
brush_ellipse = PdfSolidBrush(PdfRGBColor(Color.get_CadetBlue()))
page.Canvas.DrawEllipse(brush_ellipse, 300.0, 120.0, 100.0, 80.0)

# 6. 绘制正圆
page.Canvas.DrawEllipse(brush_ellipse, 300.0, 250.0, 60.0, 60.0)

# 恢复画布状态
page.Canvas.Restore(state)

# 保存
doc.SaveToFile("ShapesDemo.pdf")
doc.Close()

输出文档预览：

总结

本文介绍了使用 Python 在 PDF 文档中绘制图形的基本方法，涵盖直线、虚线、矩形、椭圆和自定义路径等常见图形元素。在实际开发中，这些基础绘图能力可以组合应用到许多场景中------比如在报表中绘制表格线框、在设计稿中添加标注框、在证书模板中绘制装饰线条等。

掌握这些基础的图形绘制技巧后，可以继续探索更高级的绘图能力，例如渐变填充、图形变换和图层管理，以满足更复杂的文档处理需求。