QUrlQuery Class
QUrlQuery 类提供了一种操作 URL 查询字符串中键值对的方法。更多内容...
| 标题： | #include <QUrlQuery> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake： | QT += core |
- 所有成员的列表，包括继承的成员
- QUrlQuery 属于“输入/输出与网络”、“网络编程 API”以及“隐式共享类”范畴。
注意：该类中的所有函数均为可重入的。
QUrlQuery 比较
| 类别 | 可比较类型 |
|---|---|
| 相等性 | QUrlQuery |
公共函数
| QUrlQuery() | |
| QUrlQuery(const QString &queryString) | |
| QUrlQuery(const QUrl &url) | |
| QUrlQuery(std::initializer_list<std::pair<QString, QString>> list) | |
| QUrlQuery(const QUrlQuery &other) | |
(since 6.5) | QUrlQuery(QUrlQuery &&other) |
| ~QUrlQuery() | |
| void | addQueryItem(const QString &key, const QString &value) |
| QStringList | allQueryItemValues(const QString &key, QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const |
| void | clear() |
| bool | hasQueryItem(const QString &key) const |
| bool | isEmpty() const |
| QString | query(QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const |
| QString | queryItemValue(const QString &key, QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const |
| QList<std::pair<QString, QString>> | queryItems(QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const |
| QChar | queryPairDelimiter() const |
| QChar | queryValueDelimiter() const |
| void | removeAllQueryItems(const QString &key) |
| void | removeQueryItem(const QString &key) |
| void | setQuery(const QString &queryString) |
| void | setQueryDelimiters(QChar valueDelimiter, QChar pairDelimiter) |
| void | setQueryItems(const QList<std::pair<QString, QString>> &query) |
| void | swap(QUrlQuery &other) |
| QString | toString(QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const |
| QUrlQuery & | operator=(QUrlQuery &&other) |
| QUrlQuery & | operator=(const QUrlQuery &other) |
静态公共成员
| char16_t | defaultQueryPairDelimiter() |
| char16_t | defaultQueryValueDelimiter() |
相关的非成员
| size_t | qHash(const QUrlQuery &key, size_t seed = 0) |
| bool | operator!=(const QUrlQuery &lhs, const QUrlQuery &rhs) |
| bool | operator==(const QUrlQuery &lhs, const QUrlQuery &rhs) |
详细说明
该类用于解析如下所示的 URL 中的查询字符串：
上述此类查询字符串用于在URL中传递选项，通常会被解码为多个键值对。上述示例的列表中将包含两个条目，键分别为“type”和“color”。QUrlQuery 还可以根据查询的各个组成部分，创建一个适合在QUrl::setQuery() 中使用的查询字符串。
解析查询字符串最常见的方式是在构造函数中通过传入查询字符串来初始化它。否则，可以使用 `setQuery()` 方法设置待解析的查询。该方法还可以在使用 `setQueryDelimiters()` 函数设置非标准分隔符后，用于解析包含这些分隔符的查询。
可以通过调用query() 方法再次获取编码后的查询字符串。该方法会提取所有内部存储的项目，并使用已设定的分隔符对字符串进行编码。
编码
QUrlQuery 中的所有获取方法都支持一个可选的QUrl::ComponentFormattingOptions 类型的参数，包括query()，该参数决定了如何对相关数据进行编码。 除了 `QUrl::FullyDecoded` 之外，返回值仍应被视为百分比编码的字符串，因为某些值无法以解码形式表示（如控制字符、无法解码为 UTF-8 的字节序列）。因此，百分号始终由字符串 "%25" 表示。
QUrlQuery 中的所有设置方法以及诸如hasQueryItem() 之类的查询方法均仅接受编码形式。与QUrl 不同，这里没有可选参数来指定传入的字符串已解码。 如果向设置器或查询方法传递了编码不正确的字符串，QUrlQuery 会尝试恢复数据，而不是直接报错。也就是说，该类中的所有函数都会像指定了QUrl::TolerantMode 解码模式一样解析其字符串参数。
应用程序代码应始终确保编码正确，切勿依赖 TolerantMode 解析模式来修复字符串。特别需要注意的是，所有用户输入在传递给本类中的函数之前，都必须先使用QUrl::toPercentEncoding() 或类似函数进行百分比编码。
空格和加号 (“+”) 的处理
Web 浏览器通常会将 HTML FORM 元素中的空格编码为加号（“+”），并将加号编码为其百分比编码形式（%2B）。然而，规范 URL 的互联网标准并不认为空格和加号是等效的。
因此，QUrlQuery 绝不会将空格字符编码为“+”，也不会将“+”解码为空格字符。相反，空格字符将以编码形式“%20”呈现。
为了支持类似 HTML 表单的编码方式，QUrlQuery 也不会将“%2B”序列解码为加号，也不会对加号进行编码。 事实上，在键、值或查询字符串中发现的任何“%2B”或“+”序列都会完全保留原样（将“%2b”转换为“%2B”的大写形式除外）。
完全解码
使用 `QUrl::FullyDecoded ` 格式化时，所有百分比编码序列都将被完全解码，且 '%' 字符将用于表示其本身。应谨慎使用 `QUrl::FullyDecoded `，因为它可能会导致数据丢失。有关可能丢失的数据的信息，请参阅QUrl::FullyDecoded 的文档。
仅当处理向用户展示的文本且不希望使用百分比编码时，才应使用此格式化模式。请注意，QUrlQuery 的设置器（setters）和查询方法（query methods）不支持相应的QUrl::DecodedMode 解析，因此使用QUrl::FullyDecoded 获取键列表可能会导致在对象中找不到这些键。
非标准分隔符
默认情况下，QUrlQuery 使用等号（“=”）将键与值分隔开，并使用“&”符号将键值对相互分隔。可以通过调用setQueryDelimiters() 来更改 QUrlQuery 在解析和重建查询时使用的分隔符。
非标准分隔符应从 RFC 3986 中所称的“子分隔符”中选择。它们包括：
sub-delims = "!" / "$" / "&" / "'" / "(" / ")"
/ "*" / "+" / "," / ";" / "="不支持使用其他字符，否则可能会导致意外行为。QUrlQuery 不会验证您传递的分隔符是否有效。
另请参阅 QUrl 。
成员函数文档
QUrlQuery::QUrlQuery()
构建一个空的 QUrlQuery 对象。随后可以通过调用setQuery() 来设置查询，或者使用addQueryItem() 来添加项目。
另请参阅 setQuery() 和addQueryItem()。
[explicit] QUrlQuery::QUrlQuery(const QString &queryString)
创建一个 QUrlQuery 对象，并使用默认的查询分隔符解析queryString 中的查询字符串。若要使用其他分隔符解析查询字符串，应先通过setQueryDelimiters() 设置这些分隔符，然后使用setQuery() 设置查询字符串。
[explicit] QUrlQuery::QUrlQuery(const QUrl &url)
创建一个 QUrlQuery 对象，并使用默认的查询分隔符解析url URL 中包含的查询字符串。若要使用其他分隔符解析查询字符串，应先通过setQueryDelimiters() 设置这些分隔符，然后使用setQuery() 设置查询。
另请参阅 QUrl::query()。
QUrlQuery::QUrlQuery(std::initializer_list<std::pair<QString, QString>> list)
根据键值对的list 构建一个QUrlQuery对象。
QUrlQuery::QUrlQuery(const QUrlQuery &other)
复制other 中QUrlQuery对象的内容，包括查询分隔符。
[noexcept, since 6.5] QUrlQuery::QUrlQuery(QUrlQuery &&other)
移动other 的QUrlQuery对象中的内容，包括查询分隔符。
该函数于 Qt 6.5 中引入。
[noexcept] QUrlQuery::~QUrlQuery()
销毁此QUrlQuery 对象。
void QUrlQuery::addQueryItem(const QString &key, const QString &value)
将键值对key =value 追加到 URL 查询字符串的末尾。此方法不会覆盖可能已存在的、具有相同键的现有项。
注意： 与 HTML 表单不同，此方法 不会将空格（ASCII 0x20）和加号（"+"）视为相同。如果您需要将空格表示为加号，请使用实际的加号。
注意： 键和值字符串应采用百分比编码形式。如果提供的不当编码输入，该函数会尝试恢复，但这可能会导致数据丢失。有关更多信息，请参阅QUrlQuery#Encoding 。
另请参阅 hasQueryItem() 和queryItemValue()。
QStringList QUrlQuery::allQueryItemValues(const QString &key, QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const
返回一个查询字符串值列表，其中键与 URL 中的 `key ` 相等，并使用 `encoding ` 中指定的选项对返回值进行编码。如果未找到键 `key `，则该函数返回一个空列表。
注意：该 键应为百分比编码形式。如果提供的不当编码的输入，本函数会尝试进行恢复，但这可能会导致数据丢失。有关更多信息，请参阅QUrlQuery#Encoding 。
另请参阅 queryItemValue() 和addQueryItem()。
void QUrlQuery::clear()
清除此QUrlQuery 对象，删除其中当前存储的所有键值对。如果查询分隔符已被修改，此函数将保留其修改后的值。
另请参阅 isEmpty() 和setQueryDelimiters()。
[static constexpr noexcept] char16_t QUrlQuery::defaultQueryPairDelimiter()
返回用于分隔键值对的默认分隔符，即“&”符号。
注意： 在 Qt 6之前 ，此函数返回的是 `QChar`。
另请参阅 setQueryDelimiters()、queryPairDelimiter() 和defaultQueryValueDelimiter()。
[static constexpr noexcept] char16_t QUrlQuery::defaultQueryValueDelimiter()
返回查询中用于分隔键和值的默认字符，即等号（"="）。
注意： 在 Qt 6之前 ，此函数返回QChar 。
另请参阅 setQueryDelimiters()、queryValueDelimiter() 和defaultQueryPairDelimiter()。
bool QUrlQuery::hasQueryItem(const QString &key) const
如果 URL 中存在一个查询字符串键值对，且其键值等于key ，则返回 `true `。
注意：该键 应为百分比编码形式。如果提供的不当编码的输入，本函数会尝试进行恢复，但这可能会导致数据丢失。更多信息请参见QUrlQuery#Encoding 。
另请参阅 addQueryItem() 和queryItemValue()。
bool QUrlQuery::isEmpty() const
如果该QUrlQuery 对象不包含任何键值对（例如在默认构造后或解析空查询字符串后），则返回true 。
QString QUrlQuery::query(QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const
返回一个重建的查询字符串，该字符串由当前存储在此QUrlQuery 对象中的键值对组成，并使用为该对象选择的查询分隔符进行分隔。键和值的编码方式由encoding 参数指定的选项决定。
对于此函数，唯一可能引起歧义的分隔符是井号（"#"），因为在 URL 中，它用于将查询字符串与可能紧随其后的片段分隔开来。
返回字符串中键值对的顺序与原始查询中的顺序完全一致。
另请参阅 setQuery()、QUrl::setQuery()、QUrl::fragment() 以及《编码》章节。
QString QUrlQuery::queryItemValue(const QString &key, QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const
返回 URL 中与键key 关联的查询值，并使用encoding 中指定的选项对返回值进行编码。如果未找到键key ，该函数将返回一个空字符串。若需区分空值与不存在的键，应先使用hasQueryItem() 检查该键是否存在。
如果键key 存在多个定义，则本函数将返回第一个找到的键，其顺序以查询字符串中的出现顺序或通过addQueryItem() 添加的顺序为准。
注意：该键 应采用百分比编码形式。若提供编码不正确的输入，本函数将尝试进行恢复，但这可能会导致数据丢失。更多信息请参阅QUrlQuery#Encoding 。
另请参阅 addQueryItem()、allQueryItemValues() 以及“编码”章节。
QList<std::pair<QString, QString>> QUrlQuery::queryItems(QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const
返回 URL 的查询字符串，形式为键值对映射，并使用encoding 中指定的选项对各项进行编码。元素的顺序与查询字符串中的顺序一致，或与通过setQueryItems() 设置的顺序一致。
另请参阅 setQueryItems() 和编码。
QChar QUrlQuery::queryPairDelimiter() const
返回在query()中重建查询字符串时，或在setQuery()中解析查询字符串时，用于分隔键值对的字符。
另请参阅 setQueryDelimiters() 和queryValueDelimiter()。
QChar QUrlQuery::queryValueDelimiter() const
返回在query()中重建查询字符串时，或在setQuery()中解析查询字符串时，用于分隔键和值的字符。
另请参阅 setQueryDelimiters() 和queryPairDelimiter()。
void QUrlQuery::removeAllQueryItems(const QString &key)
从 URL 中移除所有键值为key 的查询字符串对。
注意：该 键应采用百分比编码形式。如果提供的输入编码不正确，该函数会尝试进行恢复，但这可能会导致数据丢失。有关更多信息，请参阅QUrlQuery#Encoding 。
另请参阅 removeQueryItem()。
void QUrlQuery::removeQueryItem(const QString &key)
从 URL 中移除键值为key 的查询字符串对。如果存在多个键值为key 的项目，则按其在查询字符串中出现的顺序，或按调用addQueryItem() 时添加的顺序，移除第一个项目。
注意：键 应采用百分比编码形式。如果提供的输入编码不正确，该函数会尝试恢复，但可能会导致数据丢失。有关更多信息，请参阅QUrlQuery#Encoding 。
另请参阅 removeAllQueryItems()。
void QUrlQuery::setQuery(const QString &queryString)
解析queryString 中的查询字符串，并将内部项设置为从中获取的值。如果已通过setQueryDelimiters()指定了分隔符，则该函数将使用这些分隔符（而非默认分隔符）来解析字符串。
另请参阅 query()。
void QUrlQuery::setQueryDelimiters(QChar valueDelimiter, QChar pairDelimiter)
设置用于分隔键与值之间，以及 URL 查询字符串中键值对之间的分隔符。默认的值分隔符为 '='，默认的键值对分隔符为 '&'。
valueDelimiter 将用于分隔键和值，pairDelimiter 将用于分隔键值对。当通过query()返回时，查询字符串中键和值的编码表示中出现的任何这些分隔符都会进行百分比编码。
如果将valueDelimiter 设置为','，而pairDelimiter 设置为';'，则上述查询字符串将表示为如下形式：
http://www.example.com/cgi-bin/drawgraph.cgi?type,pie;color,green注意：非标准 分隔符应从 RFC 3986 中所谓的“子分隔符”中选择。它们包括：
sub-delims = "!" / "$" / "&" / "'" / "(" / ")"
/ "*" / "+" / "," / ";" / "="不支持使用其他字符，且可能会导致意外行为。此方法不会验证您传递的分隔符是否有效。
另请参阅 queryValueDelimiter() 和queryPairDelimiter()。
void QUrlQuery::setQueryItems(const QList<std::pair<QString, QString>> &query)
将此QUrlQuery 对象中的项设置为query 。query 中元素的顺序将被保留。
注意： 与HTML表单不同，此方法 不会将空格（ASCII 0x20）和加号（“+”）视为相同。若需将空格表示为加号，请使用实际的加号。
注意： 键和值应采用百分比编码形式。如果输入的编码不正确，该函数会尝试恢复，但这可能会导致数据丢失。有关更多信息，请参阅QUrlQuery#Encoding 。
另请参阅 queryItems() 和isEmpty()。
[noexcept] void QUrlQuery::swap(QUrlQuery &other)
将此 URL 查询实例替换为other 。此操作速度非常快，且绝不会失败。
QString QUrlQuery::toString(QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const
将此QUrlQuery 转换为QString 并返回。可通过encoding 指定返回值的URL字符串编码方式。
[noexcept] QUrlQuery &QUrlQuery::operator=(QUrlQuery &&other)
将other 通过Move操作赋值给此QUrlQuery 实例。
QUrlQuery &QUrlQuery::operator=(const QUrlQuery &other)
复制other QUrlQuery 对象的内容，包括查询分隔符。
相关的非成员
[noexcept] size_t qHash(const QUrlQuery &key, size_t seed = 0)
返回key 的哈希值，并使用seed 作为计算的种子。
[noexcept] bool operator!=(const QUrlQuery &lhs, const QUrlQuery &rhs)
如果QUrlQuery 对象rhs 不等于lhs ，则返回true 。否则，返回false 。
另请参阅 operator==()。
[noexcept] bool operator==(const QUrlQuery &lhs, const QUrlQuery &rhs)
如果QUrlQuery 对象lhs 和rhs 包含相同的内容、按相同的顺序排列，并且使用相同的查询分隔符，则返回true 。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
