当前位置：首页 > news >正文

详解 Qt QtPDF之QPdfPageNavigator 页面跳转

news 来源：原创 2025/5/12 23:00:33

文章目录

前言
- - 头文件：
- 自 Qt 6.4 起
- 继承自：
属性
- `backAvailable : const bool`
- `currentLocation : const QPointF`
- `currentPage : const int`
- `currentZoom : const qreal`
- `forwardAvailable : const bool`
公共函数
- `QPdfPageNavigator(QObject *parent)`
- `virtual ~QPdfPageNavigator() override`
- `bool backAvailable() const`
- `QPointF currentLocation() const`
- `int currentPage() const`
- `qreal currentZoom() const`
公共槽函数
- `void back()`
- `void clear()`
- `void forward()`
- `void jump(int page, const QPointF &location, qreal zoom = 0)`
- `void jump(QPdfLink destination)`
- `void update(int page, const QPointF &location, qreal zoom)`
信号
- `void backAvailableChanged(bool available)`
- `void currentLocationChanged(QPointF location)`
- `void currentPageChanged(int page)`
- `void currentZoomChanged(qreal zoom)`
- `void forwardAvailableChanged(bool available)`
- `void jumped(QPdfLink current)`
示例代码
总结

前言

QPdfPageNavigator 类提供了在 PDF 文档中进行导航的功能，类似于网页浏览器中的“后退”和“前进”按钮。它允许用户在 PDF 文档中浏览页面，并记住页面的位置和缩放级别历史。此类可用于实现如后退、前进、跳转到文档中特定位置等功能。

头文件：

#include <QPdfPageNavigator>

自 Qt 6.4 起

继承自：

QObject

属性

`backAvailable : const bool`

此属性返回 true，如果在导航历史中存在可以后退的目的地。这表示在调用 push() 或 forward() 后，用户可以向后导航到先前的页面和位置。

访问函数：
```
bool backAvailable() const
```

通知信号：

void backAvailableChanged(bool available)

`currentLocation : const QPointF`

此属性保存当前正在查看的页面的位置，它记录了最后一次传递给 jump() 或 update() 的位置。默认值为 (0, 0)，表示页面的左上角。

访问函数：
```
QPointF currentLocation() const
```

通知信号：

void currentLocationChanged(QPointF location)

`currentPage : const int`

此属性保存当前正在查看的页面的索引，默认值为 0，表示第一页。

访问函数：
```
int currentPage() const
```
通知信号：
```
void currentPageChanged(int page)
```

`currentZoom : const qreal`

此属性保存当前页面的缩放级别。值为 1 表示默认缩放级别，1 个逻辑像素等于 1 个点。默认值为 1。

访问函数：
```
qreal currentZoom() const
```
通知信号：
```
void currentZoomChanged(qreal zoom)
```

`forwardAvailable : const bool`

此属性返回 true，如果在导航历史中存在可以前进的目的地。这表示在调用 back() 后，用户可以向前导航到更近期的位置。

访问函数：
```
bool forwardAvailable() const
```

通知信号：

void forwardAvailableChanged(bool available)

公共函数

`QPdfPageNavigator(QObject *parent)`

构造函数，使用指定的父对象构建一个页面导航堆栈。此构造函数初始化导航器来跟踪页面、位置和缩放级别的历史记录。

`virtual ~QPdfPageNavigator() override`

析构函数，销毁页面导航堆栈，释放所有分配的资源。

`bool backAvailable() const`

返回 true，如果在导航历史中存在后退的目的地，表示用户可以返回到先前的页面和位置。

`QPointF currentLocation() const`

返回当前查看页面的位置信息。这是最后一次调用 jump() 或 update() 时的位置。

`int currentPage() const`

返回当前查看的页面索引，表示用户当前所在的页面。

`qreal currentZoom() const`

返回当前页面的缩放级别，表示页面的缩放倍率。

公共槽函数

`void back()`

此槽函数从导航历史中弹出一个目的地，更新 currentPage、currentLocation 和 currentZoom 属性为最近访问的目的地，然后发出 jumped() 信号。

`void clear()`

清除导航历史，并将 currentPage、currentLocation 和 currentZoom 属性恢复为默认值。此操作相当于重置导航历史。

`void forward()`

此槽函数使视图返回到上次调用 back() 之前查看的页面、位置和缩放级别，并发出 jumped() 信号。如果自上次调用 back() 后有新的目的地被添加到历史中，forward() 将不会执行，因为这会在导航历史中创建一个分支，导致“未来”的目标丢失。

`void jump(int page, const QPointF &location, qreal zoom = 0)`

此槽函数将给定的目的地（由页面、位置和缩放级别组成）添加到导航历史中。如果未指定 zoom 参数或其值为 0，则保留当前的缩放级别。此函数通常用于用户跳转到文档中的特定页面和位置，例如点击超链接或搜索结果。

`void jump(QPdfLink destination)`

此槽函数将指定的 QPdfLink 目的地添加到导航历史中。适用于跳转到超链接或搜索结果。QPdfLink 对象的 rectangles 属性用于定义应该在视口中显示的区域。

`void update(int page, const QPointF &location, qreal zoom)`

此函数用于更新当前目的地，包括页面、位置和缩放级别。通常在用户手动移动文档时调用，以便在调用 back() 后，forward() 会跳转到最后查看的目的地，而不是历史中最后一个指定的目的地。与 jump() 不同，调用 update() 不会触发 jumped() 信号，因为它表示平滑的滚动而不是跳转到新的位置。

信号

`void backAvailableChanged(bool available)`

当后退目的地的可用性发生变化时发出此信号，指示用户是否可以向后导航。

`void currentLocationChanged(QPointF location)`

当当前页面位置发生变化时发出此信号，指示用户跳转到新的位置或更新了当前位置。

`void currentPageChanged(int page)`

当当前页面发生变化时发出此信号，指示用户跳转到新的页面。

`void currentZoomChanged(qreal zoom)`

当页面的缩放级别发生变化时发出此信号，指示用户调整了缩放比例。

`void forwardAvailableChanged(bool available)`

当前进目的地的可用性发生变化时发出此信号，指示用户是否可以向前导航。

`void jumped(QPdfLink current)`

当用户跳转到新的目的地时（例如调用 back()、forward()、jump() 或 update()），会发出此信号。此信号提供当前目的地的详细信息，包括页面、位置和缩放级别。

示例代码

#ifndef WIDGET_H
#define WIDGET_H#include <QWidget>
#include <QPdfDocument>
#include <QPdfView>
#include <QVBoxLayout>
#include <QFileDialog>
#include <QPushButton>
#include <QLabel>
#include <QTreeView>
#include <QPdfBookmarkModel>
#include <QPdfPageNavigator>QT_BEGIN_NAMESPACE
namespace Ui {
class Widget;
}
QT_END_NAMESPACEclass Widget : public QWidget
{Q_OBJECTpublic:Widget(QWidget *parent = nullptr);~Widget();private:Ui::Widget *ui;
};class PdfViewer : public QWidget {Q_OBJECTpublic:PdfViewer(QWidget *parent = nullptr) : QWidget(parent) {// 创建布局管理器QVBoxLayout *layout = new QVBoxLayout(this);// 添加控件QLabel *label = new QLabel("请选择 PDF 文件：", this);QPushButton *loadButton = new QPushButton("加载 PDF", this);pdfView = new QPdfView(this);// 设置初始布局layout->addWidget(label);layout->addWidget(loadButton);layout->addWidget(pdfView);// 创建 PDF 文档对象pdfDocument = new QPdfDocument(this);// 创建 QPdfBookmarkModel，并将 pdfDocument 设置给它bookmarkModel = new QPdfBookmarkModel(this);// 创建 QTreeView 来显示书签QTreeView *bookmarkView = new QTreeView(this);bookmarkView->setModel(bookmarkModel); // 设置书签模型layout->addWidget(bookmarkView);// 连接按钮信号槽connect(loadButton, &QPushButton::clicked, this, &PdfViewer::loadPdf);QPushButton *next = new QPushButton("next",this);connect(next, &QPushButton::clicked, this, [=](){page++;navigator->jump(page,navigator->currentLocation());});setLayout(layout);  // 设置主布局}private slots:void loadPdf() {// 打开文件选择对话框QString fileName = QFileDialog::getOpenFileName(this, "打开 PDF 文件", "", "PDF Files (*.pdf)");if (fileName.isEmpty()) return;// 加载 PDF 文档if (pdfDocument->load(fileName) == QPdfDocument::Error::None) {// 设置 pdfView 显示加载的文档pdfView->setDocument(pdfDocument);// 设置书签模型与文档bookmarkModel->setDocument(pdfDocument);// 您可以设置 pdfView 显示第一页navigator = pdfView->pageNavigator();} else {qWarning() << "无法加载 PDF 文件：" << fileName;}}private:QPdfDocument *pdfDocument;        // PDF 文档对象QPdfView *pdfView;                // PDF 视图组件QPdfBookmarkModel *bookmarkModel;  // 书签模型QPdfPageNavigator* navigator;int page = 1;
};#endif // WIDGET_H

总结

QPdfPageNavigator 类用于记录用户在 PDF 文档中的浏览历史。它允许用户在文档中前后导航，并保持页面、位置和缩放级别的历史记录。此类特别适合实现 PDF 查看器中的后退、前进和跳转到特定位置等功能，类似于网页浏览器中的历史记录。

该类确保用户的浏览体验流畅，提供了返回先前位置或跳转到更近期位置的能力。QPdfPageNavigator 类通常与 QPdfView 一起使用，提供交互式的 PDF 查看体验。

此外，QPdfPageNavigator 还支持跳转到文档中的特定位置，诸如由链接或搜索结果标记的区域。缩放功能的加入使其成为构建丰富 PDF 查看应用程序的有力工具，支持详细的导航和探索。

总之，QPdfPageNavigator 通过管理导航历史，提供后退和前进控制，并保持 PDF 文档中的当前位置、缩放和页面数据，增强了用户体验。

文章目录

前言

头文件：

自 Qt 6.4 起

继承自：

属性

backAvailable : const bool

currentLocation : const QPointF

currentPage : const int

currentZoom : const qreal

forwardAvailable : const bool

公共函数

QPdfPageNavigator(QObject *parent)

virtual ~QPdfPageNavigator() override

bool backAvailable() const

QPointF currentLocation() const

int currentPage() const

qreal currentZoom() const

公共槽函数

void back()

void clear()

void forward()

void jump(int page, const QPointF &location, qreal zoom = 0)

void jump(QPdfLink destination)

void update(int page, const QPointF &location, qreal zoom)

信号

void backAvailableChanged(bool available)

void currentLocationChanged(QPointF location)

void currentPageChanged(int page)

void currentZoomChanged(qreal zoom)

void forwardAvailableChanged(bool available)

void jumped(QPdfLink current)

示例代码

总结

相关文章：

`backAvailable : const bool`

`currentLocation : const QPointF`

`currentPage : const int`

`currentZoom : const qreal`

`forwardAvailable : const bool`

`QPdfPageNavigator(QObject *parent)`

`virtual ~QPdfPageNavigator() override`

`bool backAvailable() const`

`QPointF currentLocation() const`

`int currentPage() const`

`qreal currentZoom() const`

`void back()`

`void clear()`

`void forward()`

`void jump(int page, const QPointF &location, qreal zoom = 0)`

`void jump(QPdfLink destination)`

`void update(int page, const QPointF &location, qreal zoom)`

`void backAvailableChanged(bool available)`

`void currentLocationChanged(QPointF location)`

`void currentPageChanged(int page)`

`void currentZoomChanged(qreal zoom)`

`void forwardAvailableChanged(bool available)`

`void jumped(QPdfLink current)`