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

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

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

为什么需要编程绘制图形

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

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

环境准备

本文使用 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()

输出文档预览：