QUrlQuery Class
QUrlQueryクラスは、URLのクエリでキーと値のペアを操作する方法を提供します。詳細...
| ヘッダー | #include <QUrlQuery> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake： | QT += core |
- 継承メンバを含む全メンバ一覧
- QUrlQueryは、Input/Output and Networking、Network Programming API、Implicitly Shared Classesに属しています。
このクラスは等価比較可能です。
注意:このクラスの関数はすべてリエントラントです。
パブリック関数
| 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 "をキーとする2つのエントリーを含んでいます。QUrlQueryは、クエリの個々のコンポーネントから、QUrl::setQuery （）で使用するのに適したクエリ文字列を作成するために使用することもできます。
クエリー文字列をパースする最も一般的な方法は、コンストラクタでクエリー文字列を渡して初期化することです。そうでない場合は、setQuery() メソッドを使用して、パースするクエリを設定します。このメソッドは、setQueryDelimiters() 関数を使用して非標準の区切り文字を設定した後に、それを使用してクエリをパースすることもできます。
エンコードされたクエリー文字列は、query() を使って再び取得することができる。これは、内部に格納されているすべての項目を取り出し、区切り文字を使用して文字列をエンコードします。
エンコード
QUrlQuery のすべてのゲッター・メソッドは、query() を含むQUrl::ComponentFormattingOptions 型のオプション・パラメータをサポートしています。QUrl::FullyDecoded を除き、返される値はパーセント符号化された文字列とみなされます。これは、復号化された形式で表現できない値（制御文字やUTF-8に復号化できないバイト列など）があるためです。そのため、パーセント文字は常に"%25 "という文字列で表されます。
QUrlQuery のすべてのセッター・メソッドとhasQueryItem() のようなクエリー・メソッドは、エンコードされた形式のみを取ります。QUrl とは異なり、渡される文字列がデコードされていることを指定するオプションのパラメータはありません。不適切にエンコードされた文字列がセッターやクエリー・メソッドに渡された場合、QUrlQueryは失敗する代わりに回復を試みます。つまり、このクラスのすべての関数は、QUrl::TolerantMode デコード・モードが指定されたかのように文字列引数を解析します。
アプリケーション・コードは、TolerantModeの解析による文字列の修正に依存せず、常に適切なエンコードを保証するように努める必要があります。特に、すべてのユーザー入力は、このクラスの関数に渡される前に、まずQUrl::toPercentEncoding() または同様の関数を使用してパーセントエンコードされなければなりません。
スペースとプラス（"+"）の処理
ウェブ・ブラウザは通常、HTMLのFORM要素にあるスペースをプラス記号（"+"）に、プラス記号をパーセント・エンコードした形（%2B）にエンコードします。しかし、URLに関するインターネットの仕様では、スペースとプラス記号は等価とはみなされません。
そのため、QUrlQueryはスペース文字を "+"にエンコードすることはなく、"+"をスペース文字にデコードすることもありません。代わりに、スペース文字はエンコードされた状態で"%20 "と表示されます。
HTMLフォームのようなエンコーディングをサポートするために、QUrlQueryは"%2B "シーケンスをプラス記号にデコードすることも、プラス記号をエンコードすることもありません。実際、キー、値、クエリ文字列で見つかった"%2B "または "+"シーケンスは、（"%2B "を"%2B "に大文字にすることを除いて）正確に記述されたままになります。
完全なデコード
QUrl::FullyDecoded フォーマットでは、パーセントエンコードされたシーケンスはすべて完全にデコードされ、'%'文字はそれ自身を表すために使用されます。QUrl::FullyDecoded の使用には注意が必要です。データが失われる可能性があるからです。どのようなデータが失われるかについては、QUrl::FullyDecoded のドキュメントを参照のこと。
このフォーマット・モードは、パーセント・エンコーディングが望まれないコンテキストでユーザーに表示されるテキストを扱う場合にのみ使用されるべきです。QUrlQueryのセッターとクエリーメソッドは、対応するQUrl::DecodedMode 構文解析をサポートしていないので、QUrl::FullyDecoded を使用してキーのリストを取得すると、オブジェクトに見つからないキーが生じる可能性があることに注意してください。
非標準の区切り文字
デフォルトでは、QUrlQueryはキーと値を等号（"="）で区切り、キーと値のペアをアンパサンド（"&"）で区切ります。QUrlQuery が解析やクエリの再構築に使用する区切り記号は、setQueryDelimiters() を呼び出すことで変更できます。
非標準の区切り文字は、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)
URL のクエリー文字列の最後にkey =value のペアを追加する。このメソッドは、同じキーを持つ既存のアイテムを上書きしません。
注意: このメソッドは、HTML フォームがそうであるように、スペース (ASCII 0x20) とプラス記号 ("+") を同じものとして扱いません。スペースをプラス記号として表現する必要がある場合は、実際のプラス記号を使用してください。
注意： キー文字列と値文字列は、パーセントエンコード形式であることが期待されます。
hasQueryItem() およびqueryItemValue()も参照 。
QStringList QUrlQuery::allQueryItemValues(const QString &key, QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const
encoding で指定されたオプションを使用して戻り値をエンコードし、URL からkey に等しいキーを持つクエリー文字列値のリストを返します。キーkey が見つからない場合、この関数は空のリストを返します。
注意： キーはパーセントエンコード形式であることが期待される。
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 を返す。
注意: キーがパーセントエンコード形式であることを期待する。
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()、Encodingも参照のこと 。
QString QUrlQuery::queryItemValue(const QString &key, QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const
encoding で指定されたオプションを使用して戻り値をエンコードし、URL からキーkey に関連付けられたクエリー値を返す。キーkey が見つからない場合、この関数は空の文字列を返します。空の値と存在しないキーを区別する必要がある場合は、まずhasQueryItem() を使用してキーの存在を確認する必要があります。
キーkey が複数定義されている場合、この関数は、最初に見つかったものを、クエリ文字列中に存在した順、あるいはaddQueryItem() を使用して追加した順に返します。
注意: キーは、パーセントエンコードされた形式でなければなりません。
addQueryItem()、allQueryItemValues()、Encodingも参照のこと 。
QList<std::pair<QString, QString>> QUrlQuery::queryItems(QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const
URL のクエリー文字列を、encoding で指定されたオプションを使用して項目をエンコードし、キーと値のマップとして返します。要素の順番は、クエリ文字列で見つかったもの、あるいはsetQueryItems() で設定されたものと同じです。
setQueryItems() およびEncodingも参照のこと 。
QChar QUrlQuery::queryPairDelimiter() const
query() でクエリ文字列を再構築する際、あるいはsetQuery() でパースする際に、 キーと値のペアを区切るために使用する文字を返します。
setQueryDelimiters() およびqueryValueDelimiter()も参照 ください。
QChar QUrlQuery::queryValueDelimiter() const
query() でクエリ文字列を再構築する際、あるいはsetQuery() でパースする際に、 キーと値の区切りに使用する文字を返します。
setQueryDelimiters() およびqueryPairDelimiter()も参照 ください。
void QUrlQuery::removeAllQueryItems(const QString &key)
キーがkey に等しいすべてのクエリー文字列ペアをURLから削除する。
注意: キーはパーセントエンコード形式であることが期待されます。
removeQueryItem()も参照 。
void QUrlQuery::removeQueryItem(const QString &key)
キーがkey に等しいクエリー文字列のペアを URL から削除する。キーがkey に等しい項目が複数ある場合、クエリ文字列中に存在するかaddQueryItem() で追加された順に、最初の項目を削除する。
注意: キーは、パーセントエンコード形式であることが期待される。
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）とプラス（"+"）記号を同じものとして扱いません。スペースをプラス記号として表現する必要がある場合は、実際のプラス記号を使用してください。
注意： キーと値はパーセントエンコード形式であることが期待される。
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)
Move-other をこの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 を返す。
© 2025 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.
