QQuickWebEngineProfile Class
QQuickWebEngineProfile 类提供了多个页面共享的网络引擎配置文件。更多
| Header： | #include <QQuickWebEngineProfile> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS WebEngineQuick)target_link_libraries(mytarget PRIVATE Qt6::WebEngineQuick) |
| qmake： | QT += webenginequick |
| 在 QML 中： | WebEngineProfile |
| 继承： | QObject |
公共类型
| enum | HttpCacheType { MemoryHttpCache, DiskHttpCache, NoCache } |
| enum | PersistentCookiesPolicy { NoPersistentCookies, AllowPersistentCookies, ForcePersistentCookies } |
(since 6.8) enum class | PersistentPermissionsPolicy { AskEveryTime, StoreInMemory, StoreOnDisk } |
属性
|
|
公共功能
| QQuickWebEngineProfile(QObject *parent = nullptr) | |
(since QtWebEngine 6.9) | QQuickWebEngineProfile(const QString &storageName, QObject *parent = nullptr) |
| QString | cachePath() const |
| void | clearHttpCache() |
| QWebEngineClientCertificateStore * | clientCertificateStore() |
(since 6.8) QWebEngineClientHints * | clientHints() const |
| QWebEngineCookieStore * | cookieStore() const |
| QString | downloadPath() const |
| QString | httpAcceptLanguage() const |
| int | httpCacheMaximumSize() const |
| QQuickWebEngineProfile::HttpCacheType | httpCacheType() const |
| QString | httpUserAgent() const |
| void | installUrlSchemeHandler(const QByteArray &scheme, QWebEngineUrlSchemeHandler *handler) |
| bool | isOffTheRecord() const |
| bool | isPushServiceEnabled() const |
| bool | isSpellCheckEnabled() const |
(since 6.8) QList<QWebEnginePermission> | listAllPermissions() const |
(since 6.8) QList<QWebEnginePermission> | listPermissionsForOrigin(const QUrl &securityOrigin) const |
(since 6.8) QList<QWebEnginePermission> | listPermissionsForPermissionType(QWebEnginePermission::PermissionType permissionType) const |
| QQuickWebEngineProfile::PersistentCookiesPolicy | persistentCookiesPolicy() const |
| QQuickWebEngineProfile::PersistentPermissionsPolicy | persistentPermissionsPolicy() const |
| QString | persistentStoragePath() const |
(since 6.8) QWebEnginePermission | queryPermission(const QUrl &securityOrigin, QWebEnginePermission::PermissionType permissionType) const |
| void | removeAllUrlSchemeHandlers() |
| void | removeUrlScheme(const QByteArray &scheme) |
| void | removeUrlSchemeHandler(QWebEngineUrlSchemeHandler *handler) |
| void | setCachePath(const QString &path) |
| void | setDownloadPath(const QString &path) |
| void | setHttpAcceptLanguage(const QString &httpAcceptLanguage) |
| void | setHttpCacheMaximumSize(int maxSize) |
| void | setHttpCacheType(QQuickWebEngineProfile::HttpCacheType) |
| void | setHttpUserAgent(const QString &userAgent) |
| void | setOffTheRecord(bool offTheRecord) |
| void | setPersistentCookiesPolicy(QQuickWebEngineProfile::PersistentCookiesPolicy) |
| void | setPersistentPermissionsPolicy(QQuickWebEngineProfile::PersistentPermissionsPolicy) |
| void | setPersistentStoragePath(const QString &path) |
| void | setPushServiceEnabled(bool enable) |
| void | setSpellCheckEnabled(bool enabled) |
| void | setSpellCheckLanguages(const QStringList &languages) |
| void | setStorageName(const QString &name) |
| void | setUrlRequestInterceptor(QWebEngineUrlRequestInterceptor *interceptor) |
| QStringList | spellCheckLanguages() const |
| QString | storageName() const |
| const QWebEngineUrlSchemeHandler * | urlSchemeHandler(const QByteArray &scheme) const |
| QQuickWebEngineScriptCollection * | userScripts() const |
信号
| void | cachePathChanged() |
(since 6.7) void | clearHttpCacheCompleted() |
| void | downloadFinished(QQuickWebEngineDownloadRequest *download) |
| void | downloadPathChanged() |
| void | downloadRequested(QQuickWebEngineDownloadRequest *download) |
| void | httpAcceptLanguageChanged() |
| void | httpCacheMaximumSizeChanged() |
| void | httpCacheTypeChanged() |
| void | httpUserAgentChanged() |
| void | offTheRecordChanged() |
| void | persistentCookiesPolicyChanged() |
| void | persistentPermissionsPolicyChanged() |
| void | persistentStoragePathChanged() |
| void | presentNotification(QWebEngineNotification *notification) |
| void | pushServiceEnabledChanged() |
| void | spellCheckEnabledChanged() |
| void | spellCheckLanguagesChanged() |
| void | storageNameChanged() |
静态公共成员
| QQuickWebEngineProfile * | defaultProfile() |
详细说明
网络引擎配置文件包含设置、脚本、持久 cookie 策略以及属于该配置文件的所有网络引擎页面共享的访问链接列表。
访问过的链接信息与持久 cookie 和其他持久数据一起存储在由storageName 属性决定的存储空间中。持久数据存储在由persistentStoragePath 属性决定的子目录中，缓存存储在由cachePath 属性决定的子目录中。httpCacheType 属性描述了缓存的类型：内存或磁盘。如果只设置了storageName 属性，其他值将根据该属性自动生成。如果要手动指定任何值，应在创建任何属于配置文件的页面之前进行。
预案可用于将页面相互隔离。一个典型的用例是用于私人浏览模式的专用非记录预案。非记录配置文件会强制 Cookie、HTTP 缓存和其他通常持久的数据只存储在内存中。offTheRecord 属性表示配置文件是否为非记录配置文件。
默认配置文件可通过defaultProfile() 访问。这是一个内置配置文件，所有未使用其他配置文件创建的网页都属于该配置文件。
WebEngineProfile 实例可通过 QQuickWebEngineProfile 类从 C++ 中创建和访问，该类在 C++ 中提供了更多的功能。这样，Qt Quick 应用程序就可以拦截 URL 请求（QQuickWebEngineProfile::setRequestInterceptor），或注册自定义 URL 方案（QQuickWebEngineProfile::installUrlSchemeHandler ）。
拼写检查 HTML 表单字段可通过设置spellCheckEnabled 属性在每个配置文件中启用，拼写检查使用的当前语言可通过spellCheckLanguages 属性设置。
成员类型文档
enum QQuickWebEngineProfile::HttpCacheType
该枚举描述 HTTP 缓存类型：
| 常量 | 值 | 描述 |
|---|---|---|
QQuickWebEngineProfile::MemoryHttpCache | 0 | 使用内存缓存。如果设置了off-the-record ，则默认使用此类型。 |
QQuickWebEngineProfile::DiskHttpCache | 1 | 使用磁盘缓存。如果未设置off-the-record ，则默认使用此值。如果设置了off-the-record ，则返回MemoryHttpCache 。 |
QQuickWebEngineProfile::NoCache | 2 | 同时禁用内存和磁盘缓存。(在 Qt 5.7 中添加） |
enum QQuickWebEngineProfile::PersistentCookiesPolicy
该枚举描述了 cookie 持久性的策略：
| 常量 | 值 | 描述 |
|---|---|---|
QQuickWebEngineProfile::NoPersistentCookies | 0 | 会话和持久 cookie 都存储在内存中。如果设置了off-the-record 或没有可用的持久性数据路径，则只能使用此设置。 |
QQuickWebEngineProfile::AllowPersistentCookies | 1 | 标记为 "持久 "的 Cookie 会保存到磁盘并从磁盘恢复，而会话 Cookie 只会保存到磁盘，用于崩溃恢复。这是默认设置。 |
QQuickWebEngineProfile::ForcePersistentCookies | 2 | 会话和永久 cookie 都保存到磁盘并从磁盘恢复。 |
[since 6.8] enum class QQuickWebEngineProfile::PersistentPermissionsPolicy
该枚举描述了权限持久性策略：
| 常量 | 值 | 说明 |
|---|---|---|
QQuickWebEngineProfile::PersistentPermissionsPolicy::AskEveryTime | 0 | 应用程序在每次需要权限时都会请求，无论之前是否已授予权限。这样做的目的是为了与现有应用程序向后兼容，否则不建议使用。 |
QQuickWebEngineProfile::PersistentPermissionsPolicy::StoreInMemory | 1 | 只有在第一次需要权限时才会提出请求。之后的任何请求都将根据用户最初的选择自动批准或拒绝。这将延续到使用同一QQuickWebEngineProfile 实例的所有页面，直到应用程序关闭为止。如果设置了off-the-record 或没有可用的持久化数据路径，则会应用此设置。 |
QQuickWebEngineProfile::PersistentPermissionsPolicy::StoreOnDisk | 2 | 工作方式与PersistentPermissionsInMemory 相同，但权限会保存到磁盘并从磁盘恢复。这是默认设置。 |
此枚举在 Qt 6.8 中引入。
属性文档
cachePath : QString
配置文件缓存（尤其是 HTTP 缓存）存储位置的路径。
默认情况下，缓存存储在QStandardPaths::writableLocation(QStandardPaths::CacheLocation) 下面的目录中，该目录使用storageName 命名。
访问功能：
| QString | cachePath() const |
| void | setCachePath(const QString &path) |
通知信号：
| void | cachePathChanged() |
[since QtWebEngine 1.9] downloadPath : QString
下载文件存储位置的路径。
覆盖用于下载位置的默认路径，将其设置为path 。
如果设置为空字符串，则恢复默认路径。
注： 默认情况下，下载路径为QStandardPaths::DownloadLocation 。
此属性在 QtWebEngine 1.9 中引入。
访问函数：
| QString | downloadPath() const |
| void | setDownloadPath(const QString &path) |
Notifier 信号：
| void | downloadPathChanged() |
httpAcceptLanguage : QString
接受语言 HTTP 请求头字段的值。
访问功能：
| QString | httpAcceptLanguage() const |
| void | setHttpAcceptLanguage(const QString &httpAcceptLanguage) |
通知信号：
| void | httpAcceptLanguageChanged() |
httpCacheMaximumSize : int
HTTP 缓存的最大大小。如果是0 ，大小将由QtWebEngine 自动控制。默认值为0 。
访问功能：
| int | httpCacheMaximumSize() const |
| void | setHttpCacheMaximumSize(int maxSize) |
Notifier 信号：
| void | httpCacheMaximumSizeChanged() |
另请参阅 httpCacheType 。
httpCacheType : HttpCacheType
该枚举描述 HTTP 缓存的类型。
如果配置文件未记录或未设置storageName ，则返回MemoryHttpCache 。
访问功能：
| QQuickWebEngineProfile::HttpCacheType | httpCacheType() const |
| void | setHttpCacheType(QQuickWebEngineProfile::HttpCacheType) |
通知信号：
| void | httpCacheTypeChanged() |
httpUserAgent : QString
随 HTTP 发送的用户代理字符串，用于识别浏览器。
访问功能：
| QString | httpUserAgent() const |
| void | setHttpUserAgent(const QString &userAgent) |
通知信号：
| void | httpUserAgentChanged() |
[since QtWebEngine 6.5] isPushServiceEnabled : bool
推送信息服务是否启用。
注： 默认情况下，推送消息服务处于禁用状态。
注： Qt WebEngine 使用Firebase Cloud Messaging（FCM）作为浏览器推送服务。因此，所有推送消息都将通过谷歌推送服务及其各自的服务器。
此属性在 QtWebEngine 6.5 中引入。
访问功能：
| bool | isPushServiceEnabled() const |
| void | setPushServiceEnabled(bool enable) |
Notifier 信号：
| void | pushServiceEnabledChanged() |
offTheRecord : bool
网络引擎配置文件是否为非记录配置文件。非记录配置文件会强制 Cookie、HTTP 缓存和其他通常持久的数据只存储在内存中。配置文件默认为非记录型。
要将配置文件从"不记录 "行为改为基于磁盘的行为，还需要设置适当的storageName 。
访问功能：
| bool | isOffTheRecord() const |
| void | setOffTheRecord(bool offTheRecord) |
Notifier 信号：
| void | offTheRecordChanged() |
另请参阅 setStorageName() 。
persistentCookiesPolicy : PersistentCookiesPolicy
该枚举描述了 cookie 持久性策略。如果配置文件不在记录中，则返回NoPersistentCookies 。
访问功能：
| QQuickWebEngineProfile::PersistentCookiesPolicy | persistentCookiesPolicy() const |
| void | setPersistentCookiesPolicy(QQuickWebEngineProfile::PersistentCookiesPolicy) |
通知器信号：
| void | persistentCookiesPolicyChanged() |
[since 6.8] persistentPermissionsPolicy : PersistentPermissionsPolicy
描述权限持久性策略。如果配置文件是非记录的，则返回NoPersistentCookies 。
此属性在 Qt 6.8 中引入。
访问函数：
| QQuickWebEngineProfile::PersistentPermissionsPolicy | persistentPermissionsPolicy() const |
| void | setPersistentPermissionsPolicy(QQuickWebEngineProfile::PersistentPermissionsPolicy) |
Notifier 信号：
| void | persistentPermissionsPolicyChanged() |
persistentStoragePath : QString
浏览器和网页内容的持久数据存储位置的路径。持久数据包括持久 cookie、HTML5 本地存储和访问过的链接。
默认情况下，存储位置位于QStandardPaths::writableLocation(QStandardPaths::AppDataLocation) 以下，目录名为storageName 。
访问功能：
| QString | persistentStoragePath() const |
| void | setPersistentStoragePath(const QString &path) |
通知信号：
| void | persistentStoragePathChanged() |
[since QtWebEngine 1.4] spellCheckEnabled : bool
此属性表示是否启用了网络引擎拼写检查器。
该属性在 QtWebEngine 1.4 中引入。
访问函数：
| bool | isSpellCheckEnabled() const |
| void | setSpellCheckEnabled(bool enabled) |
Notifier 信号：
| void | spellCheckEnabledChanged() |
[since QtWebEngine 1.4] spellCheckLanguages : QStringList
该属性包含拼写检查器使用的语言。
该属性在 QtWebEngine 1.4 中引入。
访问函数：
| QStringList | spellCheckLanguages() const |
| void | setSpellCheckLanguages(const QStringList &languages) |
Notifier 信号：
| void | spellCheckLanguagesChanged() |
storageName : QString
存储名称，用于为每个使用磁盘存储持久数据和缓存的配置文件创建单独的子目录。
访问功能：
| QString | storageName() const |
| void | setStorageName(const QString &name) |
通知信号：
| void | storageNameChanged() |
另请参阅 persistentStoragePath 和cachePath 。
成员函数文档
QQuickWebEngineProfile::QQuickWebEngineProfile(QObject *parent = nullptr)
使用父配置文件parent 构建一个新的非记录配置文件。
非记录配置文件不会在本地机器上留下记录，也没有持久数据或缓存。因此，HTTP 缓存只能在内存中，cookie 只能是非持久的。尝试更改这些设置不会有任何效果。
[explicit, since QtWebEngine 6.9] QQuickWebEngineProfile::QQuickWebEngineProfile(const QString &storageName, QObject *parent = nullptr)
构建一个新的配置文件，存储名称为storageName ，父配置文件为parent 。
存储名称必须是唯一的。
基于磁盘的 QQuickWebEngineProfile 应在应用程序退出时或退出前销毁，否则缓存和持久化数据可能无法完全刷新到磁盘。
此函数在 QtWebEngine 6.9 中引入。
另请参阅 storageName().
[invokable] void QQuickWebEngineProfile::clearHttpCache()
删除配置文件的缓存项。
注意： 确保在清除操作过程中不对配置文件启动新的导航或任何操作。clearHttpCacheCompleted() 信号会通知操作完成。
注： 可通过元对象系统和 QML 调用此函数。请参见Q_INVOKABLE 。
另请参阅 WebEngineProfile::clearHttpCache() 和clearHttpCacheCompleted()。
[signal, since 6.7] void QQuickWebEngineProfile::clearHttpCacheCompleted()
clearHttpCache() 操作完成时发出该信号。
该函数在 Qt 6.7 中引入。
另请参阅 clearHttpCache()。
QWebEngineClientCertificateStore *QQuickWebEngineProfile::clientCertificateStore()
返回配置文件的客户证书存储。
[since 6.8] QWebEngineClientHints *QQuickWebEngineProfile::clientHints() const
返回与此浏览上下文相关的客户端提示设置。
注： 属性 clientHints 的获取函数。
此函数在 Qt 6.8 中引入。
另请参阅 QWebEngineClientHints 。
QWebEngineCookieStore *QQuickWebEngineProfile::cookieStore() const
返回此配置文件的 cookie 存储。
[static] QQuickWebEngineProfile *QQuickWebEngineProfile::defaultProfile()
返回默认配置文件。
默认配置文件为非记录配置文件。
另请参阅 storageName()。
[signal] void QQuickWebEngineProfile::downloadFinished(QQuickWebEngineDownloadRequest *download)
每当下载因成功完成、取消或中断（如失去连接）而停止时，都会发出该信号。download 参数包含已完成下载实例的状态。
注： 要从 C++ static_castdownload 转到QWebEngineDownloadRequest
[signal] void QQuickWebEngineProfile::downloadRequested(QQuickWebEngineDownloadRequest *download)
每当下载被触发时，就会发出该信号。download 参数包含下载的状态。下载必须通过QWebEngineDownloadRequest::accept() 明确接受，否则将默认取消。下载项目的父级是配置文件。如果下载未被接受，它将在信号发出后立即被删除。此信号不能与队列连接一起使用。
注意： 要从 C++ static_castdownload 转为QWebEngineDownloadRequest
void QQuickWebEngineProfile::installUrlSchemeHandler(const QByteArray &scheme, QWebEngineUrlSchemeHandler *handler)
为配置文件中的自定义 URL 方案scheme 注册处理程序handler 。
必须在应用程序启动时首先在QWebEngineUrlScheme::registerScheme 注册该方案。
[invokable, since 6.8] QList<QWebEnginePermission> QQuickWebEngineProfile::listAllPermissions() const
返回QList QWebEnginePermission 对象，每个对象代表权限存储中当前存在的一个权限。返回的列表包含此配置文件以前授予/拒绝的所有权限，前提是这些权限属于持久类型。
注： 当 persistentPermissionPolicy() 设置为AskEveryTime 时，将返回空列表。
注： 可通过元对象系统和 QML 调用此函数。请参见Q_INVOKABLE 。
此函数在 Qt 6.8 中引入。
另请参阅 queryPermission()、listPermissionsForOrigin()、listPermissionsForPermissionType() 和QWebEnginePermission::isPersistent() 。
[invokable, since 6.8] QList<QWebEnginePermission> QQuickWebEngineProfile::listPermissionsForOrigin(const QUrl &securityOrigin) const
返回QList 的QWebEnginePermission 对象，每个对象代表权限存储中当前存在的一个权限。返回的列表包含与该配置文件的特定securityOrigin 相关联的所有先前授予/拒绝的权限，前提是这些权限属于持久类型。
注： 由于权限是按原点授予的，因此所提供的securityOrigin 将被剥离为原点形式，返回的列表将包含原点的所有权限。因此，传递 https://www.example.com/some/page.html 与传递 https://www.example.com/ 相同。
注： 可通过元对象系统和 QML 调用此函数。请参见Q_INVOKABLE 。
此函数在 Qt 6.8 中引入。
另请参阅 queryPermission()、listAllPermissions()、listPermissionsForPermissionType() 和QWebEnginePermission::isPersistent() 。
[invokable, since 6.8] QList<QWebEnginePermission> QQuickWebEngineProfile::listPermissionsForPermissionType(QWebEnginePermission::PermissionType permissionType) const
返回QList 的QWebEnginePermission 对象，每个对象代表当前权限存储中的一个权限。返回的列表包含所提供permissionType 的所有先前授予/拒绝的权限。如果权限类型是非持久的，则列表为空。
注： 当 persistentPermissionPolicy() 设置为AskEveryTime 时，将返回空列表。
注： 可通过元对象系统和 QML 调用此函数。请参见Q_INVOKABLE 。
此函数在 Qt 6.8 中引入。
另请参阅 queryPermission(),listAllPermissions(),listPermissionsForOrigin(),QWebEnginePermission::PermissionType, 和QWebEnginePermission::isPersistent().
[signal] void QQuickWebEngineProfile::presentNotification(QWebEngineNotification *notification)
每当有新创建的用户通知时，就会发出该信号。notification 参数包含用于查询数据和进行交互的QWebEngineNotification 实例。
另请参阅 WebEngineProfile::presentNotification 。
[invokable, since 6.8] QWebEnginePermission QQuickWebEngineProfile::queryPermission(const QUrl &securityOrigin, QWebEnginePermission::PermissionType permissionType) const
返回与所提供的securityOrigin 和permissionType 的单个权限相对应的QWebEnginePermission 对象。该对象可用于查询权限的当前状态或更改权限。该对象可用于查询权限的当前状态，也可用于更改权限。不要求权限已经存在；如果已知某个网站使用权限，返回的对象也可用于预先授予该权限。
注意： 只能用于持久权限类型。使用非持久permissionType 调用该函数将返回无效对象。
注： 可通过元对象系统和 QML 调用该函数。请参见Q_INVOKABLE 。
此函数在 Qt 6.8 中引入。
另请参阅 listAllPermissions(),listPermissionsForOrigin(),listPermissionsForPermissionType() 和QWebEnginePermission::PermissionType 。
void QQuickWebEngineProfile::removeAllUrlSchemeHandlers()
删除配置文件中安装的所有自定义 URL 方案处理程序。
void QQuickWebEngineProfile::removeUrlScheme(const QByteArray &scheme)
从配置文件中删除自定义 URL 方案scheme 。
另请参阅 removeUrlSchemeHandler().
void QQuickWebEngineProfile::removeUrlSchemeHandler(QWebEngineUrlSchemeHandler *handler)
从配置文件中删除自定义 URL 方案处理程序handler 。
另请参阅 removeUrlScheme().
void QQuickWebEngineProfile::setUrlRequestInterceptor(QWebEngineUrlRequestInterceptor *interceptor)
注册请求拦截器单例interceptor ，以拦截 URL 请求。
配置文件不拥有指针的所有权。
另请参阅 QWebEngineUrlRequestInfo 和QWebEngineUrlRequestInterceptor 。
QStringList QQuickWebEngineProfile::spellCheckLanguages() const
返回拼写检查器使用的语言列表。
注： 属性 spellCheckLanguages 的获取函数。
另请参阅 setSpellCheckLanguages()。
const QWebEngineUrlSchemeHandler *QQuickWebEngineProfile::urlSchemeHandler(const QByteArray &scheme) const
返回 URL 方案scheme 的自定义 URL 方案处理程序注册信息。
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
