第29章 Qt WebEngine

课程目录第29章 Qt WebEngine

第29章 Qt WebEngine：WebEngineView、JavaScript交互、网页加载控制、开发者工具、混合应用开发

说实话，我第一次在Qt里嵌入网页时，用的是古老的QWebKit。那时候内存泄漏、崩溃、兼容性问题，简直让人头大。后来Qt推出了WebEngine模块，基于Chromium内核，稳定性和性能都上了一个台阶。这一章，我就带你彻底搞懂Qt WebEngine。

WebEngine说白了，就是把一个完整的浏览器内核塞进你的Qt应用里。你可以用它显示网页、与JavaScript互相调用、甚至开发混合应用——也就是原生界面+网页内容的组合。我参与过好几个项目，都是用这套方案做的。

核心知识点一览：

QWebEngineView：显示网页的控件
JavaScript与C++双向交互
网页加载控制与进度监听
开发者工具（DevTools）的启用
混合应用开发实战思路

29.1 快速上手：QWebEngineView

先来个最简单的例子。你只需要一个QWebEngineView控件，调用load()方法就能加载网页。嗯，就这么简单。

#include <QApplication>
#include <QWebEngineView>

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    
    QWebEngineView *view = new QWebEngineView();
    view->load(QUrl("https://www.qt.io"));
    view->show();
    
    return app.exec();
}

跑起来之后，你会看到一个完整的Chromium浏览器窗口。注意，这里有个坑——WebEngine需要网络访问权限。我在项目里遇到过，有些客户的内网环境限制了端口，结果页面一片空白。排查了半天才发现是网络问题。

小提示：如果你只需要显示本地HTML文件，可以用 view->setUrl(QUrl::fromLocalFile("path/to/index.html")); 这样就不依赖网络了。

29.2 网页加载控制

实际开发中，你不能让用户干等着。你需要知道页面加载进度、加载成功还是失败。QWebEngineView提供了几个关键信号：

信号	说明	常用场景
loadStarted()	开始加载	显示加载动画
loadProgress(int)	加载进度 0-100	更新进度条
loadFinished(bool)	加载完成	隐藏加载动画，检查成功/失败

我习惯这样用：

connect(view, &QWebEngineView::loadStarted, [=]() {
    ui->progressBar->setVisible(true);
    ui->statusLabel->setText("正在加载...");
});

connect(view, &QWebEngineView::loadProgress, [=](int progress) {
    ui->progressBar->setValue(progress);
});

connect(view, &QWebEngineView::loadFinished, [=](bool ok) {
    ui->progressBar->setVisible(false);
    if (ok) {
        ui->statusLabel->setText("加载完成");
    } else {
        ui->statusLabel->setText("加载失败");
        // 这里可以显示一个错误页面
    }
});

你想想看，如果用户网络不好，页面加载到一半卡住了，没有进度反馈，用户肯定会觉得你的软件有问题。所以这个进度监听，我建议你每次都加上。

29.3 JavaScript与C++交互

这才是WebEngine最强大的地方。你可以让C++调用JavaScript，也可以让JavaScript调用C++。说白了，就是打通了原生和Web的任督二脉。

29.3.1 C++调用JavaScript

用 page()->runJavaScript() 就行。比如你想获取网页的标题：

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

也可以执行复杂的JavaScript代码：

// 修改网页背景色
view->page()->runJavaScript("document.body.style.backgroundColor = 'lightblue';");

// 调用网页中的函数
view->page()->runJavaScript("myFunction('hello from C++');");

注意：runJavaScript()是异步的。如果你需要同步获取结果，可以用QWebChannel的方式。我曾经在项目里直接用runJavaScript获取大量数据，结果回调顺序乱了，调试了好久才发现是异步导致的。

29.3.2 JavaScript调用C++

这个稍微复杂一点，需要用到QWebChannel。我画个流程图你就明白了：

// 1. 定义一个C++对象，暴露给JS
class Bridge : public QObject
{
    Q_OBJECT
public:
    explicit Bridge(QObject *parent = nullptr) : QObject(parent) {}

public slots:
    void onButtonClicked(const QString &message) {
        qDebug() << "来自JS的消息:" << message;
        // 这里可以调用Qt原生功能
    }

    QString getData() {
        return "这是来自C++的数据";
    }
};

// 2. 设置WebChannel
QWebChannel *channel = new QWebChannel(view->page());
Bridge *bridge = new Bridge();
channel->registerObject("bridge", bridge);
view->page()->setWebChannel(channel);

然后在HTML中这样调用：

<script src="qrc:///qtwebchannel/qwebchannel.js"></script>
<script>
    var bridge;
    new QWebChannel(qt.webChannelTransport, function(channel) {
        bridge = channel.objects.bridge;
    });

    function callCpp() {
        bridge.onButtonClicked("用户点击了按钮");
    }

    function getCppData() {
        bridge.getData(function(data) {
            console.log("C++返回的数据:", data);
        });
    }
</script>

这个模式我用了很多次。比如做一个在线文档编辑器，保存按钮在网页里，但保存文件要用C++的原生对话框。通过QWebChannel，JS调用C++的保存函数，C++弹出对话框后把结果返回给JS。完美。

29.4 启用开发者工具

调试WebEngine页面时，没有DevTools简直要命。Qt默认是关闭的，你需要手动开启：

// 设置环境变量（在main函数开头）
qputenv("QTWEBENGINE_REMOTE_DEBUGGING", "9222");

// 或者用代码设置
QWebEngineSettings::globalSettings()->setAttribute(
    QWebEngineSettings::JavascriptEnabled, true);

然后打开Chrome浏览器，访问 http://127.0.0.1:9222，就能看到熟悉的DevTools界面了。你可以检查元素、看网络请求、调试JavaScript。嗯，这个功能我建议你开发时一直开着，能省不少时间。

小技巧：如果你不想每次手动打开浏览器，可以在程序里自动启动DevTools窗口：

QDesktopServices::openUrl(QUrl("http://127.0.0.1:9222"));

29.5 混合应用开发实战

混合应用，说白了就是「原生壳 + Web内容」。我做过一个数据可视化项目，界面左侧是Qt原生的树形菜单，右侧是WebEngine显示的ECharts图表。用户点击左侧菜单，右侧图表动态更新。

核心思路是这样的：

原生部分：负责文件操作、系统调用、硬件交互
Web部分：负责UI展示、动画、图表、富文本编辑
通信桥梁：用QWebChannel连接两边

举个例子，用户点击左侧的「销售数据」节点：

// C++端
void MainWindow::onTreeItemClicked(const QString &itemName)
{
    // 从数据库或文件读取数据
    QJsonObject data = loadData(itemName);
    
    // 通过WebChannel发送给JS
    QWebEnginePage *page = ui->webView->page();
    QJsonDocument doc(data);
    QString jsCode = QString("updateChart(%1);").arg(
        QString::fromUtf8(doc.toJson(QJsonDocument::Compact)));
    page->runJavaScript(jsCode);
}

Web端收到数据后，用ECharts渲染图表。用户完全感觉不到这是Web内容，体验和原生一样流畅。

避坑指南：我曾经在混合应用里犯过一个错误——在Web端做了大量计算，导致页面卡顿。后来把计算逻辑移到C++端，Web只负责展示，性能提升了好几倍。记住：计算密集型任务交给C++，UI密集型任务交给Web。

29.6 性能与安全注意事项

用WebEngine时，有几个点你一定要注意：

内存占用：每个QWebEngineView都是一个独立的渲染进程。如果你开太多，内存会飙升。我建议最多同时显示3-5个页面。
跨域问题：默认情况下，WebEngine禁止跨域请求。如果你需要加载本地文件，记得设置 --disable-web-security 参数（仅开发环境）。
JavaScript安全：不要轻易执行用户输入的JavaScript代码，防止XSS攻击。我一般会对输入做严格的过滤。

好了，这一章的内容就到这里。WebEngine是个好东西，但用好了是利器，用不好是累赘。多动手试试，遇到问题可以翻翻Qt官方文档，或者直接打开DevTools调试。嗯，实践出真知。

📚 课程目录