详解 Qt WebEngine 模块

Qt WebEngine 模块是 Qt 提供的一个功能强大的模块，用于在 Qt 应用中嵌入和显示现代网页内容。该模块基于 Chromium 引擎，支持丰富的 Web 技术（如 HTML5、CSS3、JavaScript 等），适合需要嵌入网页浏览、Web 应用、JavaScript 交互等功能的桌面应用程序。

1. Qt WebEngine 的主要组件

Qt WebEngine 提供了一些核心类，用于网页显示、加载、交互等操作。以下是主要的类及其用途：

QWebEngineView：这是用于显示网页的主要控件类，继承自 QWidget。可以通过 QWebEngineView 进行网页加载、显示、导航等操作。
QWebEnginePage：代表一个网页内容的控制类，提供了网页内容和浏览控制的功能，如处理导航、管理 JavaScript 和 Cookie 访问等。
QWebEngineProfile：代表用户的 Web 浏览配置文件，管理 Cookie、缓存、历史记录和自定义设置。一个应用可以有多个 QWebEngineProfile，每个配置文件可以代表不同的用户。
QWebEngineSettings：用于配置 QWebEnginePage 或 QWebEngineProfile 的设置，允许启用或禁用功能（如 JavaScript、插件、图像加载等）。
QWebEngineScript：用于在网页加载时执行 JavaScript 脚本。可以设置为在页面加载前或加载后执行。
QWebEngineDownloadItem：管理下载项，允许追踪和控制下载进度、暂停和恢复下载等。

2. 如何在 Qt 中使用 `QWebEngineView`

步骤 1：在 `.pro` 文件中添加模块

要使用 Qt WebEngine，需要在 .pro 文件中包含 webenginewidgets 模块：

QT += webenginewidgets

步骤 2：代码示例

以下是一个简单的代码示例，展示如何使用 QWebEngineView 加载并显示一个网页：

#include <QApplication>
#include <QWebEngineView>

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    QWebEngineView view;
    view.setUrl(QUrl("https://www.qt.io"));  // 加载网页
    view.resize(1024, 768);
    view.show();

    return app.exec();
}

3. `Qt WebEngine` 的常用功能

加载网页

可以使用 QWebEngineView::setUrl() 或 QWebEnginePage::load() 方法加载网页。例如：

QWebEngineView *view = new QWebEngineView;
view->setUrl(QUrl("https://www.example.com"));

运行 JavaScript

可以通过 QWebEnginePage::runJavaScript() 方法在页面上运行 JavaScript 代码，并可以获取返回值。例如：

view->page()->runJavaScript("document.title", [](const QVariant &result){
    qDebug() << "Page title:" << result.toString();
});

处理页面导航

QWebEnginePage 提供了导航控制信号，例如 loadStarted()、loadProgress() 和 loadFinished()。可以通过这些信号实现加载进度条等功能。

connect(view->page(), &QWebEnginePage::loadFinished, [](bool ok) {
    if (ok) {
        qDebug() << "Page loaded successfully!";
    } else {
        qDebug() << "Failed to load page.";
    }
});

与 JavaScript 交互

可以使用 QWebChannel 将 C++ 对象暴露给网页，以便在 JavaScript 中调用。需要使用 qwebchannel.js 文件（在 Qt WebEngine 安装目录中找到）来启用此功能。

// 在 C++ 中
class WebBridge : public QObject {
    Q_OBJECT
public slots:
    void cppFunction() {
        qDebug() << "C++ function called from JavaScript!";
    }
};

// 将 C++ 对象暴露给 JavaScript
QWebEngineView *view = new QWebEngineView;
QWebChannel *channel = new QWebChannel(view->page());
WebBridge *bridge = new WebBridge();
channel->registerObject(QStringLiteral("bridge"), bridge);
view->page()->setWebChannel(channel);
view->setUrl(QUrl("qrc:/webpage.html"));  // 加载网页


// 在 JavaScript 中调用 C++ 函数（网页内容）
bridge.cppFunction();

自定义浏览设置

可以使用 QWebEngineSettings 配置是否启用 JavaScript、自动加载图像等。例如：

view->settings()->setAttribute(QWebEngineSettings::JavascriptEnabled, true);
view->settings()->setAttribute(QWebEngineSettings::AutoLoadImages, true);

文件下载管理

QWebEnginePage::profile() 可以获取 QWebEngineProfile 对象，从而管理下载。可以连接到 downloadRequested 信号处理下载：

connect(view->page()->profile(), &QWebEngineProfile::downloadRequested,
        [](QWebEngineDownloadItem *download) {
            download->setPath("path/to/save/file");
            download->accept();
        });

4. 注意事项

安装 `Qt WebEngine`

Qt WebEngine 并不是 Qt 的默认模块，在安装 Qt 时需要选中 Qt WebEngine 组件。如果已经安装 Qt，可以使用 Qt Maintenance Tool（维护工具）来添加 Qt WebEngine。

平台支持限制

Qt WebEngine 基于 Chromium 引擎，受限于一些平台，不支持 iOS，并且在嵌入式平台上可能需要额外的配置。

应用大小问题

由于包含 Chromium 引擎，Qt WebEngine 模块会显著增加应用程序的体积。对于不需要复杂 Web 功能的应用，可以考虑使用 QTextBrowser 或其他更轻量级的方案。

权限与安全

Qt WebEngine 支持访问文件系统、摄像头等功能，如果您的应用访问这些敏感数据，请注意权限管理和用户隐私保护。

5. 常用信号和槽

加载进度信号：
- loadStarted()：页面开始加载时发射。
- loadProgress(int progress)：加载进度发生变化时发射。
- loadFinished(bool ok)：页面加载完成时发射。
导航信号：
- urlChanged(const QUrl &url)：页面 URL 改变时发射。
- titleChanged(const QString &title)：页面标题改变时发射。
其他常用槽函数：
- back()、forward()、reload() 和 stop()：控制页面的导航。
- setZoomFactor(qreal factor)：设置页面的缩放因子。

6. 完整的 `Qt WebEngine` 应用示例

以下是一个完整的示例，包含了网页加载、JavaScript 运行、导航控制等基本功能：

#include <QApplication>
#include <QWebEngineView>
#include <QWebChannel>
#include <QPushButton>
#include <QVBoxLayout>
#include <QWidget>

class WebBridge : public QObject {
    Q_OBJECT
public slots:
    void cppFunction() {
        qDebug() << "C++ function called from JavaScript!";
    }
};

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    // 创建 WebEngineView 和 WebChannel
    QWebEngineView view;
    QWebChannel channel;
    WebBridge bridge;
    channel.registerObject(QStringLiteral("bridge"), &bridge);
    view.page()->setWebChannel(&channel);

    // 加载本地页面或在线页面
    view.setUrl(QUrl("https://www.qt.io"));
    view.resize(1024, 768);

    // 加载 JavaScript
    view.page()->runJavaScript("console.log('Hello from JavaScript');");

    // 创建控制按钮
    QWidget window;
    QVBoxLayout layout(&window);
    QPushButton backButton("Back");
    QPushButton forwardButton("Forward");
    layout.addWidget(&backButton);
    layout.addWidget(&forwardButton);
    layout.addWidget(&view);

    // 信号槽连接
    QObject::connect(&backButton, &QPushButton::clicked, &view, &QWebEngineView::back);
    QObject::connect(&forwardButton, &QPushButton::clicked, &view, &QWebEngineView::forward);

    window.show();

    return app.exec();
}

总结

Qt WebEngine 是一个功能强大的模块，适合需要网页显示和 JavaScript 交互的应用。其基于 Chromium 内核，支持现代 Web 技术（如 HTML5、JavaScript、CSS3），可以用于构建嵌入式浏览器或 Web 应用集成。通过丰富的信号槽机制和自定义配置，Qt WebEngine 可以满足大部分嵌入网页的需求。