详解 Qt QtPDF之QPdfPageNavigator 页面跳转

---

前言

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 文档中的当前位置、缩放和页面数据，增强了用户体验。