QUrl类

成员函数文档

QUrl::QUrl()

构造一个空的 QUrl 对象。

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

通过解析 url 来构造一个 URL。注意此构造函数期望一个合适的 URL 或 URL-Reference，并且不会尝试猜测意图。例如，以下声明

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)

移动构造一个QUrl实例，使其指向other所指向的同一对象。

[noexcept] QUrl::~QUrl()

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

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

返回URL的调整版本。通过传递带有options的标志来自定义输出。

QUrl::ComponentFormattingOption的编码选项对于此方法没有太多意义，QUrl::PreferLocalFile也是如此。

此操作始终等同于QUrl(url.toString(options))。

另请参阅格式化选项、toEncoded()和toString()。

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

如果定义了URL的权限，则返回URL的权限；否则返回空字符串。

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

options参数控制如何格式化用户信息组件。此函数不允许使用QUrl::FullyDecoded的值。如果需要获取完全解码的数据，请分别调用userName()、password()、host()和port()。

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

void QUrl::clear()

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

另请参阅isEmpty()。

QString QUrl::errorString() const

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

此函数返回的错误消息具有技术性质，可能不会被最终用户理解。它主要有助于开发者理解为什么QUrl不接受某些输入。

另请参阅QUrl::ParsingMode。

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

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

注意，如果这个QUrl对象指定的路径以斜杠结尾，则认为文件名为空。

如果路径不包含任何斜杠，它将完全作为文件名返回。

示例

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。

[静态，自6.3以来] QString QUrl::fromAce(const QByteArray &domain, QUrl::AceProcessingOptions options = {})

返回给定经过ASCII兼容编码(ACE)编码的域名domain的Unicode形式。可以通过传递options中的标志来自定义输出。此函数的返回值被认为是与domain等效。

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

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

此函数是在Qt 6.3中引入的。

[静态] QUrl QUrl::fromCFURL(CFURLRef url)

构造一个包含CFURL url副本的QUrl。

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

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

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

另请参阅：toEncoded() 和 setUrl。

[静态] 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/");
    // wrong: prints QUrl("file:file.txt"), as url already has a scheme
    qDebug() << baseUrl.resolved(url);

要解析此类 URL，必须先将方案移除。

    // correct: prints 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/");
    // prints QUrl("file:///home/user/file.txt")
    qDebug() << baseUrl.resolved(url);

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

[静态] QUrl QUrl::fromNSURL(const NSURL *url)

创建包含 NSURL url 副本的 QUrl。

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

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

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

此函数将代表URL的字符串列表转换为URL列表，使用QUrl(str, mode)。请注意，这意味着所有字符串都必须是URL，而不是例如本地路径。

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

如果可以从用户提供的userInput字符串中推断出URL，则返回一个有效的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包含一个片段（即，如果在它上面看到了#），则返回true。

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

bool QUrl::hasQuery() const

如果此URL包含查询（即，如果在它上面看到了?），则返回true。

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

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

如果URL定义了主机，则返回URL的主机地址；否则返回空字符串。

参数options控制主机名的格式。选项QUrl::EncodeUnicode将导致此函数以ASCII兼容编码（ACE）形式返回主机名，适用于不使用8位编码的通道或需要传统主机名（如DNS请求或HTTP请求头）的通道。如果没有设置该标志，则此函数将根据允许顶级域名列表（请参阅idnWhitelist（））以Unicode形式返回国际域名名称（IDN）。

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

另请参阅setHost（），idnWhitelist（），setIdnWhitelist（）和authority（）。

[静态] QStringList QUrl::idnWhitelist()

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

有关此列表的理由，请参阅setIdnWhitelist（）。

另请参阅setIdnWhitelist（）和AceProcessingOption。

bool QUrl::isEmpty() const

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

另请参阅clear（）。

bool QUrl::isLocalFile() const

如果此URL指向本地文件路径，则返回true。如果方案是"文件"，则URL是本地文件路径。

请注意，此函数认为具有主机名的URL是本地文件路径，即使最终的文件路径不能用QFile::open（）。

另请参阅fromLocalFile（）和toLocalFile（）。

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

如果此URL是childUrl的父URL，则返回true。如果两个URL共享相同的方案和授权，并且此URL的路径是childUrl路径的父路径，则childUrl是此URL的子路径。

bool QUrl::isRelative() const

如果URL是相对的，则返回true；否则返回false。如果URL的方案未定义，则它是相对引用；因此，此函数等价于调用scheme（）isEmpty（）。

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

另请参阅相对URL与相对路径。

bool QUrl::isValid() const

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

URL经过符合性测试。URL的每一部分都必须符合URI标准的编码规则，才能报告为有效。

bool checkUrl(const QUrl &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

如果应用options后，此URL与给定url相等，则返回true；否则返回false。

这相当于在两个URL上调用adjusted(options)并比较结果，但速度更快。

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+"

其他解码示例

    const QUrl 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的端口号；否则返回默认端口号。

示例

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(baseUrl.resolved(relativeUrl).toString());
// prints "http://qt.digia.com/Product/Library/"

使用 ".." 调用 resolved() 将返回一个其目录比原始目录高一级的 QUrl。类似地，调用 resolved() 使用 "../.." 将从路径中移除两个级别。如果 relative 是 "/", 路径变为 "/"。

另请参阅isRelative()。

QString QUrl::scheme() const

返回 URL 的协议。如果返回空字符串，表示协议未定义，则该 URL 是相对的。

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

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

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

将 URL 的权限设置为 authority。

URL 的权限是用户信息、主机名和端口的组合。所有这些元素都是可选的；因此，空权限是有效的。

用户信息和主机名通过 '@' 分隔，主机名和端口通过 ':' 分隔。如果用户信息为空，'@' 必须省略；如果端口为空，那么允许存在多余的 ':'。

以下示例展示了一个有效的权限字符串

根据 mode 解释 authority 数据：在 StrictMode 中，任何 '%' 字符之后必须紧跟恰好两个十六进制字符，并且在解码形式中不允许某些字符（包括空格）存在。在 TolerantMode（默认模式）中，接受所有字符的未解码形式，并允许将随机出现的未跟有两个十六进制字符的 '%' 进行纠正。

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

另见authority()、setUserInfo()、setHost() 和 setPort。

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

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

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

传递一个 QString()（一个空的QString）参数将取消片段。传递一个QString("")（一个非空的QString）参数将片段设置为空字符串（就像原始 URL 中只有一个 "#" 一样）。

片段 数据的解析将根据 模式 进行：在 StrictMode 中，任何 "%" 字符都必须由恰好两个十六进制字符后跟，且某些字符（包括空格）在未解码形式中是不允许的。在 TolerantMode 中，所有字符都以未解码形式接受，并且容错解析器会纠正不跟随两个十六进制字符的孤立 "%"。在 DecodedMode 中，"%" 代表自身，并且不可能有编码的字符。

当从非 URL 数据源设置片段，或通过调用fragment() 并使用QUrl::FullyDecoded 格式化选项获取片段时，应该使用 QUrl::DecodedMode。

另见fragment() 和 hasFragment。

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

将 URL 的主机设置为 主机。主机是授权的一部分。

主机 的数据将根据 模式 进行解析：在 StrictMode 中，任何 "%" 字符都必须由恰好两个十六进制字符后跟，且某些字符（包括空格）在未解码形式中是不允许的。在 TolerantMode 中，所有字符都以未解码形式接受，并且容错解析器会纠正不跟随两个十六进制字符的孤立 "%"。在 DecodedMode 中，"%" 代表自身，并且不可能有编码的字符。

请注意，在所有情况下，解析的结果都必须是 STD 3 规则下有效的主机名，如国际资源标识符规范（RFC 3987）所修改的。不允许无效的主机名，这会导致isValid() 转为 false。

另见host() 和 setAuthority。

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

将允许在域名中包含非ASCII字符的一级域(TLDs)的白名单设置为list的值。

请注意，如果调用此函数，需要在开始任何可能访问idnWhitelist()的线程之前调用它。

Qt附带了一个默认列表，其中包含已经公布支持国际域名(INT)的互联网一级域，并确保类似外观的字符（如拉丁字母小写的'a'和西里尔等价字符，在大多数字体中都是视觉上相同的）之间不会发生欺骗。

该列表定期维护，因为注册商发布新规则。

此函数提供供需要操作列表，以便添加或删除TLD的人使用。不推荐出于测试以外的目的更改其值，因为这可能会使用户面临安全风险。

另请参阅 idnWhitelist。

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

设置URL的密码为password。密码是URL权限中的用户信息元素的一部分，如setUserInfo()中所述。

password数据根据mode进行解析：在StrictMode中，每个'%'字符后面必须紧跟两个十六进制字符，有些字符（包括空格）以未解码形式不允许。在TolerantMode中，接受所有字符以未解码形式，宽容解析器将纠正未紧跟两个十六进制字符的孤'%'. 在DecodedMode中，'%'代表自己，并且不允许编码字符。

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

另请参阅 password()和setUserInfo。

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

将URL的路径设置为path。路径是Authority之后、查询字符串之前的URL的一部分。

对于非分层方案，路径将是方案声明之后的所有内容，如下例所示

path数据根据mode进行解析：在StrictMode中，每个'%'字符后面必须紧跟两个十六进制字符，有些字符（包括空格）以未解码形式不允许。在TolerantMode中，接受所有字符以未解码形式，宽容解析器将纠正未紧跟两个十六进制字符的孤'%'. 在DecodedMode中，'%'代表自己，并且不允许编码字符。

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

另请参阅path。

void QUrl::setPort(int port)

将URL的端口号设置为port。端口号是URL权限的一部分，如setAuthority()中所描述。

port必须在0到65535之间，包括这两个数。将端口号设置为-1表示端口号未指定。

另请参阅port().

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

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

如果您需要传递不适合键值模式或使用与QUrl建议不同的方案对特殊字符进行编码的查询字符串，则此函数很有用。

将QString()（一个空的QString）传递给query将完全取消查询。但是，传递QString("")将使查询成为一个空值，就像原始URL有一个单独的"?"一样。

根据mode，按query数据解释：在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 / "+" / "-" / "." )

以下示例显示了一个 scheme 为 "ftp" 的 URL

要设置 scheme，使用以下调用

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

如果 scheme 为空，则 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。用户信息是 URL 授权的组成部分，如 setAuthority() 所述。

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

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)

交换URL other 与此URL。此操作非常快且不会失败。

[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，但任何最初存在的密码将会丢失。

另请参阅格式化选项、toEncoded()和toString()。

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

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

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

QString QUrl::toLocalFile() const

返回此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是自动释放的。

[静态] 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());
// prints "{a fi%73hy %73tring%3F}"

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

返回URL的字符串表示形式。可以通过传递带有options的标志来自定义输出。此函数不允许QUrl::FullyDecoded选项，因为这会产生模糊的数据。

默认的格式化选项是PrettyDecoded。

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

[静态] 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(options)的同义词。

另请参阅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的用户名，则返回URL的用户名；否则返回空字符串。

参数options控制如何格式化用户名组件。所有值都产生一个明确的输出。在QUrl::FullyDecoded下，所有百分编码序列都将解码；否则，返回值可能包含某些在QString中无法表示的某些控制序列的百分编码序列。

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

另请参阅setUserName 和 userInfo。

bool QUrl::operator!=(const QUrl &url) const

如果此URL和给定的 url 不相等，则返回 true；否则返回 false。

另请参阅matches。

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

将指定的 url 赋值给此对象。

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

将指定的 url 赋值给此对象。

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

将 other 移动赋值到此 QUrl 实例。

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

如果此URL和给定的 url 相等，则返回 true；否则返回 false。

另请参阅matches。