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

本文围绕使用 Python 在 PDF 中绘制线条、矩形和自定义图形实战解析展开，先梳理核心概念，再结合实践场景说明步骤、代码思路和容易忽略的细节，方便后续直接参考。

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

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

为什么需要编程绘制图形

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

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

环境准备

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

 复制代码pip install Spire.PDF 

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

绘制基本图形

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

绘制直线

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

 复制代码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 属性即可实现。

 复制代码# 创建红色画笔，线宽 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 则允许自定义更精细的虚线模式——数组中的数字交替表示实线和空白的长度。

绘制矩形

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

 复制代码# 绘制矩形边框 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.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 文档中绘制图形的基本方法，涵盖直线、虚线、矩形、椭圆和自定义路径等常见图形元素。在实际开发中，这些基础绘图能力可以组合应用到许多场景中——比如在报表中绘制表格线框、在设计稿中添加标注框、在证书模板中绘制装饰线条等。

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

实际使用时，建议结合项目规模、依赖环境和团队习惯做取舍；先保证流程清晰和结果可验证，再逐步优化细节。