QUrl Class

成员函数文档

QUrl::QUrl()

创建一个空的 QUrl 对象。

QUrl::QUrl(const QString &url, QUrl::ParsingMode parsingMode = TolerantMode)

通过解析url 来构建一个 URL。请注意，该构造函数要求传入正确的 URL 或 URL 引用，且不会尝试推测其意图。例如，以下声明：

QUrl url("example.com");

将构建一个有效的 URL，但这可能并非预期结果，因为输入中缺少scheme() 部分。对于类似上述的字符串，应用程序可能希望使用fromUserInput()。对于此构造函数或setUrl()，以下代码可能更符合预期：

QUrl url("https://example.com");

QUrl 会自动对 URL 中不允许的所有字符进行百分比编码，并对代表非保留字符（字母、数字、连字符、下划线、点和波浪号）的百分比编码序列进行解码。所有其他字符则保持原样。

使用解析器模式parsingMode 解析url 。在TolerantMode （默认模式）下，QUrl 将纠正某些错误，特别是百分号（'%'）后未跟随两个十六进制数字的情况，并且会接受任何位置上的任意字符。 在StrictMode 模式下，不允许出现编码错误，且 QUrl 还会检查是否存在未经过编码的某些禁止字符。如果在StrictMode 模式下检测到错误，isValid() 将返回 false。在此上下文中，不允许使用解析模式DecodedMode 。

示例：

QUrl url("http://www.example.com/List of holidays.xml");
// url.toEncoded() == "http://www.example.com/List%20of%20holidays.xml"

要从编码字符串构建 URL，您还可以使用fromEncoded()：

QUrl url = QUrl::fromEncoded("http://qt-project.org/List%20of%20holidays.xml");

这两个函数功能等同，且在 Qt 5 中均可接受编码数据。通常，选择 QUrl 构造函数或setUrl() 而不是fromEncoded()，取决于源数据：构造函数和setUrl() 接受QString 参数，而fromEncoded 则接受QByteArray 参数。

另请参阅 setUrl()、fromEncoded() 和TolerantMode 。

[noexcept] QUrl::QUrl(const QUrl &other)

创建other 的副本。

[noexcept] QUrl::QUrl(QUrl &&other)

通过“move”操作构造一个 QUrl 实例，使其指向与other 所指向的同一对象。

[noexcept] QUrl::~QUrl()

析构函数；在对象被删除之前立即调用。

QUrl QUrl::adjusted(QUrl::FormattingOptions options) const

返回经过调整的 URL。可以通过在options 中传递标志来自定义输出。

QUrl::ComponentFormattingOption 中的编码选项对于此方法意义不大，QUrl::PreferLocalFile 也是如此。

此方法始终等同于QUrl(url.toString(options))。

另请参阅 FormattingOptions 、toEncoded() 以及toString()。

QString QUrl::authority(QUrl::ComponentFormattingOptions options = PrettyDecoded) const

如果 URL 已定义，则返回其权威域名；否则返回空字符串。

该函数返回一个无歧义的值，其中可能包含仍采用百分比编码的字符，以及一些在QString 中无法以解码形式表示的控制序列。

参数 `options ` 控制用户信息组件的格式。本函数不允许使用 `QUrl::FullyDecoded ` 作为该参数的值。若需获取完全解码的数据，请分别调用userName()、password()、host() 和port() 函数。

另请参阅 setAuthority()、userInfo()、userName()、password()、host() 和port()。

void QUrl::clear()

重置QUrl 的内容。调用此函数后，QUrl 将等同于使用默认空构造函数构造的对象。

另请参阅 isEmpty()。

QString QUrl::errorString() const

如果最后一次修改此QUrl 对象的操作遇到了解析错误，则返回一条错误消息。如果未检测到错误，则该函数返回空字符串，且isValid()将返回true 。

该函数返回的错误消息属于技术性质，最终用户可能无法理解。它主要对试图了解QUrl 为何无法接受某些输入的开发人员有用。

另请参阅 QUrl::ParsingMode 。

QString QUrl::fileName(QUrl::ComponentFormattingOptions options = FullyDecoded) const

返回文件的名称，不包括目录路径。

请注意，如果此QUrl 对象的路径以斜杠结尾，则该文件的名称将被视为空。

如果路径中不包含任何斜杠，则将其完整地作为 fileName 返回。

示例：

QUrl url("http://qt-project.org/support/file.html");
// url.adjusted(RemoveFilename) == "http://qt-project.org/support/"
// url.fileName() == "file.html"

options 参数控制文件名部分的格式化方式。所有值都会产生明确无误的结果。当设置为QUrl::FullyDecoded 时，所有百分比编码序列都会被解码；否则，对于某些在QString 中无法以解码形式表示的控制序列，返回值中可能包含部分百分比编码序列。

另请参阅 path()。

QString QUrl::fragment(QUrl::ComponentFormattingOptions options = PrettyDecoded) const

返回 URL 的片段。要确定解析后的 URL 是否包含片段，请使用 `hasFragment()`。

options 参数控制片段组件的格式化方式。所有值均会产生无歧义的结果。当设置为QUrl::FullyDecoded 时，所有百分比编码序列都会被解码；否则，对于QString 中无法以解码形式表示的某些控制序列，返回值可能包含部分百分比编码序列。

请注意，如果存在此类无法表示的序列，QUrl::FullyDecoded 可能会导致数据丢失。建议仅在结果用于非URL上下文时使用该值。

另请参阅 setFragment() 和hasFragment()。

[static, since 6.3] QString QUrl::fromAce(const QByteArray &domain, QUrl::AceProcessingOptions options = {})

返回给定域名domain 的 Unicode 形式，该域名采用 ASCII 兼容编码（ACE）进行编码。可以通过在调用options 时传递标志来自定义输出。该函数的结果被视为与domain 等价。

如果domain 中的值无法编码，则将其转换为QString 并返回。

ASCII 兼容编码（ACE）由 RFC 3490、RFC 3491 和 RFC 3492 定义，并由 Unicode 技术标准第 46 号更新。 它是“应用程序中的域名国际化”（IDNA）规范的一部分，该规范允许使用非 US-ASCII 字符来书写域名（如"example.com" ）。

该函数在 Qt 6.3 中引入。

[static] QUrl QUrl::fromCFURL(CFURLRef url)

构建一个包含 CFURLurl 副本的 `QUrl `。

[static] QUrl QUrl::fromEncoded(QByteArrayView input, QUrl::ParsingMode mode = TolerantMode)

解析input 并返回相应的QUrl 。input 被假定为编码形式，仅包含 ASCII 字符。

使用mode 解析 URL。有关此参数的更多信息，请参阅setUrl()。在此上下文中不允许使用QUrl::DecodedMode 。

另请参阅 toEncoded() 和setUrl()。

[static] QUrl QUrl::fromLocalFile(const QString &localFile)

返回localFile 的QUrl 表示形式，将其解释为本地文件。该函数既接受以斜杠分隔的路径，也接受该平台的原生分隔符。

该函数还接受以双斜杠（或反斜杠）开头的路径，以表示远程文件，例如“//servername/path/to/file.txt”。请注意，只有某些平台才能使用QFile::open()实际打开该文件。

空的localFile 将导致URL为空（自Qt 5.4起）。

qDebug()<<QUrl::fromLocalFile("file.txt");            // QUrl("file:file.txt")
qDebug() << QUrl::fromLocalFile("/home/user/file.txt"); // QUrl("file:///home/user/file.txt")
qDebug() << QUrl::fromLocalFile("file:file.txt");       // doesn't make sense; expects path, not url with scheme

在上文代码片段的第一行中，文件 URL 是根据本地相对路径生成的。仅包含相对路径的文件 URL 只有在存在用于解析它的基 URL 时才有意义。例如：

QUrl url=QUrl::fromLocalFile("file.txt");
QUrl baseUrl=QUrl("file:/home/user/");
// 错误：会输出 QUrl("file:file.txt")，因为 url 已经包含方案
qDebug() << baseUrl.resolved(url);

要解析此类 URL，必须先去除方案：

// 正确：输出 QUrl("file:///home/user/file.txt")
url.setScheme(QString());
qDebug() << baseUrl.resolved(url);

因此，对于相对文件路径，最好使用相对 URL（即不带协议前缀）：

QUrl url=QUrl("file.txt");
QUrl baseUrl=QUrl("file:/home/user/");
// 输出 QUrl("file:///home/user/file.txt")
qDebug() << baseUrl.resolved(url);

另请参阅 toLocalFile()、isLocalFile() 和QDir::toNativeSeparators()。

[static] QUrl QUrl::fromNSURL(const NSURL *url)

创建一个包含 NSURLurl 副本的QUrl 。

[static] QString QUrl::fromPercentEncoding(const QByteArray &input)

返回input 的解码副本。首先将input 从百分比编码中解码，然后将其从UTF-8转换为Unicode。

[static] QList<QUrl> QUrl::fromStringList(const QStringList &urls, QUrl::ParsingMode mode = TolerantMode)

使用QUrl(str,mode)，将表示urls 的字符串列表转换为 URL 列表。请注意，这意味着所有字符串都必须是 URL，而不能是本地路径等。

[static] QUrl QUrl::fromUserInput(const QString &userInput, const QString &workingDirectory = QString(), QUrl::UserInputResolutionOptions options = DefaultResolution)

如果能够推导出有效URL，则根据用户提供的userInput 字符串返回一个有效URL；否则，返回无效的QUrl()。

这允许用户以纯字符串的形式输入 URL 或本地文件路径。该字符串可以手动输入到地址栏中，从剪贴板获取，或通过命令行参数传递。

当该字符串本身并非有效 URL 时，系统会基于多种假设进行最佳猜测。

如果该字符串对应于系统上的有效文件路径，则使用QUrl::fromLocalFile() 构建一个 file:// URL。

如果不是这种情况，则会尝试将该字符串转换为 http:// 或 ftp:// URL。当字符串以 'ftp' 开头时，则转换为后者。随后，结果将通过QUrl 的容错解析器进行处理；若解析成功，则返回有效的QUrl ；否则返回QUrl()。

示例：

• qt-project.org 将转换为 http://qt-project.org
• ftp.qt-project.org 变为 ftp://ftp.qt-project.org
• hostname 变为 http://hostname
• /home/user/test.html 变为 file:///home/user/test.html

为了能够处理相对路径，此方法接受一个可选的workingDirectory 路径。这在处理命令行参数时特别有用。如果workingDirectory 为空，则不会进行任何相对路径处理。

默认情况下，只有当文件实际存在于指定的工作目录中时，类似相对路径的输入字符串才会被视为相对路径。如果应用程序能够处理尚未存在的文件，则应在options 中传递AssumeLocalFile 标志。

bool QUrl::hasFragment() const

如果该 URL 包含片段（即 URL 中出现 # 符号），则返回true 。

另请参阅 fragment() 和setFragment()。

bool QUrl::hasQuery() const

如果该 URL 包含查询字符串（即其中出现了“?”），则返回true 。

另请参阅 setQuery()、query() 和hasFragment()。

QString QUrl::host(QUrl::ComponentFormattingOptions options = FullyDecoded) const

如果 URL 已定义，则返回其主机名；否则返回空字符串。

options 参数控制主机名的格式。QUrl::EncodeUnicode 选项将使该函数以ASCII兼容编码（ACE）形式返回主机名，这适用于非8位兼容或需要传统主机名的通道（例如DNS请求或HTTP请求头）。 如果未指定该标志，则该函数将根据允许的顶级域名列表（参见idnWhitelist()），以 Unicode 形式返回国际域名 (IDN)。

所有其他标志均被忽略。主机名不能包含控制字符或百分号，因此返回值可视为已完全解码。

另请参阅 setHost()、idnWhitelist()、setIdnWhitelist() 以及authority()。

[static] QStringList QUrl::idnWhitelist()

返回当前允许其组成中包含非ASCII字符的顶级域名的白名单。

有关此列表的依据，请参阅setIdnWhitelist()。

另请参阅 setIdnWhitelist() 和AceProcessingOption 。

bool QUrl::isEmpty() const

如果 URL 没有数据，则返回true ；否则返回false 。

另请参阅 clear()。

bool QUrl::isLocalFile() const

如果该 URL 指向本地文件路径，则返回 `true `。如果 URL 的方案为“file”，则该 URL 即为本地文件路径。

请注意，即使最终的文件路径无法通过QFile::open() 打开，该函数仍会将包含主机名的 URL 视为本地文件路径。

另请参阅 fromLocalFile() 和toLocalFile()。

bool QUrl::isParentOf(const QUrl &childUrl) const

如果该 URL 是childUrl 的父 URL，则返回true 。如果这两个 URL 具有相同的方案和权限，且该 URL 的路径是childUrl 路径的父路径，则childUrl 是该 URL 的子 URL。

bool QUrl::isRelative() const

如果 URL 是相对的，则返回true ；否则返回false 。如果 URL 的方案未定义，则该 URL 被视为相对引用；因此，此函数等同于调用scheme()。isEmpty()。

相对引用在 RFC 3986 第 4.2 节中进行了定义。

另请参阅 Relative URLs vs Relative Paths 。

bool QUrl::isValid() const

如果 URL 不为空且有效，则返回true ；否则返回false 。

该 URL 将经过符合性测试。URL 的每个部分都必须符合 URI 标准的编码规则，该 URL 才会被判定为有效。

boolcheckUrl(constQUrl&url) {
    if(!url.isValid()) {
        qDebug("Invalid URL: %s", qUtf8Printable(url.toString()));
       return false;
    }

    return true;
}

bool QUrl::matches(const QUrl &url, QUrl::FormattingOptions options) const

如果对该 URL 和给定的url 均应用options 后两者相等，则返回true ；否则返回false 。

这相当于对两个 URL 分别调用adjusted(options)，然后比较所得的 URL，但速度更快。

QString QUrl::password(QUrl::ComponentFormattingOptions options = FullyDecoded) const

如果 URL 定义了密码，则返回该密码；否则返回空字符串。

options 参数控制用户名部分的格式化方式。所有取值均会产生明确无误的结果。当设置为QUrl::FullyDecoded 时，所有百分比编码序列都会被解码；否则，对于某些在QString 中无法以解码形式表示的控制序列，返回值可能包含部分百分比编码序列。

请注意，如果存在上述无法表示的序列，使用QUrl::FullyDecoded 可能会导致数据丢失。建议在结果将用于非 URL 上下文时使用该值，例如在QAuthenticator 中进行设置或协商登录时。

另请参阅 setPassword()。

QString QUrl::path(QUrl::ComponentFormattingOptions options = FullyDecoded) const

返回 URL 的路径。

qDebug()<<QUrl("file:file.txt").path();                   // "file.txt"
qDebug() << QUrl("/home/user/file.txt").path();             // "/home/user/file.txt"
qDebug() << QUrl("http://www.example.com/test/123").path(); // "/test/123"

options 参数控制路径组件的格式化方式。所有值都会产生明确无误的结果。当设置为QUrl::FullyDecoded 时，所有百分比编码的序列都会被解码；否则，对于某些在QString 中无法以解码形式表示的控制序列，返回值中可能会包含一些百分比编码的序列。

请注意，如果存在上述无法表示的序列，使用QUrl::FullyDecoded 可能会导致数据丢失。建议在结果将用于非URL上下文（例如发送至FTP服务器）时使用该值。

数据丢失的一个示例是：当存在非Unicode百分比编码序列且使用FullyDecoded （默认值）时：

qDebug() << QUrl("/foo%FFbar").path();

在此示例中，由于%FF 无法被转换，因此会出现一定程度的数据丢失。

当路径中包含子分隔符（例如+ ）时，也会发生数据丢失：

qDebug() << QUrl("/foo+bar%2B").path(); // "/foo+bar+"

其他解码示例：

constQUrl url("/tmp/Mambo %235%3F.mp3");
qDebug() << url.path(QUrl::FullyDecoded);  // "/tmp/Mambo #5?.mp3"
qDebug() << url.path(QUrl::PrettyDecoded); // "/tmp/Mambo #5?.mp3"
qDebug() << url.path(QUrl::FullyEncoded);  // "/tmp/Mambo%20%235%3F.mp3"

另请参阅 setPath()。

int QUrl::port(int defaultPort = -1) const

返回 URL 的端口号；如果未指定端口，则返回defaultPort 。

示例：

QTcpSocket sock;
sock.connectToHost(url.host(), url.port(80));

另请参阅 setPort()。

QString QUrl::query(QUrl::ComponentFormattingOptions options = PrettyDecoded) const

如果 URL 中包含查询字符串，则返回该查询字符串；否则返回空结果。要判断解析后的 URL 是否包含查询字符串，请使用 `hasQuery()`。

options 参数控制查询部分的格式化方式。所有值都会产生明确无误的结果。当设置为QUrl::FullyDecoded 时，所有百分比编码的字符串都会被解码；否则，对于某些在QString 中无法以解码形式表示的控制序列，返回值可能仍包含部分百分比编码的字符串。

请注意，不建议在查询中使用QUrl::FullyDecoded ，因为查询通常包含应保持百分比编码形式的数据，包括使用“%2B”序列来表示加号字符（'+'）。

另请参阅 setQuery() 和hasQuery()。

QUrl QUrl::resolved(const QUrl &relative) const

返回将此 URL 与relative 合并后的结果。此 URL 被用作将relative 转换为绝对 URL 的基准。

如果relative 不是相对 URL，则该函数将直接返回relative 。否则，将合并两个 URL 的路径，返回的新 URL 将保留基础 URL 的方案和权威部分，但采用合并后的路径，如下例所示：

QUrl baseUrl("http://qt.digia.com/Support/");
QUrl relativeUrl("../Product/Library/");
qDebug(qUtf8Printable(baseUrl.resolved(relativeUrl).toString()));
// 输出“http://qt.digia.com/Product/Library/”

使用“..”调用 resolved() 会返回一个QUrl ，其目录比原始目录高一级。同样，使用“../..”调用 resolved() 会从路径中移除两级。如果relative 为“/”，则路径变为“/”。

另请参阅 isRelative()。

QString QUrl::scheme() const

返回 URL 的方案。如果返回空字符串，则表示该方案未定义，此时该 URL 为相对 URL。

方案中只能包含 US-ASCII 字母或数字，这意味着它不能包含任何需要进行编码的字符。此外，方案始终以小写形式返回。

另请参阅 setScheme() 和isRelative()。

void QUrl::setAuthority(const QString &authority, QUrl::ParsingMode mode = TolerantMode)

将 URL 的权威部分设置为authority 。

URL 的授权部分由用户信息、主机名和端口组成。所有这些元素均为可选；因此，空的授权部分也是有效的。

用户信息与主机名之间用“@”分隔，主机名与端口之间用“:”分隔。如果用户信息为空，则必须省略“@”；但如果端口为空，则允许出现孤立的“:”。

以下示例展示了一个有效的权威部分字符串：

authority 数据根据mode 进行解析：在StrictMode 中，任何 '%' 字符后必须紧跟 exactly two hexadecimal characters，且某些字符（包括空格）不允许以未编码形式出现。 在TolerantMode （默认值）中，所有字符均可采用未解码形式，且容错解析器会自动修正未紧跟两个十六进制字符的孤立“%”字符。

此函数不允许将mode 设置为QUrl::DecodedMode 。要设置完全解码的数据，请分别调用setUserName()、setPassword()、setHost() 和setPort()。

另请参阅 authority()、setUserInfo()、setHost() 以及setPort() 函数。

void QUrl::setFragment(const QString &fragment, QUrl::ParsingMode mode = TolerantMode)

将 URL 的片段设置为fragment 。片段是 URL 的最后一部分，由“#”后跟一串字符表示。它通常在 HTTP 中用于指代页面上的某个链接或位置：

片段有时也被称为 URL 的“引用”。

传递 QString() 类型的参数（即空的QString ）将清除片段。传递QString （""）类型的参数（即空的但非空的QString ）将把片段设置为空字符串（如同原始 URL 仅包含一个“#”）。

fragment 数据的解析遵循mode 的规则：在StrictMode 中，任何 '%' 字符后必须紧跟两个十六进制字符，且某些字符（包括空格）不允许以未编码形式出现。在TolerantMode 中，所有字符均以未编码形式被接受，且容错解析器会修正那些未紧跟两个十六进制字符的孤立 '%' 字符。 在DecodedMode 中，'%' 代表其本身，且不允许出现编码字符。

QUrl::DecodedMode 当从非 URL 的数据源设置片段，或者使用fragment() 并配合QUrl::FullyDecoded 格式化选项获取片段时，应使用此参数。

另请参阅 fragment() 和hasFragment()。

void QUrl::setHost(const QString &host, QUrl::ParsingMode mode = DecodedMode)

将 URL 的主机设置为host 。主机是权威域的一部分。

host 数据的解析遵循mode 的规定：在StrictMode 中，任何 '%' 字符后必须紧跟恰好两个十六进制字符，且某些字符（包括空格）不允许以未编码形式出现。在TolerantMode 中，所有字符均以未编码形式被接受，且宽容解析器会自动修正那些未紧跟两个十六进制字符的孤立 '%' 字符。 在DecodedMode 中，'%' 代表其本身，且不允许出现编码字符。

请注意，在所有情况下，解析结果都必须是符合 STD 3 规则（经《国际化资源标识符》规范（RFC 3987）修改）的有效主机名。不允许使用无效主机名，否则会导致isValid() 返回 false。

另请参阅 host() 和setAuthority()。

[static] void QUrl::setIdnWhitelist(const QStringList &list)

将允许域名中包含非ASCII字符的顶级域名（TLD）白名单设置为list 。

请注意，若调用此函数，必须在启动任何可能访问idnWhitelist() 的线程之前进行。

Qt 提供了一个默认列表，其中包含已公开支持国际化域名 (IDN) 的互联网顶级域名，以及确保外观相似的字符（例如拉丁小写字母'a' 及其西里尔字母对应字符，在大多数字体中它们在外观上完全相同）之间不会发生混淆的规则。

随着注册商发布新规则，该列表会定期进行维护。

提供此函数是为了方便需要操作该列表以添加或删除顶级域名（TLD）的用户。除测试目的外，不建议更改其值，因为这可能会使用户面临安全风险。

另请参阅 idnWhitelist()。

void QUrl::setPassword(const QString &password, QUrl::ParsingMode mode = DecodedMode)

将该 URL 的密码设置为password 。password 是该 URL 授权部分中用户信息元素的一部分，具体说明请参见setUserInfo()。

password 数据的解析遵循mode 的规定：在StrictMode 中，任何 '%' 字符后必须紧跟恰好两个十六进制字符，且某些字符（包括空格）不允许以未编码形式出现。在TolerantMode 中，所有字符均以未编码形式被接受，且宽容的解析器会自动修正未紧跟两个十六进制字符的孤立 '%' 字符。 在DecodedMode 中，'%' 代表其本身，且不允许出现编码字符。

QUrl::DecodedMode 当从非 URL 的数据源设置密码时，应使用此选项，例如向用户显示的密码对话框，或者通过调用password() 并使用QUrl::FullyDecoded 格式化选项获取的密码。

另请参阅 password() 和setUserInfo()。

void QUrl::setPath(const QString &path, QUrl::ParsingMode mode = DecodedMode)

将 URL 的路径设置为path 。路径是指 URL 中位于域名之后、查询字符串之前的那个部分。

对于非层次结构的方案，路径将包含方案声明之后的所有内容，如下例所示：

path 数据根据mode 进行解析：在StrictMode 中，任何 '%' 字符后面必须紧跟两个十六进制字符，且某些字符（包括空格）不允许以未编码形式出现。在TolerantMode 中，所有字符均以未编码形式被接受，且容错解析器会修正那些后面未跟两个十六进制字符的孤立 '%' 字符。 在DecodedMode 中，'%' 代表其本身，且不允许出现编码字符。

QUrl::DecodedMode 当从非 URL 的数据源设置路径时，应使用此选项，例如显示给用户的对话框，或者通过调用path() 并使用QUrl::FullyDecoded 格式化选项获得的路径。

另请参阅 path()。

void QUrl::setPort(int port)

将 URL 的端口设置为port 。如setAuthority() 中所述，端口是 URL 授权部分的组成部分。

port 必须在 0 到 65535 之间（包含 0 和 65535）。将端口设置为 -1 表示端口未指定。

另请参阅 port()。

void QUrl::setQuery(const QString &query, QUrl::ParsingMode mode = TolerantMode)

将 URL 的查询字符串设置为query 。

如果需要传递一个不符合键值模式的查询字符串，或者该查询字符串对特殊字符的编码方案与QUrl 建议的不同，此函数会很有用。

将 QString() 的值（即空的QString ）传递给query 会完全清除查询字符串。然而，传递QString （""）的值会将查询字符串设置为空值，仿佛原始 URL 中只有一个孤立的“？”一样。

query 数据根据mode 进行解析：在StrictMode 中，任何 '%' 字符后必须紧跟恰好两个十六进制字符，且某些字符（包括空格）不允许以未编码形式出现。在TolerantMode 中，所有字符均以未编码形式被接受，且宽容的解析器会纠正未紧跟两个十六进制字符的孤立 '%' 字符。 在DecodedMode 中，'%' 代表其本身，且不允许出现编码字符。

查询字符串通常包含百分比编码序列，因此不建议使用DecodedMode 。需要注意的一个特殊序列是加号（'+'）的处理。QUrl 不会将空格转换为加号，尽管网页浏览器提交的 HTML 表单会进行此类转换。 为了在查询中表示真正的加号，通常使用“%2B”这一序列。在TolerantMode 或StrictMode 中，该函数将保留“%2B”序列不变。

另请参阅 query() 和hasQuery()。

void QUrl::setQuery(const QUrlQuery &query)

将 URL 的查询字符串设置为query 。

该函数从QUrlQuery 对象中重建查询字符串，并将其设置到此QUrl 对象上。由于QUrlQuery 包含已经过解析的数据，因此该函数不带解析参数。

另请参阅 query() 和hasQuery()。

void QUrl::setScheme(const QString &scheme)

将 URL 的方案设置为scheme 。由于方案只能包含 ASCII 字符，因此不会对输入进行任何转换或解码。此外，方案必须以 ASCII 字母开头。

方案描述了 URL 的类型（或协议）。它由 URL 开头的一个或多个 ASCII 字符表示。

方案严格符合RFC 3986 规范：scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )

以下示例展示了一个协议为“ftp”的 URL：

要设置方案，请使用以下调用：

QUrl url;
url.setScheme("ftp");

方案也可以为空，此时该 URL 将被解释为相对 URL。

另请参阅 scheme() 和isRelative()。

void QUrl::setUrl(const QString &url, QUrl::ParsingMode parsingMode = TolerantMode)

解析url 并将其值赋给该对象。QUrl 会自动对 URL 中不允许的所有字符进行百分比编码，并对表示非保留字符（字母、数字、连字符、下划线、点和波浪号）的百分比编码序列进行解码。所有其他字符均保持原样。

使用解析模式parsingMode 解析url 。在TolerantMode （默认模式）下，QUrl 将纠正某些错误，特别是百分号（'%'）后未跟随两个十六进制数字的情况，并且允许任何字符出现在任意位置。 在StrictMode 中，编码错误将不被容忍，且QUrl 还会检查是否存在某些以未编码形式出现的禁止字符。如果在StrictMode 中检测到错误，isValid() 将返回 false。在此上下文中不允许使用解析模式DecodedMode ，这将引发运行时警告。

另请参阅 url() 和toString()。

void QUrl::setUserInfo(const QString &userInfo, QUrl::ParsingMode mode = TolerantMode)

将 URL 的用户信息设置为userInfo 。如setAuthority() 中所述，用户信息是 URL 授权部分的可选组成部分。

用户信息由用户名和可选的密码组成，两者以“:”分隔。如果密码为空，则必须省略冒号。以下示例展示了一个有效的用户信息字符串：

userInfo 数据将根据mode 进行解析：在StrictMode 中，任何 '%' 字符后必须紧跟恰好两个十六进制字符，且某些字符（包括空格）不允许以未解码形式出现。 在TolerantMode （默认设置）下，所有字符均可以未解码形式接受，且容错解析器会自动修正未紧跟两个十六进制字符的孤立 '%' 字符。

此函数不允许将mode 设置为QUrl::DecodedMode 。要设置完全解码的数据，请分别调用setUserName() 和setPassword()。

另请参阅 userInfo()、setUserName()、setPassword() 和setAuthority()。

void QUrl::setUserName(const QString &userName, QUrl::ParsingMode mode = DecodedMode)

将 URL 的用户名设置为userName 。userName 是 URL 授权部分中用户信息元素的一部分，具体说明请参见setUserInfo()。

userName 数据的解析遵循mode 的规定：在StrictMode 中，任何 '%' 字符后必须紧跟恰好两个十六进制字符，且某些字符（包括空格）不允许以未解码形式出现。 在TolerantMode （默认）中，所有字符均可以未编码形式接受，且容错解析器会修正未紧跟两个十六进制字符的孤立 '%'。在DecodedMode 中，'%' 代表其本身，且不允许使用编码字符。

QUrl::DecodedMode 当从非 URL 数据源设置用户名时，应使用此选项，例如显示给用户的密码对话框，或者通过调用userName() 并使用QUrl::FullyDecoded 格式化选项获取用户名的情况。

另请参阅 userName() 和setUserInfo()。

[noexcept] void QUrl::swap(QUrl &other)

将此网址替换为other 。此操作非常快，且绝不会失败。

[static, since 6.3] QByteArray QUrl::toAce(const QString &domain, QUrl::AceProcessingOptions options = {})

返回给定域名domain 的 ASCII 兼容编码。可通过向options 传递标志来自定义输出。该函数的返回结果被视为与domain 等效。

ASCII 兼容编码（ACE）由 RFC 3490、RFC 3491 和 RFC 3492 定义，并由 Unicode 技术标准第 46 号进行了更新。 它是“应用程序中域名国际化”（IDNA）规范的一部分，该规范允许使用非 US-ASCII 字符书写域名（例如"example.com" ）。

如果domain 不是有效的主机名，则该函数返回空的QByteArray 。请特别注意，IPv6 字面量不是有效的域名。

该函数于 Qt 6.3 中引入。

CFURLRef QUrl::toCFURL() const

根据QUrl 创建一个CFURL。

调用方拥有该 CFURL，并负责将其释放。

QString QUrl::toDisplayString(QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded)) const

返回 URL 的可读字符串表示形式。可以通过向 `options` 传递标志来自定义输出。选项 `RemovePassword ` 始终处于启用状态，因为密码绝不应显示给用户。

使用默认选项时，生成的QString 结果可随后传递回QUrl ，但初始存在的任何密码都将丢失。

另请参阅 FormattingOptions 、toEncoded() 和toString()。

QByteArray QUrl::toEncoded(QUrl::FormattingOptions options = FullyEncoded) const

如果 URL 有效，则返回其编码后的表示形式；否则返回一个空的 `QByteArray `。可以通过向 `options` 传递标志来自定义输出。

用户信息、路径和片段均被转换为 UTF-8，随后所有非 ASCII 字符均进行百分比编码。主机名使用 Punycode 进行编码。

QString QUrl::toLocalFile() const

返回此 URL 以本地文件路径格式呈现的路径。即使原始 URL 包含反斜杠，返回的路径也将使用正斜杠。

如果该 URL 包含非空的主机名，则会在返回值中按 SMB 网络中的格式进行编码（例如，“//servername/path/to/file.txt”）。

qDebug()<<QUrl("file:file.txt").toLocalFile();            // "file.txt"
qDebug() << QUrl("file:/home/user/file.txt").toLocalFile(); // "/home/user/file.txt"
qDebug() << QUrl("file.txt").toLocalFile();                 // ""; wasn't a local file as it had no scheme

注意：如果该 URL 的路径部分包含非 UTF-8 二进制序列（例如 %80），则该函数的行为未定义。

另请参阅 fromLocalFile() 和isLocalFile()。

NSURL *QUrl::toNSURL() const

根据QUrl 创建一个NSURL。

该 NSURL 将被自动释放。

[static] QByteArray QUrl::toPercentEncoding(const QString &input, const QByteArray &exclude = QByteArray(), const QByteArray &include = QByteArray())

返回input 的编码副本。首先将input 转换为UTF-8，并将所有不在未保留字符组中的ASCII字符进行百分比编码。若要防止字符被百分比编码，请将其传递给exclude ；若要强制对字符进行百分比编码，请将其传递给include 。

“未保留字符”的定义如下：ALPHA / DIGIT / "-" / "." / "_" / "~"

QByteArray ba=QUrl::toPercentEncoding("{a fishy string?}", "{}", "s");
qDebug(ba.constData());
// 输出“{a fi%73hy %73tring%3F}”

QString QUrl::toString(QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded)) const

返回 URL 的字符串表示形式。可以通过向 `options` 传递标志来自定义输出。本函数不允许使用 `QUrl::FullyDecoded ` 选项，因为这会生成模棱两可的数据。

默认格式化选项为PrettyDecoded 。

另请参阅 FormattingOptions 、url() 和setUrl()。

[static] QStringList QUrl::toStringList(const QList<QUrl> &urls, QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded))

使用toString （options ）将一个urls 列表转换为一个QString 对象列表。

QString QUrl::url(QUrl::FormattingOptions options = FormattingOptions(PrettyDecoded)) const

返回 URL 的字符串表示形式。可以通过向 `options` 传递标志来自定义输出。本函数不允许使用 `QUrl::FullyDecoded ` 选项，因为这会生成模棱两可的数据。

生成的QString 结果稍后可传回给QUrl 。

toString （带选项）的同义词。

另请参阅 setUrl()、FormattingOptions 、toEncoded() 以及toString()。

QString QUrl::userInfo(QUrl::ComponentFormattingOptions options = PrettyDecoded) const

返回该 URL 的用户信息；如果用户信息未定义，则返回空字符串。

该函数返回一个无歧义的值，其中可能包含仍处于百分比编码状态的字符，以及一些在QString 中无法以解码形式表示的控制序列。

参数options 控制用户信息组件的格式。本函数不允许使用QUrl::FullyDecoded 值。若需获取完全解码的数据，请分别调用userName()和password()。

另请参阅 setUserInfo()、userName()、password() 和authority()。

QString QUrl::userName(QUrl::ComponentFormattingOptions options = FullyDecoded) const

如果 URL 中定义了用户名，则返回该用户名；否则返回空字符串。

options 参数控制用户名部分的格式化方式。所有取值均会产生无歧义的结果。当设置为QUrl::FullyDecoded 时，所有百分比编码序列都会被解码；否则，对于某些在QString 中无法以解码形式表示的控制序列，返回值可能包含部分百分比编码序列。

请注意，如果存在上述无法表示的序列，使用 `QUrl::FullyDecoded ` 可能会导致数据丢失。建议在结果将用于非 URL 场景时使用该值，例如在 `QAuthenticator ` 中进行设置或协商登录。

另请参阅 setUserName() 和userInfo()。

[noexcept] QUrl &QUrl::operator=(QUrl &&other)

将other 通过move赋值给此QUrl 实例。

QUrl &QUrl::operator=(const QString &url)

将指定的url 分配给此对象。

当定义了QT_NO_URL_CAST_FROM_STRING 宏时，此运算符不可用。

[noexcept] QUrl &QUrl::operator=(const QUrl &url)

将指定的url 分配给此对象。