Qt WebEngine 概述

Qt WebEngine 模块提供了一个 Web 浏览器引擎，可让您在没有本地 Web 引擎的平台上轻松地将万维网上的内容嵌入到 Qt 应用程序中。

Qt WebEngine 该模块提供了用于渲染 HTML、XHTML 和 SVG 文档的 C++ 类和 QML 类型，可使用层叠样式表 (CSS) 和 JavaScript 脚本调整样式。通过使用 HTML 元素上的contenteditable 属性，用户可以完全编辑 HTML 文档。

Qt WebEngine 架构

Qt WebEngine 架构框图，显示 Qt WebEngine Widgets、Qt WebEngine 和 Qt WebEngine Process 如何与构建在 Chromium 引擎之上的 Qt WebEngine Core 进行交互" src="images/qtwebengine-architecture.png" title="Qt WebEngine 架构框图，显示 Qt WebEngine Widgets、Qt WebEngine 和 Qt WebEngine Process 如何与构建在 Chromium 引擎之上的 Qt WebEngine Core 进行交互"/>

Qt WebEngine 的功能分为以下模块：

• Qt WebEngine 小部件 模块，用于创建基于小部件的网络应用程序
• Qt WebEngine 用于创建基于 Qt Quick 的网络应用程序的模块
• Qt WebEngine 与 Chromium 交互的核心模块

页面渲染和 JavaScript 执行与图形用户界面进程分离，由Qt WebEngine 进程处理。如果在应用程序中捆绑了 Qt 库，则该库必须与应用程序一起提供。

Qt WebEngine 部件模块

Qt WebEngine Widgets 模块的类关系结构以及主要类如何相互作用和相互依赖的示意图" src="images/qtwebenginewidgets-model.png" title="显示 Qt WebEngine Widgets 模块的类关系结构以及主要类如何相互作用和相互依赖的示意图"/>

网络引擎视图是Qt WebEngine 模块的主要部件组件。它可在各种应用程序中用于加载网页内容。在视图中，网络引擎页面包含一个主框架，负责显示网络内容、历史导航链接和操作。视图和页面非常相似，因为它们提供了一系列通用功能。

所有页面都属于一个网络引擎配置文件，其中包含共享设置、脚本和cookie。配置文件可用于将页面相互隔离。一个典型的用例是用于私人浏览模式的专用配置文件，在这种模式下不会永久保存任何信息。

内容使用图形卡（GPU）功能渲染。而场景图则依赖 Qt 渲染硬件接口（Qt Rendering Hardware Interface）作为 GPU 可能具备的不同功能和 API 的抽象层。有关如何调整渲染管道的更多建议，请参阅 "通过 Qt 渲染硬件接口进行渲染"。

Qt WebEngine 模块

Qt WebEngine 模块中的类关系图。View 类连接到 Action、History 和 Profile。Profile 类连接到 Settings、Script 和 Cookie" src="images/qtwebengine-model.png" title="Qt WebEngine 模块中的类关系图。View 类连接到 Action、History 和 Profile。Profile 类连接到 Settings、Script 和 Cookie"/>

Qt WebEngine QML 实现包含与Qt WebEngine Widgets 实现相同的元素，只是没有可单独访问的网络引擎页面。受支持的页面功能集成在网络引擎视图中。

Qt WebEngine 核心模块

Qt WebEngine 核心基于Chromium 项目。Chromium 提供自己的网络和绘画引擎，并与其附属模块紧密结合在一起开发。即使不使用QtNetwork 协议栈，其设置也可与Qt WebEngine 同步。详情请参见代理支持、管理证书、客户端证书和QWebEngineCookieStore 。

所使用的 Chromium 版本是当前版本Qt WebEngine 的 Qt 功能冻结时最新稳定 Chrome 版本所使用的版本。每次补丁发布时都会从较新的 Chrome 版本中挑选额外的安全补丁，Qt 补丁发布冻结时及时发布的安全补丁也会包含在内。如果 Chrome 浏览器在我们的发布窗口之外发布了重要的修复程序，下一个补丁的发布时间将加快，以确保在补丁详细信息公开之前发布已打补丁的Qt WebEngine 。

如果您除了安全修复之外还需要更新Qt WebEngine ，但又无法更新所有 Qt，Qt WebEngine 支持使用上一个 Qt LTS 的旧版本构建。例如，Qt WebEngine 6.3、6.4 和 6.5 都可以用 Qt 6.2 构建。在 Qt LTS 版本中，Qt WebEngine 可能会被这样的较新版本完全取代，以方便打安全补丁。

相关的 Chromium 版本也可在运行时使用qWebEngineChromiumVersion() 方法读取，而qWebEngineChromiumSecurityPatchVersion() 则可读取当前的安全补丁级别。你也可以在Qt WebEngine 源文件的 CHROMIUM_VERSION 文件中找到相关版本。

在基于小工具的应用程序中嵌入网页内容

使用QWebEngineView 类以最简单的方式显示网页。由于它是一个小工具，因此您可以将QWebEngineView 嵌入到您的表单中，并使用其便利功能下载和显示网站。

QWebEngineView *view = new QWebEngineView(parent);
view->load(QUrl("http://www.qt.io/"));
view->show();

QWebEngineView 的一个实例有一个QWebEnginePage 。QWebEnginePage 可以有一个QWebEngineHistory ，用于访问页面的导航历史记录，还可以有几个QAction 对象，用于在网页上应用操作。此外，QWebEnginePage 还能在页面主框架的上下文中运行 JavaScript 代码，并能为特定事件（如显示自定义验证对话框）定制处理程序。

每个QWebEnginePage 都隶属于QWebEngineProfile ，QWebEngineSettings 用于指定页面设置，QWebEngineScriptCollection 用于在页面上运行脚本，QWebEngineCookieStore 用于访问 Chromium 的 HTTP cookie。QWebEnginePage 也可以直接指向脚本集合。

对于基于 widget 的应用程序，网络引擎会自动初始化，除非将其置于插件中。在这种情况下，必须在应用程序主源文件中使用QtWebEngineQuick::initialize 对其进行初始化，如下代码片段所示：

int main(int argc, char **argv)
{
    QtWebEngineQuick::initialize();

    QApplication app(argc, argv);

    QMainWindow window;
    window.show();

    return app.exec();
}

将 Web 内容嵌入Qt Quick 应用程序

WebEngineView QML 类型允许Qt Quick 应用程序渲染动态网页内容区域。A WebEngineView类型可与其他 QML 类型共享屏幕，也可按照Qt Quick 应用程序的指定覆盖整个屏幕。

为确保在图形用户界面和渲染进程之间共享 OpenGL 上下文，必须在应用程序主源文件中使用QtWebEngineQuick::initialize 对网络引擎进行初始化，如下代码片段所示：

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

    QtWebEngineQuick::initialize();

    QQmlApplicationEngine engine;
    engine.load(QUrl("qrc:/main.qml"));

    return app.exec();
}

应用程序可以使用 URL 或 HTML 字符串将页面加载到WebEngineView ，并在会话历史记录中导航。默认情况下，不同页面的链接会加载到同一个WebEngineView 对象中，但网站可能会要求以新标签页、窗口或对话框的形式打开它们。

以下示例 QML 应用程序使用url 属性加载网页：

import QtQuick
import QtQuick.Window
import QtWebEngine

Window {
    width: 1024
    height: 750
    visible: true
    WebEngineView {
        anchors.fill: parent
        url: "https://www.qt.io"
    }
}

脚本注入

Qt WebEngine 不允许直接访问页面的文档对象模型（DOM）。不过，可以通过注入脚本来检查和调整 DOM。

页面的 DOM 是在文档准备就绪时构建的，通常是在页面完全加载时。因此，在文档创建后立即执行脚本并不适合 DOM 操作，因为在这种情况下，必须等到 DOM 准备就绪。

此外，注入的脚本与页面上执行的其他脚本共享同一个世界，这可能会导致冲突。为了避免这种情况，QWebEngineScript 类和 WebEngineScript QML 类型为内容脚本扩展提供了 Chromium API 的实现。它们指定了要运行的脚本、注入点和运行脚本的世界。这样就能访问 DOM，在世界中对其进行操作。

Qt WebEngine 此外，《CLG 脚本扩展》还支持使用以下类似 Greasemonkey 的属性来增强脚本：

• @exclude <regexp>
• @include <regexp>
• @match <regexp>
• @name <free text>
• @run-at [document-start|document-end|document-idle]

这些属性决定了是否以及何时运行用户脚本。这些属性必须紧贴脚本开头，放在==UserScript== 注释中：

// ==UserScript==
// @include http://*.qt.io/*
// @exclude http://wiki.qt.io/*
// ==/UserScript==

window.alert("Page is from qt.io, but not wiki.qt.io");

如果您的WebEngine 应用程序是使用Qt Quick Resource Compiler 构建的，并且应用程序在 .qrc 资源中包含 JavaScript 文件，请考虑阅读 "Qt 资源文件中的 JavaScript 文件"一节。

管理证书

Qt WebEngine 使用自己的网络协议栈，因此QSslConfiguration 不用于打开 SSL 连接。相反，Qt WebEngine 使用操作系统的根 CA 证书来验证对等方的证书。

webEngineCertificateError::type 和QWebEngineCertificateError::Type 枚举提供了有关可能发生的证书错误类型的信息。这些错误可通过WebEngineView::certificateError QML 方法或连接到QWebEnginePage::certificateError 信号来处理。

代理支持

Qt WebEngine 使用来自 Qt Network中的代理设置，并将其转发给 Chromium 的网络协议栈。如果设置了QNetworkProxy::applicationProxy ，它也将用于Qt WebEngine 。如果启用了QNetworkProxyFactory::usesSystemConfiguration() ，代理设置将自动从系统中获取。不过，已安装的QNetworkProxyFactory 的设置将被忽略。

如果设置了QNetworkProxy::user() 和QNetworkProxy::password()，这些凭证将自动用于代理身份验证。由于没有错误处理回调，用户必须提供有效的凭据。

如果QNetworkProxy 没有设置凭据，但代理要求进行身份验证，则会发出QWebEnginePage::proxyAuthenticationRequired 。对于Qt Quick ，则会显示一个对话框。

Qt WebEngine 并不支持QNetworkProxy 的所有属性。也就是说，QNetworkProxy::type(),QNetworkProxy::hostName() 和QNetworkProxy::port() 会被考虑在内。所有其他代理设置，如QNetworkProxy::rawHeader() 将被忽略。

高 DPI 支持

Qt 6 始终启用高 DPI 支持，这也适用于Qt WebEngine 。更多信息，请参阅高 DPI。

使用 WebEngine 核心

Qt WebEngine Core 提供了一个由Qt WebEngine 和Qt WebEngine Widgets 共享的 API，用于处理为 Chromium 网络堆栈发出的 URL 请求以及访问其 HTTP cookie。

实施QWebEngineUrlRequestInterceptor 接口并在配置文件中安装拦截器后，就能在 URL 请求到达 Chromium 网络堆栈之前对其进行拦截、阻止和修改 (QWebEngineUrlRequestInfo)。

QWebEngineUrlSchemeHandler 可为配置文件注册，以添加对自定义 URL 方案的支持。然后，针对该方案的请求将作为QWebEngineUrlRequestJob 对象发送至QWebEngineUrlSchemeHandler::requestStarted() 。

QWebEngineCookieStore 类提供了访问 Chromium HTTP cookie 的函数。这些函数可用于与QNetworkAccessManager 同步 cookie，以及在导航过程中设置、删除和拦截 cookie。

进程模型

Qt WebEngine 进程是一个独立的可执行文件，用于渲染网页和执行 JavaScript。这样可以减少安全问题，并隔离特定内容导致的崩溃。

Qt WebEngine 在《超级嗅探狗》中，使用多个操作系统进程将网站与网站之间以及网站与客户端应用程序之间隔离开来，从而提高了安全性和稳健性。支持以下进程模式，或在操作系统进程间划分网站的方式：

• 每个网站实例进程
• 每个网站进程
• 单一进程

每个网站实例进程

这是默认模式。来自不同网站的网页被放入不同的进程，对同一网站的不同访问也被隔离。

如果两个网页来自相同的注册域名（如wikipedia.org ）和方案（如https ），则视为属于同一站点。这与同源策略类似，但会忽略子域。例如，https://en.wikipedia.org/ 和https://de.wikipedia.org/ 都属于同一个站点。

站点实例是属于同一站点的网页集合。当应用程序将 URL 明确加载到Qt WebEngine 时（例如通过QWebEnginePage::setUrl ），就会为该网页创建一个新的站点实例。但是，当用户点击页面上的同站点链接时，现有的站点实例只是扩展了更多的页面。

例如，在 "简单浏览器"示例中，当用户打开两个标签页并在 URL 栏中明确输入https://en.wikipedia.org/ 时，两个标签页都将有自己独立的操作系统进程（因为明确输入 URL 会创建一个新的网站实例）。但是，当用户用鼠标中键单击一些相同网站的链接以打开更多标签页时，这些新标签页将共享同一个操作系统进程（因为用户交互扩展了现有网站实例）。

每个网站的进程

来自不同网站的页面被放入不同的进程。与每个网站实例进程不同的是，对同一网站的所有访问都将共享一个操作系统进程。

这种模式的好处是减少内存消耗，因为更多网页将共享进程。缺点是安全性、健壮性和响应速度降低。

要启用这种模式，请使用命令行参数--process-per-site 。请参阅使用命令行参数。

单进程

仅出于调试目的，可使用命令行参数--single-process 启用单进程模式。请参阅使用命令行参数和Qt WebEngine 调试和剖析。

平台注意事项

Qt WebEngine 目前仅支持 Windows、Linux 和 macOS。由于 Chromium 的构建要求，它通常需要比 Qt 其他部分更新的编译器。更多详情，请参阅Qt WebEngine Platform Notes。

相关模块

您可以使用 Qt PDF模块来渲染 PDF 文件。在内部，该模块由PDFium 提供支持，后者也用于 Chromium。

使用该 Qt WebView模块，你可以在有浏览器 API 的平台上使用操作系统提供的浏览器 API，将网页内容嵌入到你的应用程序中，而无需发布整个 Chromium 运行时。在没有原生 API 的平台上，它还可以充当WebEngine 的包装器。

该 Qt WebChannel模块可用于在 C++ 的QObject 对象和 QML 的 JavaScript 之间创建双向通信通道。