本教程详细讲解如何使用 pyside6/pyqt6 将 qwidget 内容以高分辨率导出为 pdf 文件，解决输出模糊问题。通过调整 qwidget 尺寸以匹配目标 dpi、正确配置 qprinter 的分辨率以及优化字体和元素大小，确保生成的 pdf 具有清晰专业的打印质量。
在 PySide6 或 PyQt6 应用程序中，将 QWidget 的内容导出为 PDF 是一种常见的需求，例如生成报表、发票或任何可视化文档。然而，开发者经常会遇到导出的 PDF 质量不佳、图像模糊的问题。这通常是由于屏幕显示分辨率与打印输出分辨率之间的差异未被正确处理所致。本教程将深入探讨如何通过精确控制 QWidget 尺寸、打印机设置以及 UI 元素样式，实现高分辨率的 PDF 输出。
问题分析：为什么导出的 PDF 会模糊？
QWidget.render() 方法默认情况下会以当前屏幕的 DPI 来渲染 QWidget 的内容。如果目标 PDF 的打印分辨率（例如 300 DPI）远高于屏幕分辨率（通常为 96 DPI 或 72 DPI），那么直接渲染会导致内容被“拉伸”，从而出现模糊。例如，A4 纸张在 96 DPI 下的像素尺寸约为 794x1123 像素，而在 300 DPI 下则为 2480x3508 像素。如果 QWidget 按照 96 DPI 的尺寸设计，然后强制以 300 DPI 打印，其内容就会显得不清晰。
解决此问题的关键在于确保 QWidget 在渲染时，其内部元素和整体尺寸能够适配目标 PDF 的高分辨率。
核心解决方案
要实现高分辨率的 QWidget 到 PDF 导出，需要关注以下三个关键点：
1. 调整 QWidget 尺寸以匹配打印分辨率
这是解决模糊问题的首要步骤。我们需要根据目标纸张尺寸和所需的打印 DPI 来计算 QWidget 的理想像素尺寸。以 A4 纸张为例：
- A4 尺寸： 210mm x 297mm
- 目标 DPI： 300 DPI (dots per inch)
- 换算： 1 英寸 = 25.4 毫米
计算 A4 纸张在 300 DPI 下的像素尺寸：
- 宽度 (像素) = (210 mm / 25.4 mm/inch) * 300 DPI ≈ 2480 像素
- 高度 (像素) = (297 mm / 25.4 mm/inch) * 300 DPI ≈ 3508 像素
因此，将 QWidget 的固定尺寸设置为 QSize(2480, 3508)，可以使其在渲染时拥有足够的像素信息来生成高质量的 A4 尺寸 300 DPI PDF。
from PySide6.QtCore import QSize
# ... 其他导入
class Example(QWidget):
def __init__(self):
super().__init__()
# 设置 QWidget 的固定尺寸为 A4 @ 300 DPI
self.setFixedSize(QSize(2480, 3508))
# ... 其他 UI 元素初始化2. 正确配置 QPrinter 分辨率
在 exportToPDF 方法中，除了设置纸张大小和输出格式外，必须明确设置 QPrinter 的分辨率。错误的做法是尝试使用 printer.PrinterMode.HighResolution，这只是一个枚举成员，并不能直接设置分辨率。正确的方法是使用 printer.setResolution()。
from PySide6.QtPrintSupport import QPrinter
from PySide6.QtGui import QPageSize
# ... 其他导入
class Example(QWidget):
# ... __init__ 方法
def exportToPDF(self, filename):
printer = QPrinter()
pageSize = QPageSize(QPageSize.A4)
printer.setPageSize(pageSize)
# 关键：设置打印机分辨率为 300 DPI
printer.setResolution(300)
printer.setOutputFormat(QPrinter.PdfFormat)
printer.setOutputFileName(filename)
self.render(printer)3. 优化 UI 元素和字体大小
当 QWidget 的尺寸从 96 DPI 对应的尺寸（例如 794x1123）大幅增加到 300 DPI 对应的尺寸（2480x3508）时，原有的字体大小和 UI 元素尺寸可能会变得非常小，难以阅读。因此，需要相应地调整字体大小和表格行高等。
例如，对于 QTableWidget，可以设置其整体字体、表头字体以及行高：
from PySide6.QtGui import QFont
from PySide6.QtWidgets import QTableWidget, QHeaderView, QTableWidgetItem
# ... 其他导入
class Example(QWidget):
def __init__(self):
super().__init__()
self.setFixedSize(QSize(2480, 3508))
self.table_widget = QTableWidget(35, 5, self)
self.table_widget.setHorizontalHeaderLabels(["Item", "Batch", "MRP", "Quantity", "Amount"])
# 调整表头字体大小
self.table_widget.horizontalHeader().setFont(QFont("Arial", 30))
# 调整表格内容字体大小
self.table_widget.setFont(QFont("Arial", 30))
# 调整垂直表头（行）的默认尺寸，以适应更大的字体
self.table_widget.verticalHeader().setDefaultSectionSize(100)
# 设置列宽模式
self.table_widget.horizontalHeader().setSectionResizeMode(0, QHeaderView.Stretch)
for i in range(1, 5): # 其他列根据内容自适应
self.table_widget.horizontalHeader().setSectionResizeMode(i, QHeaderView.ResizeMode.ResizeToContents)
# 填充表格数据
for i in range(0, 35):
for j in range(0, 5):
self.table_widget.setItem(i, j, QTableWidgetItem(f"Item Name_{i}_{j}"))
layout = QVBoxLayout()
layout.addWidget(self.table_widget)
self.setLayout(layout)完整示例代码
下面是一个整合了上述所有优化措施的 PySide6 示例，演示如何将一个包含 QTableWidget 的 QWidget 以高分辨率导出为 PDF。
import os
import datetime
from PySide6.QtCore import QSize
from PySide6.QtGui import QPageSize, QFont
from PySide6.QtWidgets import QApplication, QWidget, QTableWidget, QVBoxLayout, QTableWidgetItem, QHeaderView
from PySide6.QtPrintSupport import QPrinter
class Example(QWidget):
def __init__(self):
super().__init__()
# 1. 设置 QWidget 的固定尺寸以匹配 A4 300 DPI
self.setFixedSize(QSize(2480, 3508))
# 初始化 QTableWidget
self.table_widget = QTableWidget(35, 5, self)
self.table_widget.setHorizontalHeaderLabels(["Item", "Batch", "MRP", "Quantity", "Amount"])
# 3. 调整字体大小和表格元素尺寸以适应高分辨率
self.table_widget.horizontalHeader().setFont(QFont("Arial", 30))
self.table_widget.setFont(QFont("Arial", 30))
self.table_widget.verticalHeader().setDefaultSectionSize(100)
# 设置列宽模式
self.table_widget.horizontalHeader().setSectionResizeMode(0, QHeaderView.Stretch)
self.table_widget.horizontalHeader().setSectionResizeMode(1, QHeaderView.ResizeMode.ResizeToContents)
self.table_widget.horizontalHeader().setSectionResizeMode(2, QHeaderView.ResizeMode.ResizeToContents)
self.table_widget.horizontalHeader().setSectionResizeMode(3, QHeaderView.ResizeMode.ResizeToContents)
self.table_widget.horizontalHeader().setSectionResizeMode(4, QHeaderView.ResizeMode.ResizeToContents)
# 填充表格数据
for i in range(0, 35):
for j in range(0, 5):
self.table_widget.setItem(i, j, QTableWidgetItem(f"Item Name_{i}_{j}"))
# 设置布局
layout = QVBoxLayout()
layout.addWidget(self.table_widget)
self.setLayout(layout)
def exportToPDF(self, filename):
printer = QPrinter()
pageSize = QPageSize(QPageSize.A4)
printer.setPageSize(pageSize)
# 2. 关键：设置打印机分辨率为 300 DPI
printer.setResolution(300)
printer.setOutputFormat(QPrinter.PdfFormat)
printer.setOutputFileName(filename)
# 渲染 QWidget 到打印机设备
self.render(printer)
if __name__ == "__main__":
app = QApplication([])
example = Example()
example.show() # 可以选择不显示窗口，直接导出
# 生成带时间戳的文件名
pdf_filename = "invoice_" + datetime.datetime.now().strftime('%Y%m%d%H%M%S') + ".pdf"
example.exportToPDF(pdf_filename)
# 尝试打开生成的 PDF 文件
# 注意：os.system("start ...") 是 Windows 特有命令
# 在 Linux/macOS 上可能需要使用 'xdg-open' 或 'open'
try:
if os.name == 'nt': # Windows
os.system(f"start {pdf_filename}")
elif os.name == 'posix': # Linux or macOS
import platform
if platform.system() == 'Darwin': # macOS
os.system(f"open {pdf_filename}")
else: # Linux
os.system(f"xdg-open {pdf_filename}")
except Exception as e:
print(f"无法打开 PDF 文件: {e}")
app.exec()
注意事项与最佳实践
- DPI 换算： 始终记住屏幕 DPI 与打印 DPI 的差异。在设计用于打印的 QWidget 时，应以目标打印 DPI 为基准来计算尺寸。
-
动态内容与布局： 如果 QWidget 的内容是动态生成的，或者需要适应不同的纸张尺寸/DPI，硬编码尺寸可能不灵活。在这种情况下，可以考虑：
- 动态计算 QWidget 尺寸： 根据 QPrinter.pageRect() 或 QPageSize 结合 QPrinter.resolution() 动态设置 setFixedSize()。
- 使用布局管理器： 充分利用 QVBoxLayout, QHBoxLayout, QGridLayout 等布局管理器，它们在 QWidget 尺寸变化时能自动调整子控件的位置和大小。
- 字体缩放： 可以根据目标 DPI 与默认 DPI 的比值，对字体大小进行等比例缩放。
- 性能考虑： 渲染一个非常大的 QWidget（例如 2480x3508 像素）可能会消耗更多的内存和 CPU 资源。对于极其复杂的界面，可能需要优化渲染逻辑或考虑分块渲染。
- 测试： 在不同 DPI 设置下（例如 150 DPI, 600 DPI）测试输出效果，确保内容清晰且布局正确。
- QPrinter.setFullPage(True)： 如果希望 QWidget 内容占据整个页面，而忽略页边距，可以使用 printer.setFullPage(True)。但通常情况下，默认的页边距更符合打印习惯。
总结
通过本教程，我们了解了 PySide6/PyQt6 中将 QWidget 导出为高分辨率 PDF 的关键技术。核心在于：根据目标打印分辨率（如 300 DPI）精确计算并设置 QWidget 的像素尺寸，使用 QPrinter.setResolution() 方法明确指定打印分辨率，并相应地调整 QWidget 内部的字体和元素大小。遵循这些步骤，将能够生成清晰、专业的 PDF 文档，满足高质量打印的需求。
