1. 项目概述
在Qt开发中,PDF文件生成是一个常见但颇具挑战性的任务。作为一名长期从事Qt开发的工程师,我经常需要为项目添加报表导出、公文生成等功能。经过多个项目的实践,我发现QPdfWriter配合QPainter是最灵活可靠的解决方案之一。
这个方案的核心优势在于:
- 完全控制PDF的每个细节,从页面布局到元素绘制
- 不依赖第三方库,纯Qt实现
- 支持从简单文本到复杂图形的各种绘制需求
- 跨平台兼容性好
本文将基于我最近完成的一个工业监测系统项目,详细解析如何使用QPdfWriter生成专业级的PDF文档。这个系统需要定期生成两种类型的PDF:
- 设备检测报告(含表格、图表和检测数据)
- 异常事件通报(仿公文格式,含红头、公章等元素)
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备与基础配置
2.1 项目配置
首先,确保项目已包含printsupport模块。在.pro文件中添加:
cmake复制QT += printsupport core gui
对于Qt6项目,还需要添加core5compat模块以保持兼容性:
cmake复制QT += core5compat
2.2 基础类介绍
QPdfWriter是Qt提供的PDF生成器,继承自QPagedPaintDevice。它的工作流程与QPrinter类似,但专门针对PDF输出做了优化。核心特点包括:
- 支持PDF/A标准(归档用PDF)
- 可设置文档元数据(作者、标题等)
- 支持高DPI输出
QPainter则是Qt的绘图引擎,它不仅可以绘制到屏幕和图像,也能绘制到PDF等打印设备上。
3. PDF生成核心流程
3.1 基本框架代码
一个最基础的PDF生成流程如下:
cpp复制void generateBasicPdf(const QString& filename) {
// 创建PDF写入器
QPdfWriter writer(filename);
// 设置页面属性
writer.setPageSize(QPageSize(QPageSize::A4));
writer.setPageOrientation(QPageLayout::Portrait);
// 设置页边距(单位:毫米)
QMarginsF margins(20, 15, 20, 15); // 左、上、右、下
writer.setPageMargins(margins, QPageLayout::Millimeter);
// 创建绘图器
QPainter painter(&writer);
painter.setRenderHint(QPainter::Antialiasing);
// 绘制内容...
painter.drawText(100, 100, "Hello, PDF!");
// 结束绘制
painter.end();
}
3.2 页面设置详解
在实际项目中,我们通常需要更精细的页面控制:
cpp复制// 设置PDF版本(默认为1.4)
writer.setPdfVersion(QPagedPaintDevice::PdfVersion_1_6);
// 设置文档信息
writer.setTitle("设备检测报告");
writer.setCreator("工业监测系统 v2.0");
// 设置分辨率(影响坐标单位)
writer.setResolution(300); // 300 DPI
// 自定义页面大小(单位:毫米)
QPageSize customSize(QSizeF(210, 297), QPageSize::Millimeter);
writer.setPageSize(customSize);
注意:DPI设置会影响所有绘制操作的坐标单位。例如在300 DPI下,300单位=1英寸=25.4毫米。
4. 实战绘制技巧
4.1 文本绘制
文本绘制是PDF生成中最常用的功能。Qt提供了多种文本绘制方式:
cpp复制// 基本文本绘制
QFont font("SimSun", 12); // 宋体12号
painter.setFont(font);
painter.drawText(100, 100, "静态文本");
// 带格式的文本绘制
QRect textRect(100, 120, 400, 200);
painter.drawText(textRect, Qt::AlignLeft | Qt::TextWordWrap,
"这是一段会自动换行的长文本...");
// 旋转文本
painter.save();
painter.translate(200, 200);
painter.rotate(45);
painter.drawText(0, 0, "旋转45度");
painter.restore();
对于中文支持,需要特别注意:
- 确保系统中安装了所需字体
- 避免使用生僻字体,优先使用系统自带字体(如SimSun、Microsoft YaHei)
- 测试在不同平台下的显示效果
4.2 图形绘制
QPdfWriter支持所有QPainter的绘图功能:
cpp复制// 绘制直线
painter.setPen(QPen(Qt::black, 2)); // 2像素宽的黑线
painter.drawLine(100, 100, 300, 100);
// 绘制矩形
painter.setBrush(QBrush(Qt::lightGray)); // 填充色
painter.drawRect(100, 120, 200, 100);
// 绘制圆形
painter.setPen(QPen(Qt::red, 3));
painter.drawEllipse(QPoint(200, 200), 50, 50);
// 绘制路径(复杂形状)
QPainterPath path;
path.moveTo(100, 300);
path.lineTo(150, 350);
path.quadTo(200, 400, 250, 350);
path.closeSubpath();
painter.drawPath(path);
4.3 表格绘制实战
表格是报表中最常见的元素。下面是一个通用的表格绘制函数:
cpp复制void drawTable(QPainter* painter, int startX, int startY,
const QStringList& headers,
const QVector<QStringList>& data) {
const int rowHeight = 30;
const int colWidth = 120;
const int headerHeight = 40;
// 绘制表头
painter->setFont(QFont("Microsoft YaHei", 10, QFont::Bold));
for(int col = 0; col < headers.size(); ++col) {
QRect cell(startX + col * colWidth, startY,
colWidth, headerHeight);
painter->drawRect(cell);
painter->drawText(cell, Qt::AlignCenter, headers[col]);
}
// 绘制数据行
painter->setFont(QFont("SimSun", 9));
for(int row = 0; row < data.size(); ++row) {
for(int col = 0; col < data[row].size(); ++col) {
QRect cell(startX + col * colWidth,
startY + headerHeight + row * rowHeight,
colWidth, rowHeight);
painter->drawRect(cell);
painter->drawText(cell, Qt::AlignCenter, data[row][col]);
}
}
}
使用示例:
cpp复制QStringList headers = {"ID", "设备名称", "状态", "最后检测"};
QVector<QStringList> data = {
{"001", "温度传感器", "正常", "2023-07-15"},
{"002", "压力表", "警告", "2023-07-14"}
};
drawTable(&painter, 100, 200, headers, data);
4.4 图片插入与处理
在PDF中插入图片需要注意以下几个要点:
cpp复制// 基本图片插入
QPixmap logo(":/images/company_logo.png");
painter.drawPixmap(100, 50, logo);
// 带缩放的图片插入
QPixmap chart(":/images/temperature_chart.png");
QRect chartR
