Qt WebEngine 功能

总结Qt WebEngine的功能。

Qt WebEngine 支持以下功能:

音频和视频编解码器

Qt WebEngine 仅支持 MPEG-4 Part 14 (MP4) 文件格式,前提是所需的专有音频和视频编解码器(如 H.264 和 MPEG layer-3 (MP3))已启用。专有编解码器可以通过在配置 Qt 时向 configure 工具传递以下选项来启用:

-webengine-proprietary-codecs

例如,在配置Qt以在顶层构建时,可以传递以下选项:

configure -webengine-proprietary-codecs

更多信息,请参见Qt配置选项。

当使用cmake仅构建Qt WebEngine模块时,可以使用以下命令进行配置和构建(在此示例中,Qt WebEngine源代码位于C:\qt\qtwebengine):

qt-configure-module C:\qt\qtwebengine -webengine-proprietary-codecs
cmake --build . --parallel

警告

分发专有编解码器库时,您必须获得它们的许可证。

FFmpeg 是一个跨平台的解决方案,用于录制、转换和流式传输音频和视频。它可以配置为与多种编解码器一起使用,这在分发编解码器库时会引发许可问题。对于某些编解码器,如 OpenH264,有开源实现可用。

WebEngineDriver

使用WebEngineDriver,您可以自动化跨浏览器的网站测试。WebEngineDriver基于ChromeDriver,可以以相同的方式使用。有关ChromeDriver及其使用的更多信息,请访问ChromeDriver用户网站

与ChromeDriver相比,WebEngineDriver进行了轻微的修改,以便能够连接到基于Qt WebEngine的浏览器。它与Qt WebEngine示例浏览器兼容,例如Simple BrowserNano Browser

浏览器自动化是通过像Selenium WebDriver这样的WebDriver客户端进行脚本编写的。例如,WebEngineDriver可以与Selenium WebDriver的Python语言绑定一起使用:

from selenium import webdriver
from selenium.webdriver.chrome.service import Service

service = Service(executable_path='QTDIR/libexec/webenginedriver')
options = webdriver.ChromeOptions()
options.binary_location = 'path/to/browser_binary'

driver = webdriver.Chrome(service=service, options=options)
driver.get("http://www.google.com/")
driver.quit()

在这个例子中,

  • executable_path 必须设置为 WebEngineDriver 的二进制路径

  • QTDIR 是 Qt 安装的目录

  • options.binary_location 必须设置为浏览器的二进制路径

注意

在Windows上:executable_path='QTDIR/bin/webenginedriver.exe'

在执行脚本之前,必须设置QTWEBENGINE_REMOTE_DEBUGGING环境变量。它的值是一个端口号,浏览器和WebEngineDriver都使用这个端口号进行通信。

export QTWEBENGINE_REMOTE_DEBUGGING=12345

通过执行,脚本会打开指定的网页浏览器并加载谷歌网站。

如果浏览器已经启动并设置了远程调试端口,WebEngineDriver 也可以附加到已经运行的浏览器上。在脚本中必须将 options.debugger_address 设置为远程调试地址:

options.debugger_address = 'localhost:12345'

在这种情况下,options.binary_location 不应设置,因为浏览器已经在运行。如果设置了 options.debugger_address,WebEngineDriver 不会使用环境变量 QTWEBENGINE_REMOTE_DEBUGGING

注意

WebEngineDriver 必须使用与 Qt WebEngine 相同版本的 Chromium 构建。

Chromium 开发者工具

Chromium DevTools 提供了检查和调试任何网页内容的布局和性能问题的能力。

此功能可以通过使用命令行选项--remote-debugging-port=[your-port]启动Qt WebEngine应用程序或通过设置环境变量QTWEBENGINE_REMOTE_DEBUGGING,然后使用基于Chromium的浏览器(如Simple BrowserNano Browser)连接到http://localhost:[your-port]来测试。

注意

任何WebEngine命令行选项应在--webEngineArgs选项之后指定,该选项用于将用户的应用程序特定选项与WebEngine的选项分开。

--webEngineArgs --remote-debugging-port=5000

为了避免在远程调试期间出现WebSocket错误,请添加一个额外的命令行参数--remote-allow-origins=[,, ...],其中指的是请求来源。使用--remote-allow-origins=*以允许来自所有来源的连接。如果未指定任何内容,Qt WebEngine在启用远程调试时会将--remote-allow-origins=*添加到命令行参数中,从而允许来自所有来源的请求。

Chromium DevTools 页面也可以在应用程序中显示。要进行设置,您可以调用 setInspectedPage() 来指定要检查的页面,这会隐式地将 DevTools 加载到 this 页面中,或者调用 setDevToolsPage() 来让 this 页面被检查。

相应的QML属性是 WebEngineView.devToolsViewWebEngineView.inspectedView

有关更多信息,请参阅 Qt WebEngine 调试和分析

客户端证书

一些网络服务器,特别是许多内网站点,要求客户端使用证书进行身份验证,这种证书被称为客户端证书。Qt WebEngine 将读取在 macOS 和 Windows 系统设置中安装的客户端证书,以及在 Linux 上安装到 NSS 数据库中的证书。可以使用 pk12util 工具将证书安装到 NSS 数据库中。

默认情况下,Qt WebEngine 不会向服务器提供任何客户端证书,因为这样做会唯一标识用户,并可能违反隐私期望。

要激活对客户端证书的支持,应用程序需要监听selectClientCertificateselectClientCertificate信号,并选择其中一个提供的证书。对于可以导航到不受信任网站的应用程序,建议在唯一标识用户到远程服务器之前始终给用户一个选择。

除了存储在系统设置中的客户端证书外,Qt WebEngine 还提供了内存存储。可以通过 clientCertificateStore() 方法获取 QWebEngineClientCertificateStore 实例。应用程序可以使用此类通过 add() 调用添加新证书。请注意,在 selectClientCertificate 调用期间,Qt WebEngine 会列出系统和内存中存储的客户端证书。

另请参阅客户端证书示例以获取更多实现细节。

自定义方案

Qt WebEngine 使应用程序能够定义自己的自定义URL方案,这些方案具有专门的安全策略和传输机制。

自定义方案可用于实现替代网络协议,包括所有常见的网络安全策略、用于显示用户界面组件或调试信息的特权内部方案、具有额外限制的沙盒方案等。

欲了解更多信息,请参阅 QWebEngineUrlSchemeQWebEngineUrlSchemeHandler

拖放

Qt WebEngine 支持 HTML5 的拖放功能。

此功能可以通过在Simple BrowserNano Browser中打开HTML5拖放演示来测试,例如HTML5 Demos - Drag and DropHTML5 Demos - Simple Drag and DropHTML5 Demos - Drag and Drop, Automatic Upload

将文件拖入浏览器实际上不是HTML5的一部分,但它是被支持的。可以通过打开HTML5 Demos - File API来测试。

此功能在 Qt 5.7.0 中添加了支持。

网站图标

Qt WebEngine 支持网站 URL 图标,favicon。每个图标都存储在内部数据库中,每个 QWebEngineProfile 都可以通过 icon() 调用或当前加载内容的 WebEngineView.icon 属性访问。

此外,Qt WebEngine 提供了用于访问内部配置文件中已存储图标的API。

注意

图标数据库不适用于非记录配置文件。

QML 网站图标处理

为了访问图标,注册了一个QQuickImageProvider。这个提供者可以通过一个特殊的URL访问,其中方案是“image:”,主机是“favicon”。

url 可以是网站图标的URL:

url 也可以是一个页面 URL 来访问其图标:

如果有多个图标可用,可以指定Image::sourceSize属性来选择所需大小的图标。如果未指定Image::sourceSize或为0,则将选择最大的可用图标。

图像提供者在现有的WebEngineView实例中查找请求的图标。首先,它尝试匹配当前显示的图标。如果没有找到匹配项,则从数据库中请求图标。每个配置文件都有自己的图标数据库,并且它存储在持久存储中,因此即使没有网络连接也可以访问存储的图标。图标必须事先加载才能存储在数据库中。

C++ 图标处理

用户可以为每个QWebEngineProfile从先前加载的内容中请求一个图标,使用requestIconForPageURL()requestIconForIconURL()调用。请注意,配置文件的数据库存储在持久存储中,并且可以在没有网络连接的情况下访问。

全屏

Qt WebEngine 支持以全屏模式查看网页内容。有关更多信息,请参阅 WebEngineSettings.fullscreenSupportEnabledfullScreenRequestedFullScreenSupportEnabledfullScreenRequested

此功能可以通过在视频播放器Nano浏览器中播放YouTube视频来测试,并点击全屏图标进入全屏模式。

此功能在 Qt 5.6.0 中添加了支持。

硬件加速

QtWebEngine 尝试使用硬件加速来渲染内容。它使用 OpenGLOpenGLES API 在 GPU 上执行渲染调用。作为备用方案,当硬件不满足所需的 OpenGL 功能集时,将使用软件渲染。用户可以通过加载 chrome://gpu 内部页面来检查当前的硬件加速状态。此外,可以使用 QTWEBENGINE_CHROMIUM_FLAGS 通过 disable-gpu 开关显式禁用加速。例如在 Linux 上:

export QTWEBENGINE_CHROMIUM_FLAGS=--disable-gpu

HTML5 数字版权管理

如果安装了Widevine CDM插件,Qt WebEngine支持查看受DRM保护的视频。CDM插件是用于显示受DRM保护内容的基于Flash插件的替代品。它仅以二进制格式提供,因此可以隐藏DRM解密实现细节。它可以从第三方或Google Chrome安装中获取。

Qt WebEngine 在启动时会查找 Widevine CDM 插件,通常会在已知的位置查找,例如默认的 Google Chrome 安装目录或 Linux 发行版的特定路径。然而,插件的位置也可以通过 QTWEBENGINE_CHROMIUM_FLAGS 使用 widevine-path 来传递。

在Windows上:

set QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="C:/some path/widevinecdm.dll"

在Linux上:

export QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="/some path/libwidevinecdm.so"

在macOS上:

export QTWEBENGINE_CHROMIUM_FLAGS=--widevine-path="/some path/libwidevinecdm.dylib"

DRM服务最常用的视频格式H.264需要专有的音频和视频编解码器。有关启用编解码器的更多信息,请参阅音频和视频编解码器

此功能可以通过在castLabsSwank Motion Pictures, Inc.Bitmovin PlayerSimple BrowserNano Browser中播放视频来测试。

此功能在 Qt 5.7.0 中添加了支持。

HTML5 地理位置

Qt WebEngine 支持使用 Qt Positioning 作为后端的 JavaScript 地理定位 API。默认情况下,HTML5 地理定位功能是禁用的。要明确允许它,应用程序需要监听 permissionRequested。当接收到类型为 Geolocation 的权限请求时,您可以在接收到的对象上调用 grant() 来授予所需的权限。

如果Qt WebEngine是使用Qt Positioning支持构建的,那么可以通过使用Maps并允许其找到用户的当前位置来测试此功能。

注意

在Windows 11上,启用设置以授予地图示例访问Windows位置服务的权限。在设置应用中的隐私与安全 > 位置下,启用位置服务,允许应用访问您的位置,并允许桌面应用访问您的位置。

请参阅Qt Positioning以了解可能的后端设置,例如基于GPS或IP的定位。

此功能在 Qt 5.5.0 中添加了支持。

HTML5 WebSockets

Qt WebEngine 支持 WebSocket JavaScript API,使用 ws://wss:// 协议与 WebSocket 服务器进行通信。此外,与 Qt WebChannel 和 Qt WebSockets 的集成使得 JavaScript 和应用程序的本机端之间能够进行通信。

Qt WebChannel 模块有一个很好的聊天服务器及其基于网页的聊天客户端的示例。该客户端在 Qt WebEngine 的示例浏览器(如 Simple BrowserNano Browser)中开箱即用。

HTTP/2 协议

Qt WebEngine 支持 HTTP/2 协议的 Chromium 实现。

此功能可以通过在Simple BrowserNano Browser中打开一个HTTP/2演示(例如Akamai HTTP/2 Demo)来测试。

本地存储

Qt WebEngine 支持在 Local Storage 中保存没有过期日期的键值对。这是 Web Storage API 的一部分,用户可以使用 Window.localStorage JavaScript 属性访问给定域的 Storage 对象。即使页面或浏览器应用程序关闭,存储的数据也会保留。

请注意,Local 存储也可以通过 LocalStorageEnabled 设置来禁用。此外,存储路径可以通过 setPersistentStoragePath 调用来调整。

QWebEngineProfile profile("MyProfile");
profile.settings()->setAttribute(QWebEngineSettings::LocalStorageEnabled, isEnabled);
profile.setPersistentStoragePath("/path/to/storage");

Qt WebEngine 还提供了一种简单的方法来调查 Local Storage 的内容,通过访问应用面板并展开本地存储菜单,使用 Qt WebEngine 开发者工具

原生对话框

一个网页可能会为以下功能请求对话框:

  • 输入用于HTTP和代理认证的用户凭证

  • 显示JavaScript警告、确认对话框和提示

  • 选择颜色

  • 选择文件

  • 显示表单验证消息

Qt WebEngine 为这些功能提供了标准对话框。在基于小部件的应用程序中,标准对话框基于 QDialog,而在 Qt Quick 应用程序中,它们可以基于 Qt Quick Controls 1 或 Qt Quick Controls 2(自 Qt 5.8 起)。后者仅在 eglfs 平台上使用。

要明确强制使用基于Qt Quick Controls 1或Qt Quick Controls 2的对话框,请将QTWEBENGINE_DIALOG_SET环境变量设置为QtQuickControls1QtQuickControls2

Qt WebEngine Widgets 对话框可以通过重新实现 chooseFiles()javaScriptAlert()javaScriptConfirm()javaScriptPrompt() 函数来自定义。

自 Qt 5.8 起,可以通过连接到 authenticationDialogRequested()javaScriptDialogRequested()colorDialogRequested()fileDialogRequested() 和 WebEngineView::formValidationMessageRequested() 信号来自定义 Qt Quick 对话框。例如,

PDF文件查看

Qt WebEngine 支持通过导航查看PDF文档。此功能使用Chromium扩展API和PDF查看器插件来显示PDF文档。可以在Simple BrowserNano Browser中进行测试。

要使用此功能,需要使用PluginsEnabledWebEngineSettings::pluginsEnabled来启用加载插件。

此功能可以通过PdfViewerEnabledWebEngineSettings::pdfViewerEnabled设置来开启(默认)或关闭。

此功能在 Qt 5.13.0 中添加了支持。

页面生命周期API

Qt WebEngine 支持 Page Lifecycle API 规范,这是 HTML 标准的一个正在进行中的扩展,允许用户代理通过冻结或丢弃后台页面来减少资源消耗。该功能在 Widgets 和 QML API 中都有体现。

有关使用QML API的示例,请参见WebEngine生命周期示例

此功能在 Qt 5.14.0 中添加了支持。

生命周期状态概述

每个WebEngineView项目(或QWebEnginePage对象)可以处于三种生命周期状态之一:活动、冻结或丢弃。这些状态,就像CPU的睡眠状态一样,控制着网页视图的资源使用。

活动状态是网页视图的正常、无限制状态。所有可见的网页视图始终处于活动状态,所有尚未完成加载的网页视图也是如此。只有不可见的、空闲的网页视图才能转换到其他生命周期状态。

冻结状态是一种低CPU使用率的状态。在这种状态下,大多数HTML任务源被暂停(冻结),因此,大多数DOM事件处理和JavaScript执行也将被暂停。为了进入冻结状态,网页视图必须是不可见的,因为在这种状态下无法进行渲染。

discarded 状态是一种极端的资源节省状态。在这种状态下,网页视图的浏览上下文将被丢弃,相应的渲染子进程将被关闭。在这种状态下,CPU 和内存的使用几乎减少到零。退出此状态时,网页将自动重新加载。进入和退出丢弃状态的过程类似于序列化网页视图的浏览历史并销毁视图,然后创建一个新视图并恢复其历史记录。

另请参阅 WebEngineView::LifecycleState。在 Widgets API 中等效的是 LifecycleState

``lifecycleState``

和 `` recommendedState``

属性

WebEngineView 类型的 lifecycleState 属性是一个读写属性,用于控制网页视图的当前生命周期状态。该属性旨在尽可能少地限制可以转换到的状态。例如,允许冻结当前正在后台播放音乐的网页视图,从而停止音乐。为了实现一种不那么激进的资源节省策略,避免中断用户可见的后台活动,必须使用 recommendedState 属性。

WebEngineView 类型的 recommendedState 属性是一个只读属性,它根据当前网页视图的活动情况计算 lifecycleState 属性的安全限制。因此,在一个网页视图在后台播放音乐的示例中,推荐的状态将是 Active,因为更激进的状态会停止音乐。如果应用程序希望避免中断后台活动,那么它应该避免将网页视图置于比 recommendedState 提供的更激进的资源节约生命周期状态。

另请参阅 WebEngineView::lifecycleStateWebEngineView::recommendedState。在 Widgets API 中的等效项是 lifecycleStaterecommendedState

DOM扩展

lifecycleState 属性与 Page Lifecycle API 规范 相关联,该规范指定了两个新的 DOM 事件,freezeresume,并添加了一个新的 Document.wasDiscarded 布尔属性。当从 Active 状态转换到 Frozen state 时,以及反之,freezeresume 事件会被触发。当从 Discarded 状态转换到 Active 状态时,Document.wasDiscarded 属性会被设置为 true

流程模型

Qt WebEngine 使用多个操作系统进程来隔离网站与彼此以及客户端应用程序,从而提高安全性和鲁棒性。支持以下进程模型,或在操作系统进程之间划分网站的方式:

每个站点实例的进程

这是默认模型。来自不同站点的页面被放入不同的进程中,对同一站点的不同访问也被隔离。

如果两个网页源自相同的注册域名(例如,wikipedia.org)和协议(例如,https),则它们被视为属于同一站点。这与同源策略类似,但子域名被忽略。例如,https://en.wikipedia.org/https://de.wikipedia.org/ 都属于同一站点。

站点实例是属于同一站点的一组网页。当应用程序明确地将URL加载到Qt WebEngine中时(例如通过setUrl),会为该页面创建一个新的站点实例。然而,当用户点击页面上的同站点链接时,现有的站点实例仅会扩展更多的页面。

例如,在Simple Browser示例中,当用户打开两个标签页并显式地在URL栏中输入https://en.wikipedia.org/时,这两个标签页将拥有各自独立的操作系统进程(因为显式输入URL会创建一个新的站点实例)。然而,当用户随后中键点击一些同站点的链接以打开更多标签页时,这些新标签页将共享相同的操作系统进程(因为用户交互会扩展现有的站点实例)。

每个站点的处理过程

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

这种模型的优点是减少了内存消耗,因为更多的网页将共享进程。缺点包括安全性、健壮性和响应性的降低。

要启用此模型,请使用命令行参数 --process-per-site。请参阅 使用命令行参数

单进程

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

拼写检查器

Qt WebEngine 支持将拼写检查功能集成到 HTML 表单中,使用户能够提交经过拼写检查的消息。当用户点击带有下划线的拼写错误单词时,默认的上下文菜单会显示最多四个建议。选择一个建议将替换拼写错误的单词。

为了能够检查拼写,拼写检查器需要字典。它支持来自Hunspell项目的字典,但它们必须编译成特殊的二进制格式。一个Hunspell字典由两个文件组成:

  • 一个 .dic 文件,它是一个包含该语言单词的字典

  • 一个.aff文件,用于定义字典中特殊标志的含义

这两个文件可以通过使用与Qt一起提供的qwebengine_convert_dict工具转换为bdic格式。当Qt WebEngine拼写检查器初始化时,它将尝试加载bdict字典并检查它们的一致性。

如果设置了QTWEBENGINE_DICTIONARIES_PATH,拼写检查器将使用指定目录中的字典,而不查找其他位置。否则,如果存在相对于可执行文件的qtwebengine_dictionaries目录,它将使用该目录。如果不存在,它将在QT_INSTALL_PREFIX/qtwebengine_dictionaries中查找。

在macOS上,根据Qt WebEngine在构建时的配置方式,有两种可能找到拼写检查数据的方式:

  • Hunspell 词典(默认)- 使用 .bdic 词典,就像在其他平台上一样

  • 原生字典 - 使用macOS拼写检查API(这意味着结果将取决于已安装的操作系统字典)

因此,在macOS Hunspell的情况下,Qt WebEngine将在应用程序包内的qtwebengine_dictionaries子目录中查找,该子目录位于Resources目录中,同时也会在Qt框架包内的Resources目录中查找。

总结一下,在使用Hunspell的情况下,考虑以下路径:

  • QTWEBENGINE_DICTIONARIES_PATH,如果已设置

  • QCoreApplication::applicationDirPath()/qtwebengine_dictionaries 或 QCoreApplication::applicationDirPath()/../Contents/Resources/qtwebengine_dictionaries(在 macOS 上)

  • [QLibraryInfo::DataPath]/qtwebengine_dictionaries 或 path/to/ QtWebEngineCore .framework/Resources/qtwebengine_dictionaries (macOS上的Qt框架包)

拼写检查默认是禁用的,可以通过在基于小部件的应用程序中使用setSpellCheckEnabled()方法以及在Qt Quick应用程序中使用spellCheckEnabled属性来为每个配置文件启用。

当前用于拼写检查的语言是按配置文件定义的,可以使用setSpellCheckLanguages()方法或spellCheckLanguages属性进行设置。

此功能可以通过构建和运行Spellchecker Example来测试。

Qt WebEngine 也可以在没有拼写检查器支持的情况下编译,使用 webengine-spellchecker 配置开关。

qt-configure-module path\to\qtwebengine\sources -no-webengine-spellchecker

更多信息,请参见Qt配置选项。

此功能在Qt 5.8.0中添加了支持。

触摸

Qt WebEngine 支持触摸设备用于导航和与网页交互。

应用程序可以通过以下方式禁止使用触摸事件:

  • 在命令行中传递标志--touch-events=disabled将禁用JavaScript API中的触摸事件支持(意味着ontouchstart和相关处理程序将不会出现在document.window对象中)。触摸事件仍将传递给网页。

  • WebEngine视图的焦点代理对象上使用QObject::installEventFilter安装事件过滤器对象,并过滤掉所有触摸事件。

查看源代码

Qt WebEngine 支持查看网页的HTML源代码。

此功能可以从自定义菜单中使用或分配给自定义事件。有关更多信息,请参阅WebEngineView::WebActionWebAction

此功能可以通过在Simple BrowserNano Browser中打开网页,然后在上下文菜单中选择Page Source来测试。Page Source上下文菜单项会在新标签页中打开源代码视图。

要在当前标签页中打开源代码视图,也支持使用view-source URI scheme的URL。例如,您可以在URL栏中输入以下URL以查看qt.io网页的HTML源代码:

view-source:https://www.qt.io/

使用view-source URI scheme自动补全不完整的URL使此功能的使用更加舒适。例如,以下不完整的URL也会加载qt.io网页的源代码视图:

view-source:qt.io

此功能在Qt 5.8.0中添加了支持。

网页通知

Qt WebEngine 支持 JavaScript Web Notifications API。应用程序必须通过使用 QWebEnginePage::Notifications 或 WebEngineView.Notifications 明确允许该功能。

此功能在 Qt 5.13.0 中添加了支持。

WebGL

Qt WebEngine 支持某些图形堆栈设置的 WebGL。用户可以使用由 QtWebEngine 驱动的应用程序访问 chrome://gpu 页面。图形功能状态 概览会显示当前平台设置是否支持 WebGL。用户还可以查看 WebGL 报告

默认情况下启用了WebGL支持。您可以使用WebGLEnabled设置来禁用它。

WebRTC

WebRTC 通过简单的 API 为浏览器提供实时通信(RTC)功能。有关更多信息,请参阅 WebEngineView.Feature 和 QWebEnginePage::Feature。

此功能可以通过设置网络摄像头或麦克风,然后在Simple BrowserNano Browser中打开https://test.webrtc.org/进行测试。