En esta página

QUrlQuery Class

La clase QUrlQuery permite manipular pares clave-valor en la consulta de una URL. Más información...

Encabezado: #include <QUrlQuery>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core

Nota: Todas las funciones de esta clase son reentrantes.

Comparaciones de QUrlQuery

CategoríaTipos comparables
igualdadQUrlQuery

Funciones públicas

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)

Miembros públicos estáticos

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)

Descripción detallada

Se utiliza para analizar las cadenas de consulta que se encuentran en direcciones URL como la siguiente:

Ilustración de una URL en la que la parte que aparece después del signo de interrogación está resaltada como cadena de consulta.

Las cadenas de consulta como la anterior se utilizan para transmitir opciones en la URL y, por lo general, se descodifican en varios pares clave-valor. La anterior contendría dos entradas en su lista, con las claves «type» y «color». QUrlQuery también se puede utilizar para crear una cadena de consulta adecuada para su uso en QUrl::setQuery() a partir de los componentes individuales de la consulta.

La forma más habitual de analizar una cadena de consulta es inicializarla en el constructor pasándole la cadena de consulta. De lo contrario, se puede utilizar el método ` setQuery()` para establecer la consulta que se va a analizar. Ese método también se puede utilizar para analizar una consulta con delimitadores no estándar, tras haberlos establecido mediante la función ` setQueryDelimiters()`.

La cadena de consulta codificada se puede recuperar de nuevo mediante query(). Esto tomará todos los elementos almacenados internamente y codificará la cadena utilizando los delimitadores.

Codificación

Todos los métodos de lectura de QUrlQuery admiten un parámetro opcional de tipo QUrl::ComponentFormattingOptions, incluido query(), que determina cómo se codifican los datos en cuestión. Excepto en el caso de ` QUrl::FullyDecoded`, el valor devuelto debe seguir considerándose una cadena codificada con el carácter de porcentaje, ya que hay ciertos valores que no pueden expresarse en forma descodificada (como los caracteres de control o las secuencias de bytes no descodificables a UTF-8). Por ese motivo, el carácter de porcentaje siempre se representa mediante la cadena «%25».

Todos los métodos de configuración y los métodos de consulta, como hasQueryItem() en QUrlQuery, solo admiten formas codificadas. A diferencia de lo que ocurre en QUrl, no hay ningún parámetro opcional para especificar que las cadenas que se pasan están descodificadas. Si se pasan cadenas codificadas incorrectamente a los métodos de asignación o de consulta, QUrlQuery intentará recuperarlas en lugar de dar un error. Es decir, todas las funciones de esta clase analizan sus argumentos de cadena como si se hubiera especificado el modo de decodificación QUrl::TolerantMode.

El código de la aplicación debe procurar garantizar siempre una codificación adecuada y no confiar en que el análisis de TolerantMode corrija las cadenas. En particular, todas las entradas del usuario deben codificarse primero en formato «porcentaje» mediante QUrl::toPercentEncoding() o funciones similares antes de pasarlas a las funciones de esta clase.

Tratamiento de los espacios y del signo más («+»)

Los navegadores web suelen codificar los espacios que se encuentran en los elementos FORM de HTML como un signo más («+») y los signos más como su forma codificada en porcentaje (%2B). Sin embargo, las especificaciones de Internet que rigen las URL no consideran equivalentes los espacios y el carácter más.

Por ese motivo, QUrlQuery nunca codifica el carácter de espacio como «+» y nunca decodifica «+» como un carácter de espacio. En su lugar, los caracteres de espacio se representarán como «%20» en su forma codificada.

Para admitir la codificación propia de los formularios HTML, QUrlQuery tampoco decodifica nunca la secuencia «%2B» en un signo más ni codifica un signo más. De hecho, cualquier secuencia «%2B» o «+» que se encuentre en las claves, los valores o la cadena de consulta se deja tal y como está escrita (excepto por el cambio de mayúsculas de «%2b» a «%2B»).

Decodificación completa

Con el formato « QUrl::FullyDecoded », todas las secuencias codificadas con el signo de porcentaje se descodificarán por completo y el carácter «%» se utilizará para representarse a sí mismo. El formato « QUrl::FullyDecoded » debe utilizarse con precaución, ya que puede provocar la pérdida de datos. Consulta la documentación de QUrl::FullyDecoded para obtener información sobre qué datos pueden perderse.

Este modo de formato solo debe utilizarse cuando se trate de texto presentado al usuario en contextos en los que no se desee la codificación porcentual. Tenga en cuenta que los setters y los métodos de consulta de QUrlQuery no admiten el análisis equivalente de « QUrl::DecodedMode », por lo que el uso de « QUrl::FullyDecoded » para obtener una lista de claves puede dar lugar a que no se encuentren claves en el objeto.

Delimitadores no estándar

Por defecto, QUrlQuery utiliza el signo igual («=») para separar una clave de su valor, y el símbolo «&» para separar los pares clave-valor entre sí. Es posible cambiar los delimitadores que utiliza QUrlQuery para el análisis y la reconstrucción de la consulta llamando a setQueryDelimiters().

Los delimitadores no estándar deben elegirse de entre lo que la RFC 3986 denomina «subdelimitadores». Estos son:

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

No se admite el uso de otros caracteres y puede dar lugar a un comportamiento inesperado. QUrlQuery no comprueba si se ha pasado un delimitador válido.

Véase también QUrl.

Documentación de las funciones miembro

QUrlQuery::QUrlQuery()

Crea un objeto QUrlQuery vacío. Posteriormente, se puede establecer una consulta llamando a setQuery() o se pueden añadir elementos utilizando addQueryItem().

Véanse también setQuery() y addQueryItem().

[explicit] QUrlQuery::QUrlQuery(const QString &queryString)

Crea un objeto `QUrlQuery` y analiza la cadena de consulta ` queryString `, utilizando los delimitadores de consulta predeterminados. Para analizar una cadena de consulta utilizando otros delimitadores, primero debes establecerlos mediante ` setQueryDelimiters()` y, a continuación, configurar la consulta con ` setQuery()`.

[explicit] QUrlQuery::QUrlQuery(const QUrl &url)

Crea un objeto `QUrlQuery` y analiza la cadena de consulta que se encuentra en la URL url, utilizando los delimitadores de consulta predeterminados. Para analizar una cadena de consulta utilizando otros delimitadores, primero debes configurarlos mediante ` setQueryDelimiters()` y, a continuación, establecer la consulta con ` setQuery()`.

Véase también QUrl::query().

QUrlQuery::QUrlQuery(std::initializer_list<std::pair<QString, QString>> list)

Crea un objeto `QUrlQuery` a partir de la lista ` list ` de pares clave-valor.

QUrlQuery::QUrlQuery(const QUrlQuery &other)

Copia el contenido del objeto `QUrlQuery` de ` other `, incluidos los delimitadores de la consulta.

[noexcept, since 6.5] QUrlQuery::QUrlQuery(QUrlQuery &&other)

Mueve el contenido del objeto `QUrlQuery` de ` other `, incluidos los delimitadores de la consulta.

Esta función se introdujo en Qt 6.5.

[noexcept] QUrlQuery::~QUrlQuery()

Elimina este objeto ` QUrlQuery `.

void QUrlQuery::addQueryItem(const QString &key, const QString &value)

Añade el par « key = value » al final de la cadena de consulta de la URL. Este método no sobrescribe los elementos existentes que puedan tener la misma clave.

Nota: Este método no considera que los espacios (ASCII 0x20) y los signos más («+») sean lo mismo, como sí lo hacen los formularios HTML. Si necesitas que los espacios se representen como signos más, utiliza signos más reales.

Nota: Se espera quelas cadenasde clave y valor estén en formato de codificación porcentual. Esta función intentará recuperar los datos si se proporcionan entradas codificadas incorrectamente, pero esto puede provocar una pérdida de datos. Consulta QUrlQuery#Encoding para obtener más información.

Véanse también hasQueryItem() y queryItemValue().

QStringList QUrlQuery::allQueryItemValues(const QString &key, QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const

Devuelve una lista de valores de la cadena de consulta cuya clave sea igual a key de la URL, utilizando las opciones especificadas en encoding para codificar el valor devuelto. Si no se encuentra la clave key, esta función devuelve una lista vacía.

Nota: Se espera quela clave esté en formato de codificación porcentual. Esta función intentará recuperar los datos si se proporciona una entrada codificada incorrectamente, pero ello puede provocar la pérdida de datos. Consulte QUrlQuery#Encoding para obtener más información.

Véanse también queryItemValue() y addQueryItem().

void QUrlQuery::clear()

Borra este objeto ` QUrlQuery ` eliminando todos los pares clave-valor almacenados actualmente. Si se han modificado los delimitadores de consulta, esta función los dejará con sus nuevos valores.

Véase también isEmpty() y setQueryDelimiters().

[static constexpr noexcept] char16_t QUrlQuery::defaultQueryPairDelimiter()

Devuelve el carácter predeterminado para separar los pares clave-valor entre sí: el símbolo «&».

Nota: Antes de Qt 6, esta función devolvía QChar.

Véase también setQueryDelimiters(), queryPairDelimiter() y defaultQueryValueDelimiter().

[static constexpr noexcept] char16_t QUrlQuery::defaultQueryValueDelimiter()

Devuelve el carácter predeterminado para separar las claves de los valores en la consulta: el signo igual («=»).

Nota: Antes de Qt 6, esta función devolvía « QChar ».

Véase también setQueryDelimiters(), queryValueDelimiter() y defaultQueryPairDelimiter().

bool QUrlQuery::hasQueryItem(const QString &key) const

Devuelve « true » si existe un par de la cadena de consulta cuya clave sea igual a « key » en la URL.

Nota: Se espera quela clave esté en formato de codificación porcentual. Esta función intentará recuperar los datos si se proporciona una entrada codificada incorrectamente, pero ello puede provocar una pérdida de datos. Consulta QUrlQuery#Encoding para obtener más información.

Véase también addQueryItem() y queryItemValue().

bool QUrlQuery::isEmpty() const

Devuelve « true » si este objeto « QUrlQuery » no contiene ningún par clave-valor, como ocurre tras una construcción por defecto o tras analizar una cadena de consulta vacía.

Véase también setQuery() y clear().

QString QUrlQuery::query(QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const

Devuelve la cadena de consulta reconstruida, formada a partir de los pares clave-valor almacenados actualmente en este objeto ` QUrlQuery ` y separados por los delimitadores de consulta elegidos para este objeto. Las claves y los valores se codifican utilizando las opciones especificadas por el parámetro ` encoding `.

Para esta función, el único delimitador ambiguo es el símbolo almohadilla («#»), ya que en las URL se utiliza para separar la cadena de consulta del fragmento que puede seguir a continuación.

El orden de los pares clave-valor en la cadena devuelta es exactamente el mismo que en la consulta original.

Véase también setQuery(), QUrl::setQuery(), QUrl::fragment() y Codificación.

QString QUrlQuery::queryItemValue(const QString &key, QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const

Devuelve el valor de la consulta asociado a la clave key de la URL, utilizando las opciones especificadas en encoding para codificar el valor devuelto. Si no se encuentra la clave key, esta función devuelve una cadena vacía. Si necesitas distinguir entre un valor vacío y una clave inexistente, debes comprobar primero la presencia de la clave utilizando hasQueryItem().

Si la clave key está definida varias veces, esta función devolverá la primera que encuentre, en el orden en que aparecieran en la cadena de consulta o se añadieran mediante addQueryItem().

Nota: Se espera quela clave esté en formato de codificación porcentual. Esta función intentará recuperar los datos si se proporciona una entrada codificada incorrectamente, pero ello puede provocar la pérdida de datos. Consulte QUrlQuery#Encoding para obtener más información.

Véase también addQueryItem(), allQueryItemValues() y Codificación.

QList<std::pair<QString, QString>> QUrlQuery::queryItems(QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const

Devuelve la cadena de consulta de la URL, en forma de mapa de claves y valores, utilizando las opciones especificadas en encoding para codificar los elementos. El orden de los elementos es el mismo que el que aparece en la cadena de consulta o el establecido con setQueryItems().

Véase también setQueryItems() y Codificación.

QChar QUrlQuery::queryPairDelimiter() const

Devuelve el carácter utilizado para delimitar los pares clave-valor al reconstruir la cadena de consulta en query() o al analizarla en setQuery().

Véanse también setQueryDelimiters() y queryValueDelimiter().

QChar QUrlQuery::queryValueDelimiter() const

Devuelve el carácter utilizado para delimitar las claves y los valores al reconstruir la cadena de consulta en query() o al analizarla en setQuery().

Véanse también setQueryDelimiters() y queryPairDelimiter().

void QUrlQuery::removeAllQueryItems(const QString &key)

Elimina de la URL todos los pares de la cadena de consulta cuya clave sea igual a « key ».

Nota: Se espera quela clave esté en formato codificado en porcentaje. Esta función intentará recuperar los datos si se proporciona una entrada codificada incorrectamente, pero ello puede provocar la pérdida de datos. Consulte QUrlQuery#Encoding para obtener más información.

Véase también removeQueryItem().

void QUrlQuery::removeQueryItem(const QString &key)

Elimina de la URL el par de la cadena de consulta cuya clave sea igual a key. Si hay varios elementos con una clave igual a key, elimina el primero según el orden en que aparecieran en la cadena de consulta o se añadieran con addQueryItem().

Nota: Se espera quela clave esté en formato de codificación porcentual. Esta función intentará recuperar los datos si se proporciona una entrada codificada incorrectamente, pero esto puede provocar la pérdida de datos. Consulte QUrlQuery#Encoding para obtener más información.

Véase también removeAllQueryItems().

void QUrlQuery::setQuery(const QString &queryString)

Analiza la cadena de consulta de queryString y asigna a los elementos internos los valores que allí se encuentran. Si se han especificado delimitadores con setQueryDelimiters(), esta función los utilizará en lugar de los delimitadores predeterminados para analizar la cadena.

Véase también query().

void QUrlQuery::setQueryDelimiters(QChar valueDelimiter, QChar pairDelimiter)

Establece los caracteres utilizados para delimitar las claves y los valores, así como los pares clave-valor en la cadena de consulta de la URL. El delimitador predeterminado para los valores es «=» y el delimitador predeterminado para los pares es «&».

Ilustración de una URL en la que la parte que aparece después del signo de interrogación está resaltada como cadena de consulta.

valueDelimiter se utilizará para separar las claves de los valores, y pairDelimiter se utilizará para separar los pares clave-valor. Cualquier aparición de estos caracteres delimitadores en la representación codificada de las claves y los valores de la cadena de consulta se codifica con el símbolo de porcentaje cuando se devuelve en query().

Si valueDelimiter se establece en «,» y pairDelimiter en «;», la cadena de consulta anterior se representaría así:

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

Nota: Los delimitadoresno estándar deben elegirse de entre lo que la RFC 3986 denomina «subdelimitadores». Estos son:

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

No se admite el uso de otros caracteres y puede dar lugar a un comportamiento inesperado. Este método no comprueba si se ha pasado un delimitador válido.

Véanse también queryValueDelimiter() y queryPairDelimiter().

void QUrlQuery::setQueryItems(const QList<std::pair<QString, QString>> &query)

Establece los elementos de este objeto ` QUrlQuery ` como ` query`. Se conserva el orden de los elementos en ` query `.

Nota: Este método no trata los espacios (ASCII 0x20) y los signos más («+») como si fueran lo mismo, tal y como hacen los formularios HTML. Si necesitas que los espacios se representen como signos más, utiliza signos más reales.

Nota: Se espera quelas claves y los valores estén en formato de codificación porcentual. Esta función intentará recuperar los datos si se proporcionan entradas codificadas incorrectamente, pero eso puede provocar una pérdida de datos. Consulta QUrlQuery#Encoding para obtener más información.

Véase también queryItems() y isEmpty().

[noexcept] void QUrlQuery::swap(QUrlQuery &other)

Sustituye esta instancia de consulta de URL por other. Esta operación es muy rápida y nunca falla.

QString QUrlQuery::toString(QUrl::ComponentFormattingOptions encoding = QUrl::PrettyDecoded) const

Devuelve este objeto ` QUrlQuery ` como un ` QString`. Se puede utilizar ` encoding ` para especificar la codificación de la cadena URL del valor devuelto.

[noexcept] QUrlQuery &QUrlQuery::operator=(QUrlQuery &&other)

Asigna « other » a esta instancia de « QUrlQuery ». ». ». ». ». ». ». ». ». ». ». ». ». ». ». ». ». ». ». ». ». ». ». ». ».xml-ph-0001@dee

QUrlQuery &QUrlQuery::operator=(const QUrlQuery &other)

Copia el contenido del objeto ` other ` ` QUrlQuery `, incluidos los delimitadores de consulta.

Elementos no miembros relacionados

[noexcept] size_t qHash(const QUrlQuery &key, size_t seed = 0)

Devuelve el valor hash de key, utilizando seed como semilla para el cálculo.

[noexcept] bool operator!=(const QUrlQuery &lhs, const QUrlQuery &rhs)

Devuelve « true » si el objeto « QUrlQuery » rhs no es igual a lhs. En caso contrario, devuelve « false ».

Véase también operator==().

[noexcept] bool operator==(const QUrlQuery &lhs, const QUrlQuery &rhs)

Devuelve « true » si los objetos « QUrlQuery », « lhs » y « rhs » contienen el mismo contenido, en el mismo orden, y utilizan los mismos delimitadores de consulta.

© 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.