详解 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_NAMESPACE

class Widget : public QWidget
{
    Q_OBJECT

public:
    Widget(QWidget *parent = nullptr);
    ~Widget();

private:
    Ui::Widget *ui;
};

class PdfViewer : public QWidget {
    Q_OBJECT

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