详解 Qt QtPDF之QPdfPageNavigator 页面跳转

文章目录

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

前言

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

头文件：

cpp 复制代码

#include <QPdfPageNavigator>

自 Qt 6.4 起

继承自：

QObject

属性

`backAvailable : const bool`

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

访问函数：
cpp 复制代码
```
bool backAvailable() const
```

通知信号：

cpp 复制代码

void backAvailableChanged(bool available)

`currentLocation : const QPointF`

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

访问函数：
cpp 复制代码
```
QPointF currentLocation() const
```

通知信号：

cpp 复制代码

void currentLocationChanged(QPointF location)

`currentPage : const int`

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

访问函数：
cpp 复制代码
```
int currentPage() const
```
通知信号：
cpp 复制代码
```
void currentPageChanged(int page)
```

`currentZoom : const qreal`

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

访问函数：
cpp 复制代码
```
qreal currentZoom() const
```
通知信号：
cpp 复制代码
```
void currentZoomChanged(qreal zoom)
```

`forwardAvailable : const bool`

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

访问函数：
cpp 复制代码
```
bool forwardAvailable() const
```

通知信号：

cpp 复制代码

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()），会发出此信号。此信号提供当前目的地的详细信息，包括页面、位置和缩放级别。

示例代码

cpp 复制代码

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