QWebEnginePermission Class
QWebEnginePermission 是一个对象，用于访问和修改已授予或拒绝授予特定起源 URL 的单个权限的状态。更多
| Header： | #include <QWebEnginePermission> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS WebEngineCore)target_link_libraries(mytarget PRIVATE Qt6::WebEngineCore) |
| qmake： | QT += webenginecore |
| 自 | Qt 6.8 |
| 在 QML 中： | webEnginePermission |
公共类型
| enum class | PermissionType { MediaAudioCapture, MediaVideoCapture, MediaAudioVideoCapture, DesktopVideoCapture, DesktopAudioVideoCapture, …, Unsupported } |
| enum class | State { Invalid, Ask, Granted, Denied } |
属性
- isValid : const bool
- origin : const QUrl
- permissionType : const PermissionType
- state : const State
公共函数
| void | deny() const |
| void | grant() const |
| bool | isValid() const |
| QUrl | origin() const |
| QWebEnginePermission::PermissionType | permissionType() const |
| void | reset() const |
| QWebEnginePermission::State | state() const |
静态公共成员
| bool | isPersistent(QWebEnginePermission::PermissionType permissionType) |
详细说明
典型的使用模式如下：
- 网站请求特定权限，触发QWebEnginePage::permissionRequested() 信号；
- 信号处理器触发提示，询问用户是否授予权限；
- 当用户做出决定后，应用程序调用grant() 或deny() ；
另外，有意修改已授予权限的应用程序可以使用QWebEngineProfile::listAllPermissions() 获取与配置文件相关的现有权限列表，或使用QWebEngineProfile::queryPermission() 获取特定权限的 QWebEnginePermission 对象。
origin() 属性可用于查询 QWebEnginePermission 与哪个起源相关联，而permissionType() 属性则描述了所请求权限的类型。网站来源是其方案、主机名和端口的组合。权限是按起源授予的；因此，如果网页https://www.example.com:12345/some/page.html 请求一个权限，它将被授予给起源https://www.example.com:12345/ 。
QWebEnginePermission::PermissionType 描述了 Qt XML 支持的所有权限类型。只有某些权限类型会在浏览会话之间被记住，它们是WebEngine 持久的。非持久权限会在每次网站请求时查询用户。您可以使用静态方法 () 在运行时检查权限类型是否持久。QWebEnginePermission::isPersistent
持久权限存储在活动的QWebEngineProfile 中，其生命周期取决于QWebEngineProfile::persistentPermissionsPolicy() 的值。默认情况下，已命名配置文件将权限存储在磁盘上，而非记录型配置文件将权限存储在内存中（并在销毁配置文件时销毁）。存储的权限在下一次网站请求时不会询问用户，而是根据用户最初选择的分辨率自动授予或拒绝。要删除存储的权限，可调用reset() 删除。
另一方面，非持久权限只有在相关QWebEnginePage 执行导航到不同的 URL 或被销毁时才可用。
您可以使用isValid() 属性检查 QWebEnginePermission 是否处于有效状态。对于无效对象，调用grant(),deny(), 或reset() 将不起作用，而调用state() 将始终返回QWebEnginePermission::Invalid 。
另请参阅 QWebEnginePage::permissionRequested()、QWebEngineProfile::queryPermission() 和QWebEngineProfile::listAllPermissions()。
成员类型文档
enum class QWebEnginePermission::PermissionType
该枚举类型表示所请求的权限类型：
| 常量 | 值 | 说明 |
|---|---|---|
QWebEnginePermission::PermissionType::MediaAudioCapture | 1 | 访问麦克风或其他音源。此权限不具有持久性。 |
QWebEnginePermission::PermissionType::MediaVideoCapture | 2 | 访问网络摄像头或其他视频源。此权限不具有持久性。 |
QWebEnginePermission::PermissionType::MediaAudioVideoCapture | 3 | MediaAudioCapture 和 MediaVideoCapture 的组合。此权限不具有持久性。 |
QWebEnginePermission::PermissionType::DesktopVideoCapture | 4 | 访问用户屏幕内容。此权限不具有持久性。 |
QWebEnginePermission::PermissionType::DesktopAudioVideoCapture | 5 | 访问用户屏幕内容和应用程序音频。此权限不具有持久性。 |
QWebEnginePermission::PermissionType::MouseLock | 6 | 将指针锁定在网页元素内。此权限不具有持久性。 |
QWebEnginePermission::PermissionType::Notifications | 7 | 允许网站向用户发送通知。此权限具有持久性。 |
QWebEnginePermission::PermissionType::Geolocation | 8 | 访问用户的物理位置。此权限具有持久性。 |
QWebEnginePermission::PermissionType::ClipboardReadWrite | 9 | 访问用户的剪贴板。此权限具有持久性。 |
QWebEnginePermission::PermissionType::LocalFontsAccess | 10 | 访问用户计算机上安装的字体。仅适用于台式机。此权限具有持久性。 |
QWebEnginePermission::PermissionType::Unsupported | 0 | 不支持的权限类型。 |
注： 非持久权限类型是指底层存储永远不会记住的权限类型，每次网站尝试使用时都会触发权限请求。
enum class QWebEnginePermission::State
该枚举类型表示所请求权限的当前状态：
| 常量 | 值 | 描述 |
|---|---|---|
QWebEnginePermission::State::Invalid | 0 | 对象处于无效状态，任何修改所述权限的尝试都将失败。 |
QWebEnginePermission::State::Ask | 1 | 要么该权限之前未被请求过，要么permissionType() 不是持久的。 |
QWebEnginePermission::State::Granted | 2 | 权限已被授予。 |
QWebEnginePermission::State::Denied | 3 | 权限已被拒绝。 |
属性文档
[read-only] isValid : const bool
表示更改权限状态的尝试是否成功。
无效的QWebEnginePermission 是指
- permissionType() 不支持；
- origin() 无效；
- 相关配置文件已被销毁
访问功能：
| bool | isValid() const |
另请参阅 isPersistent()。
[read-only] origin : const QUrl
该属性包含权限相关来源的 URL。
网站来源是其方案、主机名和端口的组合。权限是按来源授予的；因此，如果网页https://www.example.com:12345/some/page.html 请求权限，则会授予来源https://www.example.com:12345/ 。
访问功能：
| QUrl | origin() const |
[read-only] permissionType : const PermissionType
该属性包含与该权限相关的权限类型。
访问功能：
| QWebEnginePermission::PermissionType | permissionType() const |
[read-only] state : const State
该属性显示权限的当前状态。
如果指定的permissionType() 和origin() 的权限已被授予或拒绝，则返回值分别为QWebEnginePermission::Granted 或QWebEnginePermission::Denied 。如果是首次请求权限，返回值为QWebEnginePermission::Ask 。如果对象处于无效状态，返回值为QWebEnginePermission::Invalid 。
访问函数：
| QWebEnginePermission::State | state() const |
另请参阅 isValid() 和isPersistent() 。
成员函数文档
[invokable] void QWebEnginePermission::deny() const
阻止相关起源访问请求的permissionType 。当isValid() 值为 false 时，不执行任何操作。
注： 可通过元对象系统和 QML 调用此函数。请参阅Q_INVOKABLE 。
另请参阅 grant()、reset() 和isValid()。
[invokable] void QWebEnginePermission::grant() const
允许相关起源访问请求的permissionType 。当isValid() 值为 false 时，不做任何操作。
注： 可通过元对象系统和 QML 调用此函数。请参阅Q_INVOKABLE 。
另请参阅 deny()、reset() 和isValid()。
[static invokable] bool QWebEnginePermission::isPersistent(QWebEnginePermission::PermissionType permissionType)
返回permissionType 是否具有持久性，这意味着权限的状态将被记住，下次网站请求相同权限时不会再查询用户。
注： 可通过元对象系统和 QML 调用此函数。请参阅Q_INVOKABLE 。
[invokable] void QWebEnginePermission::reset() const
从配置文件的底层存储中删除权限。默认情况下，权限存储在磁盘上（记录外配置文件除外，权限存储在内存中，并随配置文件一起销毁）。这就意味着，已经授予/拒绝的权限不会被请求两次，而是会在以后每次网站请求时自动授予/拒绝。调用 reset() 可以在下一次网站请求时再次显示查询。
当isValid() 的值为 false 时，不执行任何操作。
注： 可通过元对象系统和 QML 调用此函数。请参见Q_INVOKABLE 。
另请参阅 grant()、deny()、isValid() 和QWebEngineProfile::persistentPermissionsPolicy()。
© 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.
