class QUrlQuery#

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

摘要#

方法#

备注

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

详细描述#

警告

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

用于解析以下URL中发现的查询字符串

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

如上所示的查询字符串用于在URL中传递选项，并且通常解码为多个键值对。上面的示例将包含其列表中的两个条目，键为“类型”和“颜色”。QUrlQuery也可以用于从查询的各个组件中创建适合使用于setQuery()的查询字符串。

解析查询字符串最常见的方式是在构造函数中通过传递查询字符串初始化它。否则，可以使用setQuery()方法设置要解析的查询。该方法还可以用于在设置它们后使用setQueryDelimiters()函数解析非标准分隔的查询。

可以使用query()重新获得编码的查询字符串。这将以分隔符对内部存储的项目进行编码。

编码#

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

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

应用程序代码应始终尽力确保适当的编码，而不是依赖于TolerantMode解析来修复字符串。值得注意的是，所有用户输入都必须首先使用toPercentEncoding()或类似函数对百分号进行编码，然后再传递给本类中的函数。

空格和加号的处理

网络浏览器通常会将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__(queryString)#
参数：:

queryString – str

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

__init__(url)
参数：:

url – QUrl

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

另请参阅

query()

__init__(other)
参数：:

other – QUrlQuery

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

__init__()

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

另请参阅

setQuery() addQueryItem()

addQueryItem(key, value)#
参数：:

  • key – 字符串

  • value – 字符串

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

备注

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

备注

预期的键和值字符串应该是百分编码形式。

另请参阅

hasQueryItem() queryItemValue()

allQueryItemValues(key[, encoding=QUrl.PrettyDecoded])#
参数：:
返回类型:

字符串列表

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

备注

键应表示为百分编码形式。

另请参阅

queryItemValue() addQueryItem()

clear()#

通过删除当前存储的所有键值对来清除此QUrlQuery对象。如果查询分隔符已更改，此函数将保留它们的更改值。

hasQueryItem(key)#
参数：:

key – 字符串

返回类型:

bool

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

备注

键应表示为百分编码形式。

另请参阅

addQueryItem() queryItemValue()

isEmpty()#
返回类型:

bool

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

另请参阅

setQuery() clear()

__ne__(other)#
参数：:

other – QUrlQuery

返回类型:

bool

如果other与此QUrlQuery不相等，则返回true。否则返回false。

另请参阅

operator==()

__eq__(other)#
参数：:

other – QUrlQuery

返回类型:

bool

如果此对象和 other 对象包含相同的内容，顺序相同，并且使用相同的查询定界符，则返回 true。

query([encoding=QUrl.PrettyDecoded])#
参数：:

encoding – ComponentFormattingOption 的组合

返回类型:

str

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

对于此函数，唯一有歧义的定界符是哈希标记（“#”），因为在URL中，它用于将查询字符串与可能跟随的片段分开。

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

另请参阅

setQuery() setQuery() fragment() Encoding

queryItemValue(key[, encoding=QUrl.PrettyDecoded])#
参数：:
返回类型:

str

从URL中返回与键 key 关联的查询值，使用 encoding 中指定的选项编码返回值。如果未找到键 key，则此函数返回空字符串。如果您需要区分空值和非现有键，则应首先使用 hasQueryItem() 检查键的存在。

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

备注

键应表示为百分编码形式。

另请参阅

addQueryItem() allQueryItemValues() Encoding

queryItems([encoding=QUrl.PrettyDecoded])#
参数：:

encoding – ComponentFormattingOption 的组合

返回类型:

std(pair QString, QString) 列表

使用指定的 encoding 选项来编码元素，返回URL的查询字符串，作为一个键值对的映射。元素的顺序与查询字符串中找到的顺序或使用 setQueryItems() 设置的顺序相同。

另请参阅

setQueryItems() 编码

queryPairDelimiter()#
返回类型:

QChar

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

queryValueDelimiter()#
返回类型:

QChar

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

removeAllQueryItems(key)#
参数：:

key – 字符串

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

备注

键应表示为百分编码形式。

另请参阅

removeQueryItem()

removeQueryItem(key)#
参数：:

key – 字符串

从URL中删除键等于 key 的查询字符串对。如果有多个具有相等键的项，它将删除查询字符串中存在或通过 addQueryItem() 添加的第一个项。

备注

键应表示为百分编码形式。

另请参阅

removeAllQueryItems()

setQuery(queryString)#
参数：:

queryString – str

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

另请参阅

query()

setQueryDelimiters(valueDelimiter, pairDelimiter)#
参数：:

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

query – .list of std.pair QString,QString

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

备注

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

备注

预期键和值将以百分编码形式存在。

另请参阅

queryItems() isEmpty()

swap(other)#
参数：:

other – QUrlQuery

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

toString([encoding=QUrl.PrettyDecoded])#
参数：:

encoding – ComponentFormattingOption 的组合

返回类型:

str

将此 QUrlQuery 对象转换为 QString . 可通过 encoding 指定返回值URL字符串的编码。