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

日常工作里，PDF 是文档分发和存档的“铁打”格式——跨平台打开，排版不乱。但光有文字往往不够，很多时候需要在文档里加一些视觉元素：比如画条分隔线、标个矩形区域、加个形状装饰。不管是给报表做区域划分，还是给设计稿画原型元素，编程绘制图形都是一项基础又实用的能力。

这篇就来聊聊，怎么用 Python 在 PDF 里画出常见的图形：直线、矩形、椭圆，还有更复杂的自定义路径。

为什么需要编程绘制图形

通过代码在 PDF 里画图，和手动操作比起来，有几个明显的好处：

• 精确控制 — 坐标、尺寸、颜色、透明度都能用参数精确定义，不用怕手抖拖歪了。
• 批量生成 — 配合循环和条件判断，一次性生成大量带图形的文档，效率拉满。
• 动态内容 — 根据数据源自动调整图形的位置和样式，做报表和模板特别顺手。

环境准备

这里用 Spire.PDF 这个库来创建 PDF 和画图。安装很简单：

 复制代码pip install Spire.PDF

这个库覆盖了 PDF 的完整操作，包括页面管理、图形绘制、文字渲染，该有的都有。

绘制基本图形

Spire.PDF 通过 PdfCanvas 对象提供了一系列绘制方法，所有绘图都在页面的画布（Canvas）上进行。画布用坐标系定位，原点在页面左下角，单位是点（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 允许自定义更精细的虚线模式——数组里的数字交替表示实线和空白的长度，灵活度很高。

绘制矩形

矩形是文档标注里最常用的形状之一，可以只画边框，也可以带填充色。

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

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