class QUrl#

QUrl 类提供了处理URL的便捷接口。 更多…

概要（Synopsis）#

方法（Methods）#

静态函数#

注意

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

详细说明#

警告

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

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

使用 QUrl 最常见的方法是通过构造函数以包含完整 URL 的 QString 来初始化它。QUrl 对象也可以使用 QByteArray（包含完整 URL）通过 fromEncoded() 来创建，或者使用 fromUserInput() 从不完整的 URL 来创建。可以从 QUrl 获取 URL 表示形式，使用 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转换为本地文件路径。

使用 toString() 获取URL的可读表示。这种表示适合以非编码形式向用户显示URL。然而，由 toEncoded() 返回的编码形式，用于内部使用，传递给Web服务器、邮件客户端等。这两种形式在技术上都是正确的，并明确地表示相同的URL——实际上，将任一形式传递给 QUrl 构造函数或 setUrl() 方法，都将产生相同的 QUrl 对象。

QUrl 遵循RFC 3986（统一资源标识符：通用语法）的URI规范，并包含RFC 1738（统一资源定位符）中的方案扩展。 QUrl 中的大小写组合规则符合RFC 3491（Nameprep：国际化域名（IDN）的Stringprep配置文件）。只要(locale)使用UTF-8（IDN所需的）对文件名进行编码，它也兼容来自 freedesktop.org 的 文件URI规范。

相对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，这将返回一个绝对URL。 isParentOf() 用于确定一个URL是否是另一个URL的父URL。

错误检查#

QUrl 在解析 URL 或当使用单独的设定方法（如 setScheme() 、setHost() 或 setPath()）设置 URL 的各个组件时，能够检测到许多错误。如果解析或设定函数执行成功，则先前记录的错误条件将被丢弃。

默认情况下，QUrl 的设定方法在 TolerantMode（容忍模式）下操作，这意味着它们接受一些常见错误和数据表示不准确。另一种解析方法是 StrictMode（严格模式），它应用了额外的检查。有关解析模式差异的描述，请参阅 ParsingMode。

QUrl 只检查是否与 URL 规范一致，它并不尝试验证高级协议 URL 是否符合其他处理程序预期的格式。例如，以下 URI 都被 QUrl 识别为有效，即使它们在实际应用中可能没有意义。

当解析器遇到错误时，它会通过使 isValid() 返回 false 和 toString() / toEncoded() 返回空字符串来触发事件。如果需要向用户显示 URL 解析失败的原因，可以通过调用 QUrl 的 errorString() 获取错误条件。请注意，这条信息非常技术性，可能对最终用户来说并不容易理解。

QUrl 能记录的错误条件只有一个。如果发现多个错误，不确定哪一种错误会被报告。

字符转换

遵循以下规则，在处理 URL 和字符串时避免错误的字符转换。

  • 当从一个QByteArray或一个char*创建用于存储URL的QString时，始终使用fromUtf8()。

类 ParsingMode#

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

常量

描述

QUrl.TolerantMode

QUrl将尝试纠正URL中的一些常见错误。此模式对于解析来源不严格遵循标准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()来再次解码。在单个组件的获取器中，这些字符通常以解码形式返回。

当处于严格模式时，如果遇到解析错误，isValid() 将返回 false，errorString() 将返回描述错误的消息。如果检测到多个错误，哪个错误被报告是不确定的。

请注意，容忍模式通常不足以解析用户输入，因为用户输入通常包含比解析器能够处理的更多错误和期望。当处理直接从用户那里来的数据——与来自数据传输源的数据（例如，其他程序）相比——建议使用 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

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

QUrl.StripTrailingSlash

如果路径中存在末尾的斜杠，则将其移除。

QUrl.NormalizePathSegments

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

请注意，QUrl 使用的 Nameprep 中的大小写折叠规则要求始终将主机名转换为小写，而不管使用哪种 Qt::FormattingOptions。

还可以使用来自 ComponentFormattingOptions 的选项。

另请参阅

ComponentFormattingOptions

类 ComponentFormattingOption#

警告

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

（继承自 enum.IntFlag）组件格式化选项定义了当URL以文本形式输出时各个组件的格式化方式。当在 toString() 和 toEncoded() 中使用时，它们可以与来自 FormattingOptions 的选项组合使用。

常量

描述

QUrl.PrettyDecoded

以“美观形式”返回组件，其中大多数百分号编码字符被解码。PrettyDecoded的确切行为因组件而异，并且可能随着Qt版本的更新而改变。这是默认设置。

QUrl.EncodeSpaces

保留空白字符的编码形式（“%20”）。

QUrl.EncodeUnicode

保留非US-ASCII字符的UTF-8百分号编码形式（例如，对于U+00E9代码点，使用“%C3%A9”表示小写拉丁字母é）。

QUrl.EncodeDelimiters

保留某些分隔符的编码形式，正如当整个URL以文本表示时在URL中看到的那样。分隔符会因选项更改而影响各个组件。在此选项下，toString() 或 toEncoded() 中没有效果。

QUrl.EncodeReserved

保留URL规范不允许出现在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上）的“美观模式”对于保留字符的行为不同。

完整解码#

全解码模式类似于Qt 4.x中返回QString函数的行为，其中每个字符都是其本身，没有任何特殊意义。这同样适用于百分号字符（‘%’），它应被解释为字面意义上的百分号，而不是百分号编码序列的开始。在全其他解码模式中，相同的字符由“%25”序列表示。

当将使用QUrl::FullyDecoded获取的数据重新应用于QUrl时，必须小心使用设置器（如setPath()和setUserName()）的DecodedMode参数。否则可能会导致将百分号字符（‘%’）重新解释为百分号编码序列的开始。

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

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

  • 非UTF-8序列：URL中可能包含无效的UTF-8序列的百分号编码字符序列。由于需要使用UTF-8解码URL，解码器失败将在存在序列的地方在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使用，网络服务器的解释可能不同。在第一种情况下，它将解释为一个参数，键为“q”，值为“a+=b&c”。在第二种情况下，它可能将解释为两个参数，一个键为“q”，值为“a =b”，另一个键为“c”，没有值。

另请参阅

格式化选项

class UserInputResolutionOption#

(继承自enum.Flag) 用户输入解析选项定义了如何解释可以是相对路径或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__(url[, mode=QUrl.ParsingMode.TolerantMode])#
参数:

警告

本节包含从 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。

__init__()

构建一个空的QUrl对象。

__init__(copy)
参数:

copy – QUrl

构建其他对象的副本。

__reduce__()#
返回类型：

对象

__repr__()#
返回类型：

对象

adjusted(options)#
参数:

options – 组合了 ComponentFormattingOption

返回类型：

QUrl

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

来自 ComponentFormattingOption 的编码选项对这种方法没有多大意义，同样也没有 PreferLocalFile 。

这始终与 QUrl（url.toString（options） 相等。

另请参阅

FormattingOptions toEncoded() toString()

authority([options=QUrl.ComponentFormattingOption.PrettyDecoded])#
参数:

options – 组合了 ComponentFormattingOption

返回类型：

字符串

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

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

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

clear()#

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

另请参阅

isEmpty()

errorString()#
返回类型：

字符串

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

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

另请参阅

解析模式

fileName([options=QUrl.ComponentFormattingOption.FullyDecoded])#
参数:

options – 组合了 ComponentFormattingOption

返回类型：

字符串

警告

本节包含从 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])#
参数:

options – 组合了 ComponentFormattingOption

返回类型：

字符串

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

参数options控制如何格式化分片组件。所有值都产生一个无歧义的结果。在FullyDecoded模式下，所有百分比编码的序列都将被解码；否则，返回的值可能包含一些在QString中无法表示的控制序列的百分比编码序列。

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

另请参阅

setFragment() hasFragment()

静态fromAce(domain[, options={}])#
参数:

  • domain – QByteArray

  • options – AceProcessingOption的组合

返回类型：

字符串

返回给定的ASCII兼容编码（ACE）域名名称的Unicode形式，该域名名称编码在ASCII兼容编码（ACE）中。通过传递具有options的标志来自定义输出。此函数的结果被认为与domain相同。

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

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

静态fromEncoded(input[, mode=QUrl.ParsingMode.TolerantMode])#
参数:
返回类型：

QUrl

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

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

注意

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

另请参阅

toEncoded() setUrl()

静态fromLocalFile(localfile)#
参数:

localfile – str

返回类型：

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()

静态 fromPercentEncoding(arg__1)#
参数:

arg__1 – QByteArray

返回类型：

字符串

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

注意

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

静态 fromStringList(uris[, mode=QUrl.ParsingMode.TolerantMode])#
参数:
返回类型：

. QUrl 列表

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

静态 fromUserInput(userInput[, workingDirectory=""[, options=QUrl.UserInputResolutionOption.DefaultResolution]])#
参数:
返回类型：

QUrl

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

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

当字符串本身不是有效的 URL 时，将进行最佳猜测，并做出各种假设。

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

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

示例：

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

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

hasFragment()#
返回类型：

bool

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

另请参阅

fragment() setFragment()

hasQuery()#
返回类型：

bool

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

host([arg__1=QUrl.ComponentFormattingOption.FullyDecoded])#
参数:

arg__1 – 组合 ComponentFormattingOption

返回类型：

字符串

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

参数options控制主机名将如何格式化。如果设置了EncodeUnicode选项，则此函数将以ASCII兼容编码(ACE)形式返回主机名，这在非8位清洁或不要求使用传统主机名（如DNS请求或在HTTP请求标题）的通道中使用是合适的。如果没有设置该标志，则此函数将根据允许的顶级域名列表以Unicode形式返回国际域名名称(IDN)，具体请参见idnWhitelist() )。

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

静态idnWhitelist()#
返回类型：

字符串列表

返回当前允许在域名组成中使用非ASCII字符的顶级域的允许列表。

有关此列表的合理性，请见setIdnWhitelist()。

isEmpty()#
返回类型：

bool

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

另请参阅

clear()

isLocalFile()#
返回类型：

bool

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

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

isParentOf(url)#
参数:

url – QUrl

返回类型：

bool

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

isRelative()#
返回类型：

bool

如果URL是相对的，返回true；否则返回false。如果URL的方案未定义，则该URL是相对引用；因此，此函数与调用scheme()、isEmpty()的功能等效。

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

另请参阅

相对URL vs 相对路径

isValid()#
返回类型：

bool

警告

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

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

对URL进行一致性测试。URL的每一部分都必须符合URI标准的编码规则，URL才被视为有效。

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

    return True
matches(url, options)#
参数:
返回类型：

bool

如果通过将options应用于这两个URL后，此URL与给定的url相等，则返回true；否则返回false。

这与在每个URL上调用adjusted(options)并将结果URL进行比较等效，但更快。

__ne__(url)#
参数:

url – QUrl

返回类型：

bool

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

另请参阅

matches()

__lt__(url)#
参数:

url – QUrl

返回类型：

bool

__eq__(url)#
参数:

url – QUrl

返回类型：

bool

如果此URL与提供的 url 相等，则返回 true；否则返回 false。

另请参阅

matches()

password([arg__1=QUrl.ComponentFormattingOption.FullyDecoded])#
参数:

arg__1 – 组合 ComponentFormattingOption

返回类型：

字符串

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

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

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

另请参阅

setPassword()

path([options=QUrl.ComponentFormattingOption.FullyDecoded])#
参数:

options – 组合了 ComponentFormattingOption

返回类型：

字符串

警告

本节包含从 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])#
参数:

默认端口 – int

返回类型：

int

警告

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

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

示例

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

另请参阅

setPort()

query([arg__1=QUrl.ComponentFormattingOption.PrettyDecoded])#
参数:

arg__1 – 组合 ComponentFormattingOption

返回类型：

字符串

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

options 参数控制如何格式化查询组件。所有值都产生一个明确的result。在FullyDecoded 下，所有百分号编码序列将被解码；否则，返回的值可能包含一些在解码形式中无法表示的某些控制序列的百分号编码序列。

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

另请参阅

setQuery() hasQuery()

resolved(relative)#
参数:

relative – QUrl

返回类型：

QUrl

警告

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

返回此URL与 relative 合并的结果。此URL作为基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()#
返回类型：

字符串

返回URL的方案。如果返回空字符串，表示方案未定义，并且该URL是相对的。

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

另请参阅

setScheme() isRelative()

setAuthority(authority[, mode=QUrl.ParsingMode.TolerantMode])#
参数:

设置URL的权限为authority。

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

用户信息和主机名之间用 '@' 分隔，主机名和端口号之间用 ':' 分隔。如果用户信息为空，则 '@' 必须省略；即使端口号为空，也可以允许一个额外的 ':'。

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

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

authority数据根据mode进行解释：在StrictMode（严格模式）中，任何‘%’字符后面必须正好有两个十六进制字符，某些字符（包括空格）在未解码形式中是不允许的。在TolerantMode（默认模式）中，所有字符都接受为未解码形式，容错解析器将更正那些后面没有两个十六进制字符的‘%’。

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

setFragment(fragment[, mode=QUrl.ParsingMode.TolerantMode])#
参数:

将URL的碎片设置为fragment。碎片是URL的最后一部分，由一个‘#’和一个字符串组成。在HTTP中通常用来引用页面上某个特定的链接或点。

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

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

传递一个QString()（一个空代码）的参数将移除片段。传递一个 （一个空但非空的代码）的参数将片段设置为空字符串（就像原始URL有一个独立的“#”一样）。

根据数据根据 模式 解释:在 严格模式，任何‘%’字符必须由正好两个十六进制字符紧随其后，并且在未编码形式中不允许某些字符（包括空格）。在 宽容模式，所有字符都以未编码形式接受，并允许宽容解析器纠正不跟随两个十六进制字符的孤立的‘%’。在 已解码模式，‘%’表示自身，并且不可能存在已编码字符。

当从并非URL的数据源设置片段或通过带有 完全解码 格式化选项的 fragment() 获取片段时，应使用 DecodedMode。

另请参阅

fragment() hasFragment()

setHost(host[, mode=QUrl.ParsingMode.DecodedMode])#
参数:

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

根据数据根据 模式 解释:在 严格模式，任何‘%’字符必须由正好两个十六进制字符紧随其后，并且在未编码形式中不允许某些字符（包括空格）。在 宽容模式，所有字符都以未编码形式接受，并允许宽容解析器纠正不跟随两个十六进制字符的孤立的‘%’。在 已解码模式，‘%’表示自身，并且不可能存在已编码字符。

请注意，在所有情况下，解析结果必须是符合STD 3规则并且经过国际域名标识符规范（RFC 3987）修改后的有效主机名。不允许使用无效的主域名，这将导致

static setIdnWhitelist(arg__1)#
参数:

arg__1 – 字符串列表

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

请注意，如果您调用此函数，必须在调用idnWhitelist()之前完成。

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

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

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

另请参阅

idnWhitelist()

setPassword(password[, mode=QUrl.ParsingMode.DecodedMode])#
参数:

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

password数据根据mode进行解释：在StrictMode中，任何‘%’字符都必须后跟恰好两个十六进制字符，一些字符（包括空格）以未解码形式不允许。在TolerantMode中，所有字符以未解码形式接受，宽松解析器将纠正不在两位十六进制字符后面的“%”。在DecodedMode中，“%”代表其自身，编码字符是不可能的。

DecodedMode 应用于从一个非URL的数据源设置密码时，例如向用户展示的密码对话框或通过调用 password() 方法并获得密码，使用 FullyDecoded 格式化选项。

另请参阅

password() setUserInfo()

setPath(path[, mode=QUrl.ParsingMode.DecodedMode])#
参数:

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

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

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

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

path 数据的解释根据 mode 进行：在 StrictMode 中，任何‘%’字符之后必须精确地跟随两个十六进制字符，一些字符（包括空格）以未解码形式不允许。在 TolerantMode 中，所有字符以未解码形式接受，且容错解析器将校正没有两个十六进制字符跟随的随机‘%’。在 DecodedMode 中，‘%’代表其自身，且无法使用编码字符。

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

另请参阅

path()

setPort(port)#
参数:

port – 整型

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

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

另请参阅

port()

setQuery(query[, mode=QUrl.ParsingMode.TolerantMode])#
参数:

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

当需要传递不适合键值模式的查询字符串，或者使用与 QUrl 提议不同的方案来编码特殊字符时，该函数非常有用。

将 query 参数传递为 QString()（一个空的 QString ）将完全取消设置查询。然而，传递一个空的 QString （""）将设置查询为一个空值，就像原始 URL 有一个单独的“?”一样。

根据 mode 解释 query 数据：在 StrictMode 中，任何“%”字符后面必须正好跟着两个十六进制字符，某些字符（包括空格）不允许在未解码形式中使用。在 TolerantMode 中，所有字符都以未解码形式接受，并且容错解析器将纠正没有跟随两个十六进制字符的“%”。在 DecodedMode 中，“%”代表自身，无法进行编码字符。

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

另请参阅

query() hasQuery()

setQuery(query)
参数:

query – QUrlQuery

这是一个重载函数。

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

这个函数从 QUrlQuery 对象中重建查询字符串，并将它设置在当前的 QUrl 对象上。这个函数没有解析参数，因为 QUrlQuery 包含已经解析的数据。

另请参阅

query() hasQuery()

setScheme(scheme)#
参数:

schema – str

警告

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

将 URL 的模式设置为指定的 schema。由于模式只能包含 ASCII 字符，因此不对输入进行转换或解码。它也必须以 ASCII 字母开头。

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

模式严格遵循 RFC 3986 标准：schema = ALPHA *( ALPHA / DIGIT / "+ / "-" / "." )

以下示例展示了具有模式为“ftp”的 URL

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

要设置模式，可以使用以下调用

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

也可以设置为空，在这种情况下，URL 被解释为相对路径。

另请参阅

scheme() isRelative()

setUrl(url[, mode=QUrl.ParsingMode.TolerantMode])#
参数:

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

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

另请参阅

url() toString()

setUserInfo(userInfo[, mode=QUrl.ParsingMode.TolerantMode])#
参数:

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

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

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

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

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

setUserName(userName[, mode=QUrl.ParsingMode.DecodedMode])#
参数:

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

userName 数据的解析方式取决于 mode：在 StrictMode 下，任何‘%’字符都必须由恰好两个十六进制字符跟随，某些字符（包括空格）在未解码形式中不允许。在 TolerantMode（默认模式）下，所有字符都以未解码形式接受，且宽容解析器会纠正后面没有两个十六进制字符的‘%’。在 DecodedMode 下，‘%’代表自身，且不可能有编码字符。

设置用户名时如数据源不是 URL，例如用户界面中的密码对话框或通过调用 userName() 方法并通过 FullyDecoded 格式选项获取的用户名时，应使用 DecodedMode。

另请参阅

userName() setUserInfo()

swap(other)#
参数:

other – QUrl

交换 URLs other 和当前 URL。此操作非常快，绝对不会失败。

静态 toAce(domain[, options={}])#
参数:

  • domain – str

  • options – AceProcessingOption的组合

返回类型：

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)])#
参数:

options – 组合了 ComponentFormattingOption

返回类型：

字符串

返回 URL 的人类可读的字符串表示形式。可以通过传递带有 options 的标志来自定义输出。选项 RemovePassword 总是启用，因为密码决不应显示给用户。

使用默认选项，最终的 QString 可以稍后传回给一个 QUrl，但最初存在的任何密码都将丢失。

另请参阅

FormattingOptions toEncoded() toString()

toEncoded([options=QUrl.ComponentFormattingOption.FullyEncoded])#
参数:

options – 组合了 ComponentFormattingOption

返回类型：

QByteArray

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

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

toLocalFile()#
返回类型：

字符串

警告

本节包含从 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），则此函数的行为是未定义的。

静态toPercentEncoding(arg__1[, exclude=QByteArray()[, include=QByteArray()]])#
参数:
返回类型：

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)])#
参数:

options – 组合了 ComponentFormattingOption

返回类型：

字符串

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

默认格式化选项是 PrettyDecoded。

另请参阅

FormattingOptions url() setUrl()

静态toStringList(uris[, options=QUrl.FormattingOptions(QUrl.ComponentFormattingOption.PrettyDecoded)])#
参数:
返回类型：

字符串列表

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

url([options=QUrl.FormattingOptions(QUrl.ComponentFormattingOption.PrettyDecoded)])#
参数:

options – 组合了 ComponentFormattingOption

返回类型：

字符串

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

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

toString() 方法的同义词（选项）。

另请参阅

setUrl() FormattingOptions toEncoded() toString()

userInfo([options=QUrl.ComponentFormattingOption.PrettyDecoded])#
参数:

options – 组合了 ComponentFormattingOption

返回类型：

字符串

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

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

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

userName([options=QUrl.ComponentFormattingOption.FullyDecoded])#
参数:

options – 组合了 ComponentFormattingOption

返回类型：

字符串

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

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

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

另请参阅

setUserName() userInfo()