Qt WebEngine 概述

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

Qt WebEngine 该模块提供了用于渲染 HTML、XHTML 和 SVG 文档的 C++ 类和 QML 类型，这些文档使用层叠样式表（CSS）进行样式设计，并使用 JavaScript 编写脚本。通过使用 HTML 元素上的 属性，用户可以完全编辑 HTML 文档。contenteditable

Qt WebEngine 架构

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

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

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

Qt WebEngine 部件模块

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

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

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

Qt WebEngine 模块

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 文件中找到相关版本。

Qt WebEngine 进程

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

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

使用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 5.8 起，Qt WebEngine 支持通过使用以下类似 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 Compiler 构建的，并且应用程序在 .qrc 资源中包含 JavaScript 文件，请考虑阅读Qt 资源文件中的 JavaScript 文件一节。

管理证书

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

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

为支持高 DPI 设备，建议将应用程序属性Qt::AA_EnableHighDpiScaling 设置为启用基于显示器像素密度的自动缩放。在Qt WebEngine 应用程序中，缩放会影响默认缩放系数和滚动条大小。

例如

int main(int argc, char *argv[])
{
  QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling);
  QApplication app(argc, argv);
  // ...
}

Qt WebEngine 将普通分辨率和高分辨率的图像捆绑到qtwebengine_resources_100p.pak和qtwebengine_resources_200p.pak文件中。根据目标分辨率的不同，需要部署其中一个或两个文件。

有关详细信息，请参阅高 DPI。

使用 WebEngine Core

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

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

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

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

平台说明

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

相关模块

Qt WebEngine 取代Qt WebKit模块，WebKit 模块基于 WebKit 项目，但自 Qt 5.2 以来一直未主动与上游 WebKit 代码同步，在 Qt 5.5 中已被弃用。有关如何将 Qt WebKit 小部件应用程序更改为使用 小部件的提示，请参阅Qt WebEngine 从 Qt WebKit 移植到Qt WebEngine 。

该 Qt WebView模块允许在有本地 Web 浏览器的平台上使用本地 Web 浏览器。

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