PySide6.QtCore.QUrlQuery

class QUrlQuery

QUrlQuery 类提供了一种操作URL查询中键值对的方式。更多…

概要

方法

注意

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

详细描述

警告

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

它用于解析在以下URL中找到的查询字符串：

../../_images/qurl-querystring.png

像上面这样的查询字符串用于在URL中传输选项，通常被解码为多个键值对。上面的查询字符串将在其列表中包含两个条目，键为“type”和“color”。QUrlQuery 也可以用于从查询的各个组件创建适合在 setQuery() 中使用的查询字符串。

解析查询字符串的最常见方法是在构造函数中通过传递查询字符串来初始化它。否则，可以使用setQuery()方法来设置要解析的查询。该方法还可以用于解析具有非标准分隔符的查询，前提是已经使用setQueryDelimiters()函数设置了这些分隔符。

可以使用query()再次获取编码后的查询字符串。这将获取所有内部存储的项目并使用分隔符对字符串进行编码。

编码

QUrlQuery 中的所有获取方法都支持一个可选的 ComponentFormattingOptions 类型的参数，包括 query()，这些参数决定了如何编码相关数据。除了 FullyDecoded 之外，返回值仍然必须被视为百分号编码的字符串，因为有些值无法以解码形式表示（如控制字符，无法解码为 UTF-8 的字节序列）。因此，百分号字符总是由字符串“%25”表示。

所有的设置方法和查询方法，如hasQueryItem()在QUrlQuery中，只接受编码形式。与QUrl不同，没有可选参数来指定传递的字符串是解码的。如果传递了编码不当的字符串给设置或查询方法，QUrlQuery将尝试恢复而不是失败。也就是说，这个类中的所有函数解析它们的字符串参数时，都像是指定了TolerantMode解码模式。

应用程序代码应始终确保正确的编码，而不依赖于TolerantMode解析来修复字符串。特别是，所有用户输入在传递给此类中的函数之前，必须首先使用toPercentEncoding()或类似函数进行百分比编码。

处理空格和加号（“+”）

Web浏览器通常会将HTML表单元素中的空格编码为加号（“+”），并将加号编码为其百分比编码形式（%2B）。然而，管理URL的互联网规范并不认为空格和加号字符是等价的。

因此，QUrlQuery 从不将空格字符编码为“+”，也从不将“+”解码为空格字符。相反，空格字符将以“%20”的形式进行编码。

为了支持像HTML表单那样的编码，QUrlQuery 也不会将“%2B”序列解码为加号，也不会将加号编码。实际上，在键、值或查询字符串中找到的任何“%2B”或“+”序列都会完全按照写入的方式保留（除了将“%2b”转换为“%2B”的大写形式）。

完全解码

使用FullyDecoded格式化时，所有百分比编码的序列将被完全解码，并且‘%’字符用于表示自身。FullyDecoded应谨慎使用，因为它可能导致数据丢失。有关可能丢失的数据的信息，请参阅FullyDecoded的文档。

这种格式化模式应仅在处理不希望使用百分比编码的上下文中向用户呈现的文本时使用。请注意，QUrlQuery的设置器和查询方法不支持对应的DecodedMode解析，因此使用FullyDecoded获取键列表可能会导致在对象中找不到键。

非标准分隔符

默认情况下，QUrlQuery 使用等号（“=”）来分隔键和其值，并使用和号（”&”）来分隔键值对。可以通过调用 setQueryDelimiters() 来更改 QUrlQuery 用于解析和重建查询的分隔符。

非标准分隔符应从RFC 3986所称的“子分隔符”中选择。它们是：

sub-delims = "!" / "$" / "" / "'" / "(" / ")"
              / "*" / "+" / "," / ";" / "="

不支持使用其他字符，可能会导致意外行为。QUrlQuery不会验证您传递的分隔符是否有效。

另请参阅

QUrl

__init__()

构造一个空的QUrlQuery对象。之后可以通过调用setQuery()来设置查询，或者使用addQueryItem()来添加项目。

另请参阅

setQuery() addQueryItem()

__init__(queryString)
Parameters:

queryString – str

构造一个QUrlQuery对象并解析queryString查询字符串，使用默认的查询分隔符。要使用其他分隔符解析查询字符串，您应该首先使用setQueryDelimiters()设置它们，然后使用setQuery()设置查询。

__init__(url)
Parameters:

url – QUrl

构造一个QUrlQuery对象，并使用默认的查询分隔符解析url URL中的查询字符串。要使用其他分隔符解析查询字符串，您应首先使用setQueryDelimiters()设置它们，然后使用setQuery()设置查询。

另请参阅

query()

__init__(other)
Parameters:

其他 – QUrlQuery

复制other QUrlQuery对象的内容，包括查询分隔符。

addQueryItem(key, value)
Parameters:

  • key – str

  • value – str

将键值对 key = value 附加到URL的查询字符串末尾。此方法不会覆盖可能存在的具有相同键的现有项。

注意

此方法不会像HTML表单那样将空格（ASCII 0x20）和加号（“+”）视为相同。如果您需要将空格表示为加号，请使用实际的加号。

注意

键和值字符串应以百分比编码形式提供。

另请参阅

hasQueryItem() queryItemValue()

allQueryItemValues(key[, encoding=QUrl.PrettyDecoded])
Parameters:
Return type:

字符串列表

返回URL中键等于key的查询字符串值列表，使用encoding中指定的选项对返回值进行编码。如果未找到键key，此函数返回一个空列表。

注意

密钥预计以百分比编码形式存在。

另请参阅

queryItemValue() addQueryItem()

clear()

清除此QUrlQuery对象，移除当前存储的所有键值对。如果查询分隔符已被更改，此函数将保留其更改后的值。

hasQueryItem(key)
Parameters:

key – str

Return type:

布尔

如果URL中存在键等于key的查询字符串对，则返回true。

注意

预期以百分比编码形式存在的键。

另请参阅

addQueryItem() queryItemValue()

isEmpty()
Return type:

布尔

如果此QUrlQuery对象不包含任何键值对，例如在默认构造后或解析空查询字符串后，则返回true。

另请参阅

setQuery() clear()

__ne__(rhs)
Parameters:

rhs – QUrlQuery

Return type:

布尔

如果QUrlQuery对象rhs不等于lhs，则返回true。否则，返回false。

另请参阅

operator==()

__eq__(rhs)
Parameters:

rhs – QUrlQuery

Return type:

布尔

如果QUrlQuery对象lhs和rhs包含相同的内容，顺序相同，并且使用相同的查询分隔符，则返回true。

query([encoding=QUrl.PrettyDecoded])
Parameters:

编码 – ComponentFormattingOption 的组合

Return type:

字符串

返回重构的查询字符串，该字符串由当前存储在此QUrlQuery对象中的键值对组成，并由为此对象选择的查询分隔符分隔。键和值使用encoding参数给定的选项进行编码。

对于这个函数，唯一不明确的分隔符是井号（“#”），因为在URL中它用于将查询字符串与可能跟随的片段分开。

返回字符串中键值对的顺序与原始查询中的顺序完全相同。

另请参阅

setQuery() setQuery() fragment() 编码

queryItemValue(key[, encoding=QUrl.PrettyDecoded])
Parameters:
Return type:

字符串

返回与URL中键key关联的查询值，使用encoding中指定的选项对返回值进行编码。如果未找到键key，此函数返回一个空字符串。如果需要区分空值和不存在的键，应首先使用hasQueryItem()检查键是否存在。

如果键 key 被多次定义，此函数将返回找到的第一个，按照它们在查询字符串中出现的顺序或使用 addQueryItem() 添加的顺序。

注意

密钥预计以百分比编码形式存在。

另请参阅

addQueryItem() allQueryItemValues() 编码

queryItems([encoding=QUrl.PrettyDecoded])
Parameters:

编码 – ComponentFormattingOption 的组合

Return type:

.std.pairQString,QString 的列表

返回URL的查询字符串，作为键和值的映射，使用encoding中指定的选项对项目进行编码。元素的顺序与查询字符串中的顺序或通过setQueryItems()设置的顺序相同。

另请参阅

setQueryItems() 编码

queryPairDelimiter()
Return type:

QChar

返回在query()中重构查询字符串或在setQuery()中解析时用于分隔键值对的字符。

queryValueDelimiter()
Return type:

QChar

返回在query()中重构查询字符串或在setQuery()中解析时用于分隔键和值的字符。

removeAllQueryItems(key)
Parameters:

key – str

从URL中移除所有键等于key的查询字符串对。

注意

密钥预计以百分比编码形式存在。

另请参阅

removeQueryItem()

removeQueryItem(key)
Parameters:

key – str

从URL中移除键等于key的查询字符串对。如果有多个键等于key的项，它会移除查询字符串中第一个出现的项或使用addQueryItem()添加的项。

注意

密钥预计以百分比编码形式存在。

另请参阅

removeAllQueryItems()

setQuery(queryString)
Parameters:

queryString – str

解析queryString中的查询字符串，并将内部项设置为找到的值。如果已使用setQueryDelimiters()指定了任何分隔符，此函数将使用它们而不是默认分隔符来解析字符串。

另请参阅

query()

setQueryDelimiters(valueDelimiter, pairDelimiter)
Parameters:

  • valueDelimiter – QChar

  • pairDelimiter – QChar

警告

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

设置用于在URL的查询字符串中分隔键和值以及键值对之间的字符。默认的值分隔符是‘=’，默认的键值对分隔符是‘&’。

../../_images/qurl-querystring.png

valueDelimiter 将用于分隔键和值，而 pairDelimiter 将用于分隔键值对。在查询字符串的键和值的编码表示中出现的这些分隔字符的任何实例，在通过 query() 返回时都会被百分号编码。

如果 valueDelimiter 设置为 ‘,’ 并且 pairDelimiter 是 ‘;’，上面的查询字符串将表示为这样：

http://www.example.com/cgi-bin/drawgraph.cgi?type,pie;color,green

注意

非标准分隔符应从RFC 3986所称的“子分隔符”中选择。它们是：

sub-delims = "!" / "$" / "" / "'" / "(" / ")"
              / "*" / "+" / "," / ";" / "="

不支持使用其他字符，可能会导致意外行为。此方法不会验证您传递的分隔符是否有效。

setQueryItems(query)
Parameters:

query – .std.pairQString,QString 的列表

将此QUrlQuery对象中的项目设置为query。query中元素的顺序将被保留。

注意

此方法不会像HTML表单那样将空格（ASCII 0x20）和加号（“+”）视为相同。如果您需要将空格表示为加号，请使用实际的加号。

注意

键和值应以百分比编码形式表示。

另请参阅

queryItems() isEmpty()

swap(other)
Parameters:

其他 – QUrlQuery

将此URL查询实例与other交换。此函数非常快且永远不会失败。

toString([encoding=QUrl.PrettyDecoded])
Parameters:

编码 – ComponentFormattingOption 的组合

Return type:

字符串

返回此QUrlQuery为QString。encoding可用于指定返回值的URL字符串编码。