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

在日常文档处理工作中，PDF格式以跨平台一致性成为分发和存档的首选，这已经是行业共识。但很多时候，一张PDF文档里只有干巴巴的文字，远远不够用。比如，需要画一条分隔线把报表区域划分清楚，或者在设计稿里标注某个矩形范围，再或者是加个小小的形状装饰让页面更专业。这些需求，如果能用代码自动化生成，效率会提升不少。

这篇文章就来聊聊，怎么用Python这个强大的工具，在PDF文档里画直线、矩形、椭圆，甚至更复杂的自定义图形。

为什么需要编程绘制图形

那么，为什么需要用代码来完成这件事？相比手动操作，编程绘制图形有几个实打实的优势：

• 精确控制 - 图形的坐标、尺寸、颜色和透明度全部通过参数精确定义，避免了手动拖动带来的偏差，这在批量生成时尤其重要。
• 批量生成 - 结合循环和条件逻辑，可以一次性生成成千上万份带有图形元素的文档，比如带有动态标注的报表。
• 动态内容 - 根据数据源自动调整图形的位置和样式，非常适合模板化和报表场景，比如根据数据值自动调整矩形的高度。

环境准备

要实现这些功能，我们用到的库是Spire.PDF，一个功能完整的PDF操作库。装起来也很简单，一行命令搞定：

pip install Spire.PDF

这个库提供了页面管理、图形绘制、文字渲染等全套能力，画图只是它的一部分。

绘制基本图形

在Spire.PDF中，所有绘图操作都在页面的PdfCanvas对象上完成。画布使用的是标准的坐标系，原点在页面左下角，单位是点（point，1点 = 1/72英寸）。这个坐标系是理解所有绘图操作的基础。

绘制直线

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

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

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

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

# 创建画笔（黑色，线宽 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.Sa veToFile("DrawLines.pdf")
doc.Close()

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

绘制虚线

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

# 创建红色画笔，线宽 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则允许自定义更精细的虚线模式，比如数组[1, 4, 1]表示1点实线、4点空白、1点实线，以此类推。

绘制矩形

矩形是文档标注中最常用的形状之一，没有之一。可以绘制纯边框矩形，也可以同时绘制填充色。

# 绘制矩形边框
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()方法实现。

# 绘制椭圆边框（以矩形边界定义椭圆范围）
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()方法统一绘制。

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()方法可以设置后续绘制的透明度。

# 设置透明度（参数范围 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)))

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

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

下面的代码集成了前面介绍的所有操作，生成一个包含线条、虚线、矩形、椭圆和自定义路径的综合示例。

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

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

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

# 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.Sa veToFile("ShapesDemo.pdf")
doc.Close()

输出文档预览：

总结

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

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