Qt实现将PDF文件转高清图片的完整指南
作者:小灰灰搞电子

一、源码分享
1、效果展示

2、源码分享
#include <QScreen>
#include <QPdfDocument>
#include <QPdfDocumentRenderOptions>
#include <QImage>
#include <QFile>
#include <QDir>
#include <QGuiApplication>
#include <QPainter>
#include "mainwindow.h"
#include "ui_mainwindow.h"
MainWindow::MainWindow(QWidget *parent)
: QMainWindow(parent)
, ui(new Ui::MainWindow)
{
ui->setupUi(this);
}
MainWindow::~MainWindow()
{
delete ui;
}
bool MainWindow::pdfToHighResImage(const QString &pdfPath,
const QString &imgPath,
QSize size,int dpi)
{
QPdfDocument doc;
auto err = doc.load(pdfPath);
if (err != QPdfDocument::Error::None)
{
qDebug() << "load pdf error code:" << err;
return false;
}
// 校验自定义尺寸
if (!size.isValid() || size.width() <= 0 || size.height() <= 0)
{
qDebug() << "input size width or height less zero!";
doc.close();
return false;
}
// 拆分路径,自动创建目录
QFileInfo imageFileInfo(imgPath);
// 获取后缀并判断格式
QString suffix = imageFileInfo.suffix().toLower();
QString imgFormat;
int quality = -1;
if (suffix == "png")
{
imgFormat = "PNG";
}
else if (suffix == "jpg" || suffix == "jpeg")
{
imgFormat = "JPG";
quality = 100; // jpg最高画质防模糊
}
else
{
qDebug() << "unsupported image extensions, only png / jpg / jpeg are supported!";
doc.close();
return false;
}
// 只转换第0页(如需指定页码可再加pageIndex参数)
int pageIdx = 0;
qDebug()<<doc.pagePointSize(pageIdx);
QPdfDocumentRenderOptions opts;
opts.setRenderFlags(QPdfDocumentRenderOptions::RenderFlag::None );
QImage img = doc.render(pageIdx, size, opts);
if (img.isNull())
{
qDebug() << "page " << pageIdx + 1 << " rendering failed!";
doc.close();
return false;
}
QImage whiteBgImg(size, QImage::Format_RGB32); // RGB无透明通道
whiteBgImg.fill(Qt::white); // 铺满纯白色背景
QPainter painter(&whiteBgImg);
painter.setRenderHints(QPainter::Antialiasing | QPainter::TextAntialiasing);
painter.drawImage(0, 0, img); // 将带透明的PDF图绘制到白底上
painter.end();
// 替换原img,后续保存用白底图
img = std::move(whiteBgImg);
int dotsPerMeter = qRound(dpi / 25.4 * 1000);
img.setDotsPerMeterX(dotsPerMeter);
img.setDotsPerMeterY(dotsPerMeter);
if (imgFormat == "PNG")
{
// PNG额外写入文本信息,看图软件可识别
img.setText("DPI", QString::number(dpi));
}
bool saveOk;
if (quality > 0)
saveOk = img.save(imgPath, imgFormat.toUtf8().data(), quality);
else
saveOk = img.save(imgPath, imgFormat.toUtf8().data());
if (!saveOk)
qDebug() << "failed to save the image:" << imgPath;
else
qDebug() << "success to save the image:" << imgPath;
doc.close();
return saveOk;
}
void MainWindow::on_pushButton_clicked()
{
pdfToHighResImage("L000137362.pdf", "L000137362.jpg", QSize(896,1534),300);
pdfToHighResImage("L000137362.pdf", "L000137362.png", QSize(896,1534),300);
}
在pro中添加pdf模块。

二、pdf模块详解
Qt6 引入了功能强大的 Qt PDF 模块,为开发者提供了原生、跨平台的 PDF 文档处理能力,无需依赖第三方库。该模块基于 Qt 的图形架构,能够高效地渲染、查看和打印 PDF 文件。
1、模块概述与引入
模块组成
Qt PDF 模块主要包含以下核心类:
- QPdfDocument: 用于加载、解析和获取 PDF 文档的元数据(如页数、作者、标题)及页面内容。它是操作 PDF 的入口。
- QPdfSelection: 处理文档中的文本选择。
- QPdfLink: 表示文档内的链接(如目录跳转、URL)。
- QPdfBookmarkModel: 提供文档书签(大纲)的模型,便于集成到树形视图。
- QPdfPageNavigator: 辅助进行页面导航。
此外,该模块还提供了与 Qt Widgets 和 Qt Quick 集成的便捷类:
- QQuickPdfDocument 和 QQuickPdfPage (Qt Quick)
- QPdfView (Qt Widgets): 一个功能完整的 PDF 查看器控件。
在项目中启用
在 Qt 项目文件 (.pro) 中,添加以下配置来引入 PDF 模块:
QT += pdf
对于 CMake 项目,则在 CMakeLists.txt 中链接对应的库:
find_package(Qt6 REQUIRED COMPONENTS Pdf) target_link_libraries(your_target PRIVATE Qt6::Pdf)
2、核心类详解
QPdfDocument
这是最核心的类,负责管理 PDF 文档的生命周期。
关键方法:
load(const QString &fileName)/load(QIODevice *device): 从文件或设备加载 PDF。status(): 返回加载状态 (QPdfDocument::Status)。pageCount(): 获取文档总页数。pagePointSize(int pageIndex): 获取指定页面的尺寸(以点为单位,1点=1/72英寸)。render(int pageIndex, QSize imageSize, QPdfDocumentRenderOptions options = QPdfDocumentRenderOptions()): 核心方法,将指定页面渲染为QImage。metaData(QPdfDocument::MetaDataField field): 获取文档元数据,如标题、作者。close(): 关闭文档,释放资源。
错误处理:load 方法返回 QPdfDocument::Error 枚举值,应检查是否为 QPdfDocument::Error::None。
QPdfDocumentRenderOptions
用于精细控制页面渲染过程。
常用设置:
setRenderFlags(QPdfDocumentRenderOptions::RenderFlags): 设置渲染标志,例如:RenderFlag::None: 默认。RenderFlag::Annotations: 渲染注释。RenderFlag::OptimizedForLcd: 为 LCD 屏幕优化。
setScaledSize(QSize size): 设置渲染输出的目标尺寸(像素)。如果与pagePointSize比例不一致,图像会被拉伸。
渲染流程与图像处理
- 加载文档:使用
QPdfDocument::load。 - 配置渲染:创建
QPdfDocumentRenderOptions对象并设置参数。 - 执行渲染:调用
doc.render(pageIndex, targetSize, options)获得QImage。 - 后处理:得到的
QImage可能包含透明背景(对应PDF空白区域)。如需白底,可将其绘制到另一个填充了白色的QImage上,如您分享的源码所示。 - 设置DPI:通过
QImage::setDotsPerMeterX/Y()设置图像分辨率,以控制打印或显示的物理尺寸精度。
3、高级应用与注意事项
- 多页处理:循环
pageCount()即可实现整个PDF的转换。 - 性能优化:渲染大尺寸或高DPI图像较耗时,建议在后台线程进行。
- 内存管理:及时调用
close()释放资源,尤其是在批量处理时。 - 与QPdfView集成:对于需要交互式查看的场景,直接使用
QPdfView控件更为简单,它内部封装了文档加载、渲染、缩放、导航等功能。 - 文本提取:
QPdfDocument目前主要专注于渲染。如需复杂的文本提取、搜索功能,可能需要结合其他库或等待Qt未来版本的增强。
4、 核心类与API表格
QPdfDocument
QPdfDocument是PDF文档的容器,用于加载、解析和访问PDF内容。
| 类别 | 方法/枚举 | 说明 |
|---|---|---|
| 文档加载与状态 | Error load(const QString &fileName) | 从文件加载PDF文档,返回错误码。 |
Error load(QIODevice *device) | 从IO设备加载PDF文档。 | |
void close() | 关闭当前文档,释放资源。 | |
bool isLoaded() const | 返回文档是否已成功加载。 | |
Error error() const | 返回最后一次操作的错误码。 | |
QString errorString() const | 返回错误描述字符串。 | |
Status status() const | 返回文档的当前状态(Null、Loading、Ready、Unloading、Error)。 | |
| 页面信息 | int pageCount() const | 返回文档的总页数。 |
QSizeF pagePointSize(int pageIndex) const | 返回指定页面的尺寸(以点为单位,1点=1/72英寸)。 | |
QSizeF pageSize(int pageIndex) const | 返回指定页面的尺寸(以毫米为单位)。 | |
QString metaData(QPdfDocument::MetaDataField field) const | 获取文档元数据,如标题、作者、主题等。 | |
| 渲染 | QImage render(int pageIndex, const QSize &imageSize, const QPdfDocumentRenderOptions &options = QPdfDocumentRenderOptions()) | 将指定页面渲染为QImage。 |
QImage render(int pageIndex, const QSizeF &size, const QPdfDocumentRenderOptions &options = QPdfDocumentRenderOptions()) | 重载版本,接受QSizeF尺寸。 | |
| 导航与书签 | QPdfBookmarkModel *bookmarkModel() const | 返回书签模型,用于文档导航。 |
QPdfLinkModel *linkModel(int page) const | 返回指定页面的链接模型。 | |
| 信号 | void statusChanged(QPdfDocument::Status status) | 文档状态改变时发出。 |
void pageCountChanged(int pageCount) | 页数改变时发出。 | |
void errorChanged(QPdfDocument::Error error, const QString &description) | 发生错误时发出。 | |
void passwordRequired() | 需要密码解密时发出。 |
QPdfDocumentRenderOptions
QPdfDocumentRenderOptions用于配置页面渲染的选项,如缩放模式、旋转、裁剪等。
| 选项 | 方法 | 说明 |
|---|---|---|
| 缩放模式 | void setScaledClipRect(const QRectF &rect) | 设置裁剪矩形(相对于页面尺寸的比例,0-1)。 |
QRectF scaledClipRect() const | 获取设置的裁剪矩形。 | |
void setScaledSize(const QSizeF &size) | 设置渲染的目标尺寸(以点为单位)。 | |
QSizeF scaledSize() const | 获取目标尺寸。 | |
| 旋转 | void setRotation(QPdfDocumentRenderOptions::Rotation rotation) | 设置页面旋转角度(0°、90°、180°、270°)。 |
Rotation rotation() const | 获取旋转设置。 | |
| 渲染标志 | void setRenderFlags(RenderFlags flags) | 设置渲染标志(如反走样、文本反走样等)。 |
RenderFlags renderFlags() const | 获取渲染标志。 | |
| 颜色模式 | void setColorMode(ColorMode mode) | 设置颜色模式(Color、Grayscale、Monochrome)。 |
ColorMode colorMode() const | 获取颜色模式。 |
QPdfBookmarkModel
用于表示PDF文档的书签(目录)结构,通常与QTreeView等视图组件配合使用。
| 方法 | 说明 |
|---|---|
QVariant data(const QModelIndex &index, int role) const override | 获取书签项的数据(如标题、页码)。 |
QModelIndex parent(const QModelIndex &child) const override | 返回父节点的索引。 |
int rowCount(const QModelIndex &parent = QModelIndex()) const override | 返回子项数量。 |
int columnCount(const QModelIndex &parent = QModelIndex()) const override | 返回列数(通常为1)。 |
QModelIndex index(int row, int column, const QModelIndex &parent = QModelIndex()) const override | 创建索引。 |
QPdfLinkModel
表示PDF页面中的链接(超链接、文档内部跳转等)。
| 方法 | 说明 |
|---|---|
QVariant data(const QModelIndex &index, int role) const override | 获取链接数据(如URL、目标页码、矩形区域)。 |
int rowCount(const QModelIndex &parent = QModelIndex()) const override | 返回链接数量。 |
QModelIndex parent(const QModelIndex &child) const override | 返回父节点索引(通常为无效索引)。 |
QModelIndex index(int row, int column, const QModelIndex &parent = QModelIndex()) const override | 创建索引。 |
5. 总结
Qt6 的 PDF 模块为桌面和嵌入式应用处理 PDF 提供了官方、高效的一站式解决方案。其核心在于 QPdfDocument 的加载与渲染能力。通过 render() 方法获取 QImage 后,开发者可以灵活地进行后续的图像处理、保存或显示。本文详解了其核心类与典型工作流程,并提供了可直接使用的代码示例。
以上就是Qt实现将PDF文件转高清图片的完整指南的详细内容,更多关于Qt PDF转图片的资料请关注脚本之家其它相关文章!
