PySide6/PyQt高分辨率PDF打印：QWidget内容导出优化指南

本教程旨在解决pyside6/pyqt应用中将qwidget内容导出为pdf时出现的模糊问题。通过调整qwidget的固定尺寸以匹配目标打印分辨率（如a4纸张在300 dpi下的像素尺寸）、显式设置qprinter的输出分辨率，以及优化ui元素的字体大小和布局，可以显著提升生成pdf的清晰度，确保高质量的打印输出。

理解QWidget打印PDF模糊问题

在使用PySide6或PyQt将QWidget的内容渲染到PDF时，如果直接使用默认设置，常常会遇到生成的PDF文档内容模糊不清的问题。这主要是因为QWidget的默认渲染尺寸可能与QPrinter的输出分辨率不匹配。QWidget在屏幕上显示时，通常以屏幕DPI（每英寸点数）进行渲染。当这个低分辨率的渲染结果被直接“拉伸”到高DPI的打印输出（如300 DPI或更高）时，就会出现像素化和模糊。为了获得高质量的PDF输出，我们需要确保QWidget在被渲染到QPrinter之前，其内部的绘制尺寸和细节能够与目标打印分辨率相匹配。

核心解决方案策略

要实现高质量的PDF输出，关键在于确保QWidget在被渲染到QPrinter之前，其内部的绘制尺寸和细节能够与目标打印分辨率相匹配。这主要涉及以下三个方面的优化：

1. 调整QWidget尺寸以匹配目标DPI

将QWidget的固定尺寸设置为目标纸张尺寸在高DPI下的像素等效值，是解决模糊问题的核心步骤。例如，以A4纸张为例，如果目标打印DPI为300：

• A4纸张尺寸：210毫米 (宽) x 297毫米 (高)
• 目标DPI：300 DPI (dots per inch)
• 单位换算：1英寸 = 25.4毫米

我们可以计算出A4纸张在300 DPI下的像素尺寸：

• 宽度（像素） = (210毫米 / 25.4毫米/英寸) * 300 DPI ≈ 2480 像素
• 高度（像素） = (297毫米 / 25.4毫米/英寸) * 300 DPI ≈ 3508 像素

因此，将QWidget的固定尺寸设置为(2480, 3508)，可以使其在渲染时拥有足够的像素细节，从而避免在打印时被拉伸导致模糊。

from PySide6.QtCore import QSize

self.setFixedSize(QSize(2480, 3508))

2. 设置打印机输出分辨率

仅仅调整QWidget的尺寸是不够的，还需要明确告诉QPrinter以高分辨率进行输出。QPrinter提供了setResolution()方法来设置输出DPI。

Krea AI

多功能的一站式AI图像生成和编辑平台

下载

from PySide6.QtPrintSupport import QPrinter
from PySide6.QtGui import QPageSize

printer = QPrinter()
pageSize = QPageSize(QPageSize.A4)
printer.setPageSize(pageSize)
printer.setResolution(300) # 显式设置为300 DPI
printer.setOutputFormat(QPrinter.PdfFormat)
printer.setOutputFileName(filename)

# 渲染QWidget到QPrinter
self.render(printer)

重要提示：在旧版代码中，可能会见到 printer.PrinterMode.HighResolution 这样的尝试。PrinterMode 是一个枚举类型，不能直接作为设置分辨率的方法使用。正确的做法是调用 setResolution() 方法并传入具体的DPI值。

3. 优化UI元素字体与布局

当QWidget的尺寸大幅增加以适应高分辨率打印时，其内部的字体、图标和布局元素可能会显得过小。为了在高分辨率PDF中保持良好的可读性和视觉效果，需要相应地调整这些元素的尺寸。

例如，对于QTableWidget：

• 字体大小：增大表头和单元格的字体大小，使其在高分辨率下依然清晰可读。
• 行高与列宽：调整行高和列宽，确保内容不会显得过于拥挤或留白过多。
• SectionResizeMode：合理设置列的伸缩模式，使其在高分辨率下也能良好布局。

from PySide6.QtGui import QFont
from PySide6.QtWidgets import QHeaderView

# 调整表头字体
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)
# ... 可以对其他列进行类似的调整

完整示例代码

以下是一个结合上述所有优化措施的完整示例，演示如何将一个包含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@300DPI的像素尺寸
        # A4纸张在300 DPI下约为 2480x3508 像素
        self.setFixedSize(QSize(2480, 3508)) 

        # 初始化QTableWidget，增加行数以适应高分辨率画布
        self.table_widget = QTableWidget(35, 5, self)
        self.table_widget.setHorizontalHeaderLabels(["Item", "Batch", "MRP", "Quantity", "Amount"])

        # 3. 优化UI元素字体与布局
        self.table_widget.horizontalHeader().setFont(QFont("Arial", 30)) # 增大表头字体
        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)
        self.table_widget.verticalHeader().setDefaultSectionSize(100) # 增大行高
        self.table_widget.setFont(QFont("Arial", 30)) # 增大单元格字体

        # 填充表格数据
        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到QPrinter
        self.render(printer)


if __name__ == "__main__":
    app = QApplication([])

    example = Example()
    example.show() # 在实际应用中，如果仅需导出PDF，可以不显示窗口

    # 生成带时间戳的PDF文件名
    filename = "invoice_" + datetime.datetime.now().strftime('%Y%m%d%H%M%S') + ".pdf"
    example.exportToPDF(filename)

    # 尝试打开生成的PDF文件（跨平台兼容性处理）
    try:
        if os.name == 'nt': # Windows系统
            os.system(f"start {filename}")
        elif os.name == 'posix': # Linux或macOS系统
            if os.uname().sysname == 'Linux':
                os.system(f"xdg-open {filename}")
            else: # macOS
                os.system(f"open {filename}")
    except Exception as e:
        print(f"无法自动打开PDF文件: {e}")

    app.exec()

注意事项与最佳实践

• DPI选择：300 DPI是文档打印的常用标准，适用于大多数高质量输出需求。如果需要更高精度的图像或专业印刷，可以尝试更高的DPI（如600 DPI），但这会显著增加文件大小和渲染时间。
• 动态内容与布局：对于内容动态变化的QWidget，可能需要更复杂的布局管理策略。