Back to Qt.io
Contact Us Blog Download Qt

QWebEngineUrlScheme Class

QWebEngineUrlScheme 类可配置自定义 URL 方案。更多

头文件： #include <QWebEngineUrlScheme>
CMake： find_package(Qt6 REQUIRED COMPONENTS WebEngineCore)
target_link_libraries(mytarget PRIVATE Qt6::WebEngineCore)
qmake： QT += webenginecore

公共类型

enum Flag { SecureScheme, LocalScheme, LocalAccessAllowed, NoAccessAllowed, ServiceWorkersAllowed, …, FetchApiAllowed }
flags Flags
enum SpecialPort { PortUnspecified }
enum class Syntax { HostPortAndUserInformation, HostAndPort, Host, Path }

公共函数

QWebEngineUrlScheme()
QWebEngineUrlScheme(const QByteArray &name)
QWebEngineUrlScheme(const QWebEngineUrlScheme &that)
QWebEngineUrlScheme(QWebEngineUrlScheme &&that)
~QWebEngineUrlScheme()
int defaultPort() const
QWebEngineUrlScheme::Flags flags() const
QByteArray name() const
void setDefaultPort(int newValue)
void setFlags(QWebEngineUrlScheme::Flags newValue)
void setName(const QByteArray &newValue)
void setSyntax(QWebEngineUrlScheme::Syntax newValue)
QWebEngineUrlScheme::Syntax syntax() const
bool operator!=(const QWebEngineUrlScheme &that) const
QWebEngineUrlScheme &operator=(QWebEngineUrlScheme &&that)
QWebEngineUrlScheme &operator=(const QWebEngineUrlScheme &that)
bool operator==(const QWebEngineUrlScheme &that) const

静态公共成员

void registerScheme(const QWebEngineUrlScheme &scheme)
QWebEngineUrlScheme schemeByName(const QByteArray &name)

详细说明

网络引擎 URL 方案从网络引擎的角度描述 URL 方案，指定如何解析该方案的 URL，以及对来自此类 URL 的资源应设置哪些安全限制。

自定义 URL 方案必须在应用程序启动时尽早配置，然后再创建任何Qt WebEngine 类。一般来说，这意味着需要在创建QGuiApplication 或QApplication 实例之前配置方案。

每个已注册的方案配置都适用于所有配置文件。

int main(int argc, char **argv)
{
    QWebEngineUrlScheme scheme("myscheme");
    scheme.setSyntax(QWebEngineUrlScheme::Syntax::HostAndPort);
    scheme.setDefaultPort(2345);
    scheme.setFlags(QWebEngineUrlScheme::SecureScheme);
    QWebEngineUrlScheme::registerScheme(scheme);
    ...
}

要实际使用自定义 URL 方案，必须在配置文件中创建并注册QWebEngineUrlSchemeHandler 。

另请参阅 QWebEngineUrlSchemeHandler 。

成员类型文档

枚举 QWebEngineUrlScheme::Flag
flags QWebEngineUrlScheme::Flags

此枚举类型指定了应适用于 URL 方案的安全选项。

常量值说明
QWebEngineUrlScheme::SecureScheme0x1表示 URL 方案可能是可信的。该标志只适用于通过加密或其他方式确保数据真实性、保密性和完整性的 URL 方案。安全内置方案的示例包括https （已验证和加密）和qrc （仅本地资源），而http 则是不安全方案的示例。
QWebEngineUrlScheme::LocalScheme0x2表示 URL 方案提供对本地资源的访问。该标记的目的是防止网络内容访问本地资源。只有带有LocalAccessAllowed 标志的方案才能从带有LocalScheme 标志的方案中加载资源。唯一带有该标志的内置方案是file 。
QWebEngineUrlScheme::LocalAccessAllowed0x4表示允许此方案的内容从带有LocalScheme 标志的方案中加载资源。
QWebEngineUrlScheme::NoAccessAllowed0x8表示应强制此方案中的所有内容具有唯一的不透明来源：没有两个资源具有相同的来源。
QWebEngineUrlScheme::ServiceWorkersAllowed0x10表示应启用服务 Workers API。
QWebEngineUrlScheme::ViewSourceAllowed0x20表示应启用 "视图源 "功能。
QWebEngineUrlScheme::ContentSecurityPolicyIgnored0x40表示对该方案的访问应绕过所有内容安全策略检查。
QWebEngineUrlScheme::CorsEnabled0x80启用此方案的跨源资源共享 (CORS)。要让不同来源的文档加载内容，包括从其他方案访问，必须使用此标记。QWebEngineUrlRequestJob 类会自动生成相应的 CORS 标头。默认情况下，只有http 和https 启用了 CORS。(在 Qt 5.14 中添加）
QWebEngineUrlScheme::FetchApiAllowed (since Qt 6.6)0x100启用 HTML5 fetch API 和XMLHttpRequest.send 与 body 一起使用的 URL 方案。默认情况下，只有http 和https 可以使用 Fetch API 或带有正文的XMLHttpRequest 发送。

Flags 类型是QFlags<Flag> 的类型定义。它存储 Flag 值的 OR 组合。

enum QWebEngineUrlScheme::SpecialPort

该枚举类型为defaultPort 定义了特殊值。

常量值说明
QWebEngineUrlScheme::PortUnspecified-1表示 URL 方案中没有端口元素。

enum class QWebEngineUrlScheme::Syntax

该枚举类型列出了 URL 语法类型。

要对自定义 URL 方案应用同源策略，WebEngine 必须能够计算 URL 的来源（主机和端口组合）。Host... 选项表示 URL 方案符合标准 URL 语法（如http ），并自动启用同源策略。Path 选项表示 URL 方案使用了非标准语法，不能应用同源策略。

常量值说明
QWebEngineUrlScheme::Syntax::HostPortAndUserInformation0此类型 URL 的授权组件包含所有标准元素：主机、端口、用户名和密码。没有端口的 URL 将使用defaultPort （不得为PortUnspecified ）。
QWebEngineUrlScheme::Syntax::HostAndPort1此类 URL 的授权组件只有主机和端口元素。不含端口的 URL 将使用defaultPort （不能是PortUnspecified ）。
QWebEngineUrlScheme::Syntax::Host2该类型 URL 的授权组件只有主机部分，没有端口。defaultPort 必须设置为PortUnspecified 。
QWebEngineUrlScheme::Syntax::Path3这种类型的 URL 完全没有权限部分。方案名称和分隔符 (:) 之后的所有内容都将按原样保留，不会进行验证或规范化。此类方案的所有 URL 都将被视为具有相同的来源（除非使用了NoAccessAllowed 标志）。

成员函数文档

QWebEngineUrlScheme::QWebEngineUrlScheme()

构建一个带默认值的网络引擎 URL 方案。

[explicit] QWebEngineUrlScheme::QWebEngineUrlScheme(const QByteArray &name)

使用给定的name 构建网络引擎 URL 方案。

QWebEngineUrlScheme::QWebEngineUrlScheme(const QWebEngineUrlScheme &that)

副本that.

QWebEngineUrlScheme::QWebEngineUrlScheme(QWebEngineUrlScheme &&that)

移动that 。

[noexcept] QWebEngineUrlScheme::~QWebEngineUrlScheme()

销毁此对象。

int QWebEngineUrlScheme::defaultPort() const

返回此 URL 方案的默认端口。

默认值是PortUnspecified 。

另请参阅 setDefaultPort()。

QWebEngineUrlScheme::Flags QWebEngineUrlScheme::flags() const

返回此 URL 方案的标志。

默认值为空标志集。

另请参阅 Flags 和setFlags()。

QByteArray QWebEngineUrlScheme::name() const

返回此 URL 方案的名称。

默认值为空字符串。

另请参阅 setName()。

[static] void QWebEngineUrlScheme::registerScheme(const QWebEngineUrlScheme &scheme)

使用网络引擎的 URL 解析器和安全模型注册scheme 。

建议所有自定义 URL 方案都在应用程序启动时首先使用此函数注册，即使要使用默认选项也是如此。

警告 在应用程序启动时，必须在创建任何WebEngine 类之前尽早调用此函数。延迟调用将被忽略。

另请参阅 schemeByName()。

[static] QWebEngineUrlScheme QWebEngineUrlScheme::schemeByName(const QByteArray &name)

使用给定的name 或默认构建的方案返回网络引擎 URL 方案。

另请参阅 registerScheme()。

void QWebEngineUrlScheme::setDefaultPort(int newValue)

将此 URL 方案的默认端口设置为newValue 。

另请参阅 defaultPort() 。

void QWebEngineUrlScheme::setFlags(QWebEngineUrlScheme::Flags newValue)

将此 URL 方案的标志设置为newValue 。

另请参阅 Flags 和flags()。

void QWebEngineUrlScheme::setName(const QByteArray &newValue)

将此 URL 方案的名称设置为newValue 。

注意： 名称会自动转换为小写。

另请参阅 name() 。

void QWebEngineUrlScheme::setSyntax(QWebEngineUrlScheme::Syntax newValue)

将此 URL 方案的语法类型设为newValue 。

另请参阅 Syntax 和syntax()。

QWebEngineUrlScheme::Syntax QWebEngineUrlScheme::syntax() const

返回此 URL 方案的语法类型。

默认值为Path 。

另请参阅 Syntax 和setSyntax()。

bool QWebEngineUrlScheme::operator!=(const QWebEngineUrlScheme &that) const

如果 this 和that 对象不相等，则返回true 。

QWebEngineUrlScheme &QWebEngineUrlScheme::operator=(QWebEngineUrlScheme &&that)

移动that 。

QWebEngineUrlScheme &QWebEngineUrlScheme::operator=(const QWebEngineUrlScheme &that)

副本that.

bool QWebEngineUrlScheme::operator==(const QWebEngineUrlScheme &that) const

如果 this 和that 对象相等，则返回true 。

© 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.