PySide6.QtCore.QUrl

class QUrl

QUrl 类提供了一个方便的接口来处理URL。更多…

概要

方法

静态函数

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

它可以解析和构建编码和未编码形式的URL。QUrl还支持国际化域名（IDNs）。

使用QUrl最常见的方式是通过构造函数初始化，传递一个包含完整URL的QString。QUrl对象也可以从包含完整URL的QByteArray通过fromEncoded()创建，或者通过fromUserInput()从非完整URL启发式创建。URL表示可以从QUrl通过toString()或toEncoded()获取。

URL可以以两种形式表示：编码或未编码。未编码的表示适合展示给用户，但编码的表示通常是您发送到Web服务器的内容。例如，未编码的URL“http://bühler.example.com/List of applicants.xml”将作为“http://xn–bhler-kva.example.com/List%20of%20applicants.xml”发送到服务器。

URL 也可以通过调用 setScheme()、setUserName()、setPassword()、setHost()、setPort()、setPath()、setQuery() 和 setFragment() 逐部分构建。还有一些便捷函数可用：setAuthority() 设置用户名、密码、主机和端口。setUserInfo() 一次性设置用户名和密码。

调用isValid()来检查URL是否有效。这可以在构建URL的任何时候进行。如果isValid()返回false，你应该在继续之前clear() URL，或者通过使用setUrl()解析一个新的URL重新开始。

通过使用QUrlQuery类及其方法setQueryItems()、addQueryItem()和removeQueryItem()，构建查询特别方便。使用setQueryDelimiters()来自定义用于生成查询字符串的分隔符。

为了方便生成编码的URL字符串或查询字符串，有两个静态函数叫做fromPercentEncoding()和toPercentEncoding()，它们处理QString对象的百分比编码和解码。

fromLocalFile() 通过解析本地文件路径构造一个 QUrl。toLocalFile() 将 URL 转换为本地文件路径。

URL 的人类可读表示形式是通过 toString() 获取的。这种表示形式适合以未编码的形式向用户显示 URL。然而，由 toEncoded() 返回的编码形式则用于内部使用，例如传递给 Web 服务器、邮件客户端等。这两种形式在技术上都是正确的，并且明确地表示相同的 URL——事实上，将其中任何一种形式传递给 QUrl 的构造函数或 setUrl() 都会生成相同的 QUrl 对象。

QUrl 符合 RFC 3986（统一资源标识符：通用语法）中的 URI 规范，并包括来自 RFC 1738（统一资源定位符）的方案扩展。QUrl 中的大小写折叠规则符合 RFC 3491（Nameprep：国际化域名（IDN）的字符串准备配置文件）。它还与来自 freedesktop.org 的 文件 URI 规范 兼容，前提是区域设置使用 UTF-8 编码文件名（IDN 要求）。

相对URL与相对路径

调用 isRelative() 将返回 URL 是否为相对路径。相对 URL 没有 scheme。例如：

print(QUrl("main.qml").isRelative() # true: no scheme)
print(QUrl("qml/main.qml").isRelative() # true: no scheme)
print(QUrl("file:main.qml").isRelative() # false: has "file" scheme)
print(QUrl("file:qml/main.qml").isRelative() # false: has "file" scheme)

请注意，URL 可以是绝对的，同时包含相对路径，反之亦然：

# Absolute URL, relative path
url = QUrl("file:file.txt")
print(url.isRelative() # false: has "file" scheme)
print(QDir.isAbsolutePath(url.path()) # false: relative path)
# Relative URL, absolute path
url = QUrl("/home/user/file.txt")
print(url.isRelative() # true: has no scheme)
print(QDir.isAbsolutePath(url.path()) # true: absolute path)

相对URL可以通过将其作为参数传递给resolved()来解析，该函数返回一个绝对URL。isParentOf()用于确定一个URL是否是另一个URL的父级。

错误检查

QUrl 能够在解析URL时或在通过单独的设置方法（如 setScheme()、setHost() 或 setPath()）设置URL的组件时检测到许多错误。如果解析或设置函数成功，任何先前记录的错误条件将被丢弃。

默认情况下，QUrl 的设置方法在 TolerantMode 模式下操作，这意味着它们接受一些常见的错误和数据的错误表示。另一种解析方法是 StrictMode ，它应用了进一步的检查。有关解析模式差异的描述，请参见 ParsingMode 。

QUrl 只检查是否符合URL规范。它不会尝试验证高级协议URL是否符合其他处理程序预期的格式。例如，以下URI都被QUrl视为有效，即使它们在使用时没有意义：

当解析器遇到错误时，它会通过使isValid()返回false和toString() / toEncoded()返回空字符串来发出事件信号。如果需要向用户显示URL解析失败的原因，可以通过调用errorString()从QUrl获取错误条件。请注意，此消息技术性很强，可能对最终用户没有意义。

QUrl 只能记录一个错误条件。如果发现多个错误，则未定义报告哪个错误。

字符转换

遵循这些规则以避免在处理URL和字符串时出现错误的字符转换：

  • 当创建一个QString来包含来自QByteArray或char*的URL时，始终使用fromUtf8()。

class ParsingMode

解析模式控制着QUrl解析字符串的方式。

常量

描述

QUrl.TolerantMode

QUrl 将尝试纠正URL中的一些常见错误。此模式对于解析来自未知是否严格符合标准的来源的URL非常有用。

QUrl.StrictMode

仅接受有效的URL。此模式适用于一般的URL验证。

QUrl.DecodedMode

QUrl 将以完全解码的形式解释URL组件，其中百分号代表它们自己，而不是百分号编码序列的开始。此模式仅对设置URL组件的设置器有效；在QUrl构造函数、fromEncoded()或setUrl()中不允许使用此模式。有关此模式的更多信息，请参阅FullyDecoded的文档。

在TolerantMode中，解析器具有以下行为：

  • 空格和“%20”：未编码的空格字符将被接受，并将被视为等同于“%20”。

  • 单个“%”字符：任何未紧跟两个十六进制字符的百分号“%”（例如，“13% coverage.html”）将被替换为“%25”。请注意，一个单独的“%”字符将触发所有百分号字符的修正模式。

  • 保留和非保留字符：编码后的URL应仅包含少量字符作为字面量；所有其他字符应进行百分号编码。在TolerantMode中，如果在URL中找到这些字符，它们将被接受：空格 / 双引号 / “<” / “>” / “” / “^” / “`” / “{” / “|” / “}” 这些相同的字符可以通过将DecodeReserved传递给toString()或toEncoded()再次解码。在单个组件的getter中，这些字符通常以解码形式返回。

在严格模式下，如果发现解析错误，isValid() 将返回 false，并且 errorString() 将返回描述错误的消息。如果检测到多个错误，则未定义报告哪个错误。

请注意，TolerantMode 通常不足以解析用户输入，因为用户输入通常包含比解析器能处理的更多错误和预期。当处理直接来自用户的数据时——与来自数据传输源（如其他程序）的数据相对——建议使用 fromUserInput() 。

另请参阅

fromUserInput() setUrl() toString() toEncoded() FormattingOptions

class UrlFormattingOption

（继承自 enum.IntFlag）格式化选项定义了当URL以文本形式写出时如何格式化。

常量

描述

QUrl.None

URL的格式保持不变。

QUrl.RemoveScheme

从URL中移除方案。

QUrl.RemovePassword

URL中的任何密码都将被移除。

QUrl.RemoveUserInfo

URL中的任何用户信息都被移除。

QUrl.RemovePort

从URL中移除任何指定的端口。

QUrl.RemoveAuthority

QUrl.RemovePath

URL的路径被移除，只留下方案、主机地址和端口（如果存在）。

QUrl.RemoveQuery

URL的查询部分（在‘?’字符之后）被移除。

QUrl.RemoveFragment

QUrl.RemoveFilename

文件名（即路径中最后一个‘/’之后的所有内容）被移除。除非设置了StripTrailingSlash，否则保留末尾的‘/’。仅在未设置RemovePath时有效。

QUrl.PreferLocalFile

如果URL根据isLocalFile()是本地文件并且不包含查询或片段，则返回本地文件路径。

QUrl.StripTrailingSlash

如果路径末尾有斜杠，则将其移除。

QUrl.NormalizePathSegments

修改路径以移除多余的目录分隔符，并尽可能解析“.”和“..”。对于非本地路径，相邻的斜杠将被保留。

请注意，QUrl 所遵循的 Nameprep 中的大小写折叠规则要求主机名始终转换为小写，无论使用的 Qt::FormattingOptions 是什么。

ComponentFormattingOptions 中的选项也是可能的。

另请参阅

ComponentFormattingOptions

class ComponentFormattingOption

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

(继承自 enum.IntFlag) 组件格式化选项定义了当URL组件以文本形式写出时如何格式化。它们可以与 FormattingOptions 中的选项结合使用，当在 toString() 和 toEncoded() 中使用时。

常量

描述

QUrl.PrettyDecoded

组件以“漂亮的形式”返回，大多数百分号编码的字符被解码。PrettyDecoded 的确切行为因组件而异，也可能因 Qt 版本的不同而有所变化。这是默认设置。

QUrl.EncodeSpaces

将空格字符保留为其编码形式（“%20”）。

QUrl.EncodeUnicode

保留非US-ASCII字符以其UTF-8百分比编码形式编码（例如，“%C3%A9”表示U+00E9码点，即带尖音的小写拉丁字母E）。

QUrl.EncodeDelimiters

保留某些分隔符的编码形式，就像在完整URL以文本形式表示时出现在URL中的那样。此选项更改的分隔符因组件而异。此标志在toString()或toEncoded()中没有效果。

QUrl.EncodeReserved

保留URL规范中不允许的US-ASCII字符的编码形式。这是toString()和toEncoded()的默认行为。

QUrl.DecodeReserved

解码URL规范中不允许出现在URL中的US-ASCII字符。这是各个组件获取器的默认设置。

QUrl.FullyEncoded

将所有字符保留在其正确编码的形式中，就像该组件作为URL的一部分出现时一样。当与toString()一起使用时，这会生成一个完全符合标准的URL，以QString形式，完全等同于toEncoded()的结果

QUrl.FullyDecoded

尝试尽可能解码。对于URL的各个组件，这将解码每个百分号编码序列，包括控制字符（U+0000到U+001F）和以百分号编码形式找到的UTF-8序列。使用此模式可能会导致数据丢失，请参阅以下内容以获取更多信息。

EncodeReserved 和 DecodeReserved 的值不应在一次调用中同时使用。如果发生这种情况，行为是未定义的。它们作为单独的值提供，因为“漂亮模式”在保留字符方面的行为在某些组件上，特别是在完整 URL 上是不同的。

完全解码

FullyDecoded 模式类似于 Qt 4.x 中返回 QString 的函数的行为，即每个字符都代表其自身，从不具有任何特殊含义。即使对于百分号（‘%’），也应解释为字面百分号，而不是百分号编码序列的开始。在所有其他解码模式中，相同的实际字符由序列“%25”表示。

每当将使用QUrl::FullyDecoded获得的数据重新应用到QUrl时，必须注意使用DecodedMode参数来设置（如setPath()和setUserName()）。如果不这样做，可能会导致百分号（‘%’）被重新解释为百分号编码序列的开始。

当URL的部分内容用于非URL上下文时，此模式非常有用。例如，要在FTP客户端应用程序中提取用户名、密码或文件路径，应使用FullyDecoded模式。

此模式应谨慎使用，因为有两种情况无法在返回的QString中可靠表示。它们是：

  • 非UTF-8序列： URL可能包含不形成有效UTF-8序列的百分号编码字符序列。由于URL需要使用UTF-8解码，任何解码失败将导致QString包含一个或多个替换字符，这些字符位于序列存在的位置。

  • 编码的分隔符： URL 也允许区分字面形式的分隔符和其百分号编码形式的等价物。这最常见于查询部分，但在 URL 的大部分部分都是允许的。

以下示例说明了问题：

original = QUrl("http://example.com/?q=a%2B%3Db%26c")
copy = QUrl(original)
copy.setQuery(copy.query(QUrl.FullyDecoded), QUrl.DecodedMode)
print(original.toString() # prints: http://example.com/?q=a%2B%3Db%26c)
print(copy.toString() # prints: http://example.com/?q=a+=bc)

如果这两个URL通过HTTP GET使用，Web服务器的解释可能会有所不同。在第一种情况下，它会解释为一个参数，键为“q”，值为“a+=b&c”。在第二种情况下，它可能会解释为两个参数，一个键为“q”，值为“a =b”，第二个键为“c”，没有值。

另请参阅

FormattingOptions

class UserInputResolutionOption

(继承自 enum.Flag) 用户输入解析选项定义了 fromUserInput() 应该如何解释可能是相对路径或HTTP URL短格式的字符串。例如，file.pl 可以是一个本地文件，也可以是URL http://file.pl。

常量

描述

QUrl.DefaultResolution

默认的解析机制是检查本地文件是否存在，在提供给fromUserInput的工作目录中，并且仅在该情况下返回本地路径。否则假定为URL。

QUrl.AssumeLocalFile

此选项使 fromUserInput() 始终返回本地路径，除非输入包含方案，例如 http://file.pl。这对于诸如文本编辑器之类的应用程序非常有用，这些应用程序能够在文件不存在时创建文件。

另请参阅

fromUserInput()

class AceProcessingOption

(继承自 enum.Flag) ACE 处理选项控制 URL 如何转换为 ASCII 兼容编码以及从 ASCII 兼容编码转换回 URL。

常量

描述

QUrl.IgnoreIDNWhitelist

在将URL转换为Unicode时忽略IDN白名单。

QUrl.AceTransitionalProcessing

使用UTS #46中描述的过渡处理。这允许更好地与IDNA 2003规范兼容。

默认情况下，使用非过渡处理，并且仅在顶级域名列在IDN白名单中的URL内允许非ASCII字符。

在版本6.3中添加。

__init__()

构造一个空的QUrl对象。

__init__(copy)
Parameters:

复制 – QUrl

构造other的副本。

__init__(url[, mode=QUrl.ParsingMode.TolerantMode])
Parameters:

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

通过解析url来构造一个URL。请注意，此构造函数期望一个正确的URL或URL引用，并且不会尝试猜测意图。例如，以下声明：

url = QUrl("example.com")

将构造一个有效的URL，但它可能不是人们所期望的，因为输入的scheme()部分缺失。对于像上面这样的字符串，应用程序可能希望使用fromUserInput()。对于此构造函数或setUrl()，以下内容可能是预期的：

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

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

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

示例：

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

要从编码字符串构造URL，你也可以使用fromEncoded()：

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

这两个函数是等价的，并且在Qt 5中，这两个函数都接受编码数据。通常，选择QUrl构造函数或setUrl()与fromEncoded()的选择将取决于源数据：构造函数和setUrl()接受一个QString，而fromEncoded接受一个QByteArray。

__reduce__()
Return type:

字符串

__repr__()
Return type:

字符串

adjusted(options)
Parameters:

options – ComponentFormattingOption 的组合

Return type:

QUrl

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

来自ComponentFormattingOption的编码选项对这个方法没有太大意义，PreferLocalFile也是如此。

这总是等同于 QUrl (url. toString (options))。

另请参阅

FormattingOptions toEncoded() toString()

authority([options=QUrl.ComponentFormattingOption.PrettyDecoded])
Parameters:

options – ComponentFormattingOption 的组合

Return type:

字符串

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

此函数返回一个明确的值，该值可能包含仍为百分号编码的字符，以及一些在QString中无法以解码形式表示的控制序列。

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

clear()

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

另请参阅

isEmpty()

errorString()
Return type:

字符串

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

此函数返回的错误消息本质上是技术性的，最终用户可能无法理解。它主要对试图理解为什么QUrl不接受某些输入的开发人员有用。

另请参阅

ParsingMode

fileName([options=QUrl.ComponentFormattingOption.FullyDecoded])
Parameters:

options – ComponentFormattingOption 的组合

Return type:

字符串

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

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

请注意，如果这个QUrl对象被赋予了一个以斜杠结尾的路径，文件名将被视为空。

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

示例：

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

options 参数控制如何格式化文件名组件。所有值都会产生明确的结果。使用 FullyDecoded 时，所有百分比编码的序列都会被解码；否则，返回的值可能包含一些百分比编码的序列，用于某些在 QString 中无法以解码形式表示的控制序列。

另请参阅

path()

fragment([options=QUrl.ComponentFormattingOption.PrettyDecoded])
Parameters:

options – ComponentFormattingOption 的组合

Return type:

字符串

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

options 参数控制如何格式化片段组件。所有值都会产生明确的结果。使用 FullyDecoded 时，所有百分比编码的序列都会被解码；否则，返回值可能包含一些百分比编码的序列，用于某些在 QString 中无法以解码形式表示的控制序列。

请注意，如果存在那些不可表示的序列，FullyDecoded可能会导致数据丢失。建议在结果将用于非URL上下文时使用该值。

static fromAce(domain[, options={}])
Parameters:
Return type:

字符串

返回给定域名 domain 的 Unicode 形式，该域名以 ASCII 兼容编码 (ACE) 编码。可以通过传递带有 options 的标志来自定义输出。此函数的结果被认为等同于 domain。

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

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

static fromEncoded(input[, mode=QUrl.ParsingMode.TolerantMode])
Parameters:
Return type:

QUrl

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

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

注意

在Qt 6.7之前的版本中，此函数接受的是QByteArray，而不是QByteArrayView。如果您遇到编译错误，那是因为您的代码传递的对象可以隐式转换为QByteArray，但不能转换为QByteArrayView。将相应的参数包装在QByteArray{~~~}中，以使转换显式。这与旧版本的Qt向后兼容。

另请参阅

toEncoded() setUrl()

static fromLocalFile(localfile)
Parameters:

localfile – str

Return type:

QUrl

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

返回 localFile 的 QUrl 表示，解释为本地文件。此函数接受以斜杠分隔的路径以及此平台的本机分隔符。

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

空的 localFile 会导致一个空的 URL（自 Qt 5.4 起）。

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

在上面的代码片段的第一行中，从本地的相对路径构造了一个文件URL。只有存在一个基础URL来解析它时，具有相对路径的文件URL才有意义。例如：

url = QUrl.fromLocalFile("file.txt")
baseUrl = QUrl("file:/home/user/")
# wrong: prints QUrl("file:file.txt"), as url already has a scheme
print(baseUrl.resolved(url))

要解析这样的URL，需要事先移除方案：

# correct: prints QUrl("file:///home/user/file.txt")
url.setScheme(QString())
print(baseUrl.resolved(url))

因此，最好使用相对URL（即没有方案）来表示相对文件路径：

url = QUrl("file.txt")
baseUrl = QUrl("file:/home/user/")
# prints QUrl("file:///home/user/file.txt")
print(baseUrl.resolved(url))

另请参阅

toLocalFile() isLocalFile() toNativeSeparators()

static fromPercentEncoding(input)
Parameters:

输入 – QByteArray

Return type:

字符串

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

注意

给定无效的输入（例如包含序列“%G5”的字符串，这不是一个有效的十六进制数字），输出也将无效。例如：序列“%G5”可能被解码为‘W’。

static fromStringList(uris[, mode=QUrl.ParsingMode.TolerantMode])
Parameters:
Return type:

.list of QUrl

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

static fromUserInput(userInput[, workingDirectory=""[, options=QUrl.UserInputResolutionOption.DefaultResolution]])
Parameters:
Return type:

QUrl

从用户提供的userInput字符串中返回一个有效的URL（如果可以推断出）。如果不可能，则返回一个无效的QUrl()。

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

当字符串还不是一个有效的URL时，会进行最佳猜测，做出各种假设。

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

如果不是这种情况，会尝试将字符串转换为http://或ftp:// URL。如果字符串以‘ftp’开头，则转换为后者。然后结果通过QUrl的宽容解析器处理，如果成功，则返回一个有效的QUrl，否则返回QUrl()。

示例:

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

默认情况下，看起来像相对路径的输入字符串只有在给定工作目录中实际存在该文件时才会被视为相对路径。如果应用程序可以处理尚不存在的文件，则应在options中传递标志AssumeLocalFile。

hasFragment()
Return type:

布尔

如果此URL包含片段（即，如果在其中看到#），则返回true。

另请参阅

fragment() setFragment()

hasQuery()
Return type:

布尔

如果此URL包含查询（即，如果在其中看到?），则返回true。

host([options=QUrl.ComponentFormattingOption.FullyDecoded])
Parameters:

options – ComponentFormattingOption 的组合

Return type:

字符串

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

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

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

static idnWhitelist()
Return type:

字符串列表

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

请参阅setIdnWhitelist()了解此列表的原理。

isEmpty()
Return type:

布尔

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

另请参阅

clear()

isLocalFile()
Return type:

布尔

如果此URL指向本地文件路径，则返回true。如果方案的协议是“file”，则URL是本地文件路径。

请注意，此函数将带有主机名的URL视为本地文件路径，即使最终的文件路径无法使用open()打开。

isParentOf(url)
Parameters:

url – QUrl

Return type:

布尔

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

isRelative()
Return type:

布尔

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

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

另请参阅

相对 URLs 与 相对 路径

isValid()
Return type:

布尔

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

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

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

bool checkUrl(QUrl url) {
    if not url.isValid():
        qDebug("Invalid URL: %s", qUtf8Printable(url.toString()))
        return False

    return True
matches(url, options)
Parameters:
Return type:

布尔

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

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

__ne__(rhs)
Parameters:

rhs – QUrl

Return type:

布尔

如果 lhs 和 rhs 的 URL 不相等，则返回 true；否则返回 false。

另请参阅

matches()

__lt__(rhs)
Parameters:

rhs – QUrl

Return type:

布尔

__le__(rhs)
Parameters:

rhs – QUrl

Return type:

布尔

__eq__(rhs)
Parameters:

rhs – QUrl

Return type:

布尔

如果 lhs 和 rhs URL 相等，则返回 true；否则返回 false。

另请参阅

matches()

__gt__(rhs)
Parameters:

rhs – QUrl

Return type:

布尔

__ge__(rhs)
Parameters:

rhs – QUrl

Return type:

布尔

password([options=QUrl.ComponentFormattingOption.FullyDecoded])
Parameters:

options – ComponentFormattingOption 的组合

Return type:

字符串

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

options 参数控制如何格式化用户名组件。所有值都会产生明确的结果。使用 FullyDecoded 时，所有百分比编码的序列都会被解码；否则，返回值可能包含一些百分比编码的序列，用于某些在 QString 中无法以解码形式表示的控制序列。

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

另请参阅

setPassword()

path([options=QUrl.ComponentFormattingOption.FullyDecoded])
Parameters:

options – ComponentFormattingOption 的组合

Return type:

字符串

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

返回URL的路径。

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

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

请注意，如果存在那些不可表示的序列，FullyDecoded可能会导致数据丢失。建议在结果将用于非URL上下文时使用该值，例如发送到FTP服务器。

数据丢失的一个例子是当你有非Unicode百分号编码序列并使用FullyDecoded（默认）时：

print(QUrl("/foo%FFbar").path())

在这个例子中，由于%FF无法转换，会有一定程度的数据丢失。

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

print(QUrl("/foo+bar%2B").path() # "/foo+bar+")

其他解码示例：

url = QUrl("/tmp/Mambo %235%3F.mp3")
print(url.path(QUrl.FullyDecoded) # "/tmp/Mambo #5?.mp3")
print(url.path(QUrl.PrettyDecoded) # "/tmp/Mambo #5?.mp3")
print(url.path(QUrl.FullyEncoded) # "/tmp/Mambo%20%235%3F.mp3")

另请参阅

setPath()

port([defaultPort=-1])
Parameters:

defaultPort – int

Return type:

整数

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

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

示例：

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

另请参阅

setPort()

query([options=QUrl.ComponentFormattingOption.PrettyDecoded])
Parameters:

options – ComponentFormattingOption 的组合

Return type:

字符串

如果URL中有查询字符串，则返回查询字符串；如果没有，则返回空结果。要确定解析的URL是否包含查询字符串，请使用hasQuery()。

options 参数控制如何格式化查询组件。所有值都会产生明确的结果。使用 FullyDecoded 时，所有百分比编码的序列都会被解码；否则，返回值可能包含一些百分比编码的序列，用于某些在 QString 中无法以解码形式表示的控制序列。

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

另请参阅

setQuery() hasQuery()

resolved(relative)
Parameters:

相对 – QUrl

Return type:

QUrl

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

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

如果 relative 不是一个相对URL，这个函数将直接返回 relative。否则，两个URL的路径将被合并，返回的新URL将具有基础URL的方案和权限，但使用合并后的路径，如下例所示：

baseUrl = QUrl("http://qt.digia.com/Support/")
relativeUrl = QUrl("../Product/Library/")
qDebug(baseUrl.resolved(relativeUrl).toString())
# prints "http://qt.digia.com/Product/Library/"

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

另请参阅

isRelative()

scheme()
Return type:

字符串

返回URL的方案。如果返回空字符串，这意味着方案未定义，URL是相对的。

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

另请参阅

setScheme() isRelative()

setAuthority(authority[, mode=QUrl.ParsingMode.TolerantMode])
Parameters:

将URL的权限设置为authority。

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

用户信息和主机之间用‘@’分隔，主机和端口之间用‘:’分隔。如果用户信息为空，则必须省略‘@’；尽管如果端口为空，允许存在多余的‘:’。

以下示例显示了一个有效的授权字符串：

../../_images/qurl-authority.png

authority 数据根据 mode 进行解释：在 StrictMode 中，任何 '%' 字符必须紧跟两个十六进制字符，并且某些字符（包括空格）不允许以未解码的形式出现。在 TolerantMode（默认模式）中，所有字符都可以以未解码的形式接受，并且宽容的解析器会纠正未紧跟两个十六进制字符的 '%'。

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

setFragment(fragment[, mode=QUrl.ParsingMode.TolerantMode])
Parameters:

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

../../_images/qurl-fragment.png

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

传递一个QString()参数（一个空的QString）将取消片段。传递一个QString（“”）参数（一个空但不为空的QString）将把片段设置为空字符串（就像原始URL有一个单独的“#”一样）。

fragment 数据根据 mode 进行解释：在 StrictMode 中，任何‘%’字符必须紧跟两个十六进制字符，并且某些字符（包括空格）不允许以未解码的形式出现。在 TolerantMode 中，所有字符都可以以未解码的形式接受，并且宽容的解析器会纠正未紧跟两个十六进制字符的‘%’。在 DecodedMode 中，‘%’代表它们自己，并且编码字符是不可能的。

DecodedMode 应在从非URL的数据源设置片段时使用，或者在使用FullyDecoded格式化选项调用fragment()获取片段时使用。

另请参阅

fragment() hasFragment()

setHost(host[, mode=QUrl.ParsingMode.DecodedMode])
Parameters:

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

host 数据根据 mode 进行解释：在 StrictMode 中，任何‘%’字符必须紧跟两个十六进制字符，并且某些字符（包括空格）不允许以未解码的形式出现。在 TolerantMode 中，所有字符都可以以未解码的形式接受，并且宽容的解析器会纠正未紧跟两个十六进制字符的‘%’。在 DecodedMode 中，‘%’代表它们自己，并且编码字符是不可能的。

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

另请参阅

host() setAuthority()

static setIdnWhitelist(list)
Parameters:

list – 字符串列表

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

请注意，如果您调用此函数，您需要在启动任何可能访问idnWhitelist()的线程之前执行此操作。

Qt 附带了一个默认列表，其中包含已发布支持国际化域名 (IDNs) 的互联网顶级域名，以及确保在相似字符之间不会发生欺骗的规则（例如拉丁小写字母 'a' 和西里尔字母等效字符，在大多数字体中视觉上是相同的）。

此列表会定期更新，因为注册商会发布新规则。

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

另请参阅

idnWhitelist()

setPassword(password[, mode=QUrl.ParsingMode.DecodedMode])
Parameters:

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

password 数据根据 mode 进行解释：在 StrictMode 中，任何‘%’字符必须紧跟两个十六进制字符，并且某些字符（包括空格）不能以未解码的形式出现。在 TolerantMode 中，所有字符都可以以未解码的形式接受，并且宽容的解析器会纠正未紧跟两个十六进制字符的‘%’。在 DecodedMode 中，‘%’代表它们自己，并且编码字符是不可能的。

DecodedMode 应在从非URL的数据源设置密码时使用，例如向用户显示的密码对话框或通过调用带有FullyDecoded格式化选项的password()获得的密码。

另请参阅

password() setUserInfo()

setPath(path[, mode=QUrl.ParsingMode.DecodedMode])
Parameters:

设置URL的路径为path。路径是URL中位于授权部分之后但在查询字符串之前的部分。

../../_images/qurl-ftppath.png

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

../../_images/qurl-mailtopath.png

path 数据根据 mode 进行解释：在 StrictMode 中，任何‘%’字符必须紧跟两个十六进制字符，并且某些字符（包括空格）不允许以未解码的形式出现。在 TolerantMode 中，所有字符都可以以未解码的形式接受，并且宽容的解析器会纠正未紧跟两个十六进制字符的‘%’。在 DecodedMode 中，‘%’代表它们自己，并且编码字符是不可能的。

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

另请参阅

path()

setPort(port)
Parameters:

端口 – int

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

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

另请参阅

port()

setQuery(query)
Parameters:

查询 – QUrlQuery

这是一个重载函数。

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

此函数从QUrlQuery对象重建查询字符串并设置到此QUrl对象上。此函数没有解析参数，因为QUrlQuery包含已经解析的数据。

另请参阅

query() hasQuery()

setQuery(query[, mode=QUrl.ParsingMode.TolerantMode])
Parameters:

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

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

将QString()的值传递给query（一个空的QString）会完全取消查询。然而，传递QString（“”）的值会将查询设置为空值，就像原始URL只有一个“？”一样。

query 数据根据 mode 进行解释：在 StrictMode 中，任何‘%’字符必须紧跟两个十六进制字符，并且某些字符（包括空格）不允许以未解码的形式出现。在 TolerantMode 中，所有字符都可以以未解码的形式接受，并且宽容的解析器会纠正未紧跟两个十六进制字符的‘%’。在 DecodedMode 中，‘%’代表它们自己，并且编码字符是不可能的。

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

另请参阅

query() hasQuery()

setScheme(scheme)
Parameters:

scheme – str

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

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

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

一个方案严格遵循RFC 3986标准：scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )

以下示例显示了一个URL，其方案为“ftp”：

../../_images/qurl-authority2.png

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

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

方案也可以是空的，在这种情况下，URL 被解释为相对路径。

另请参阅

scheme() isRelative()

setUrl(url[, mode=QUrl.ParsingMode.TolerantMode])
Parameters:

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

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

另请参阅

url() toString()

setUserInfo(userInfo[, mode=QUrl.ParsingMode.TolerantMode])
Parameters:

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

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

../../_images/qurl-authority3.png

userInfo 数据根据 mode 进行解释：在 StrictMode 中，任何‘%’字符必须紧跟两个十六进制字符，并且某些字符（包括空格）不允许以未解码的形式出现。在 TolerantMode（默认模式）中，所有字符都可以以未解码的形式接受，并且宽容的解析器会纠正未紧跟两个十六进制字符的‘%’。

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

setUserName(userName[, mode=QUrl.ParsingMode.DecodedMode])
Parameters:

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

userName 数据根据 mode 进行解释：在 StrictMode 中，任何‘%’字符必须紧跟两个十六进制字符，并且某些字符（包括空格）不允许以未解码的形式出现。在 TolerantMode（默认模式）中，所有字符都可以以未解码的形式接受，并且宽容的解析器会纠正未紧跟两个十六进制字符的‘%’。在 DecodedMode 中，‘%’代表它们自己，编码字符是不可能的。

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

另请参阅

userName() setUserInfo()

swap(other)
Parameters:

其他 – QUrl

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

static toAce(domain[, options={}])
Parameters:
Return type:

QByteArray

返回给定域名 domain 的ASCII兼容编码。可以通过传递带有 options 的标志来自定义输出。此函数的结果被认为等同于 domain。

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

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

toDisplayString([options=QUrl.FormattingOptions(QUrl.ComponentFormattingOption.PrettyDecoded)])
Parameters:

options – ComponentFormattingOption 的组合

Return type:

字符串

返回一个可供人类阅读的URL字符串表示。输出可以通过传递带有options的标志进行自定义。选项RemovePassword始终启用，因为密码不应显示给用户。

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

另请参阅

FormattingOptions toEncoded() toString()

toEncoded([options=QUrl.ComponentFormattingOption.FullyEncoded])
Parameters:

options – ComponentFormattingOption 的组合

Return type:

QByteArray

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

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

toLocalFile()
Return type:

字符串

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

返回此URL格式化为本地文件路径的路径。返回的路径将使用正斜杠，即使它最初是从带有反斜杠的路径创建的。

如果此URL包含非空的主机名，它将以SMB网络上的形式编码在返回值中（例如，“//servername/path/to/file.txt”）。

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

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

static toPercentEncoding(input[, exclude=QByteArray()[, include=QByteArray()]])
Parameters:
Return type:

QByteArray

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

返回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}"
toString([options=QUrl.FormattingOptions(QUrl.ComponentFormattingOption.PrettyDecoded)])
Parameters:

options – ComponentFormattingOption 的组合

Return type:

字符串

返回URL的字符串表示。输出可以通过传递带有options的标志来自定义。在此函数中不允许使用FullyDecoded选项，因为它会生成不明确的数据。

默认的格式化选项是 PrettyDecoded 。

另请参阅

FormattingOptions url() setUrl()

static toStringList(uris[, options=QUrl.FormattingOptions(QUrl.ComponentFormattingOption.PrettyDecoded)])
Parameters:
Return type:

字符串列表

将urls列表转换为QString对象列表，使用toString (options)。

url([options=QUrl.FormattingOptions(QUrl.ComponentFormattingOption.PrettyDecoded)])
Parameters:

options – ComponentFormattingOption 的组合

Return type:

字符串

返回URL的字符串表示。输出可以通过传递带有options的标志来自定义。在此函数中不允许使用选项FullyDecoded，因为它会生成不明确的数据。

生成的 QString 可以稍后传递回 QUrl。

toString (选项) 的同义词。

另请参阅

setUrl() FormattingOptions toEncoded() toString()

userInfo([options=QUrl.ComponentFormattingOption.PrettyDecoded])
Parameters:

options – ComponentFormattingOption 的组合

Return type:

字符串

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

此函数返回一个明确的值，该值可能包含仍为百分号编码的字符，以及一些在QString中无法以解码形式表示的控制序列。

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

userName([options=QUrl.ComponentFormattingOption.FullyDecoded])
Parameters:

options – ComponentFormattingOption 的组合

Return type:

字符串

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

options 参数控制如何格式化用户名组件。所有值都会产生明确的结果。使用 FullyDecoded 时，所有百分比编码的序列都会被解码；否则，返回值可能包含一些百分比编码的序列，用于某些在 QString 中无法以解码形式表示的控制序列。

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

另请参阅

setUserName() userInfo()