QJsonValue Class
La clase QJsonValue encapsula un valor en formato JSON. Más información...
| Encabezado: | #include <QJsonValue> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
- Lista de todos los miembros, incluidos los miembros heredados
- QJsonValue forma parte del soporte para JSON en Qt y de las clases compartidas implícitamente.
Nota: Todas las funciones de esta clase son reentrantes.
Comparaciones de QJsonValue
| Categoría | Tipos comparables |
|---|---|
| igualdad | QJsonValue |
| igualdad | QJsonValueConstRef y QJsonValueRef. |
Tipos públicos
(since 6.9) | JsonFormat |
| enum | Type { Null, Bool, Double, String, Array, …, Undefined } |
Funciones públicas
| QJsonValue(QJsonValue::Type type = Null) | |
| QJsonValue(QLatin1StringView s) | |
| QJsonValue(bool b) | |
| QJsonValue(const QJsonArray &a) | |
| QJsonValue(const QJsonObject &o) | |
| QJsonValue(const QString &s) | |
| QJsonValue(const char *s) | |
| QJsonValue(double v) | |
(since 6.3) | QJsonValue(QJsonArray &&a) |
(since 6.3) | QJsonValue(QJsonObject &&o) |
| QJsonValue(int v) | |
| QJsonValue(qint64 v) | |
| QJsonValue(const QJsonValue &other) | |
| QJsonValue(QJsonValue &&other) | |
| ~QJsonValue() | |
| bool | isArray() const |
| bool | isBool() const |
| bool | isDouble() const |
| bool | isNull() const |
| bool | isObject() const |
| bool | isString() const |
| bool | isUndefined() const |
| void | swap(QJsonValue &other) |
| QJsonArray | toArray(const QJsonArray &defaultValue) const |
| QJsonArray | toArray() const |
| bool | toBool(bool defaultValue = false) const |
| double | toDouble(double defaultValue = 0) const |
| int | toInt(int defaultValue = 0) const |
(since 6.0) qint64 | toInteger(qint64 defaultValue = 0) const |
(since 6.9) QByteArray | toJson(QJsonValue::JsonFormat format = JsonFormat::Indented) const |
| QJsonObject | toObject(const QJsonObject &defaultValue) const |
| QJsonObject | toObject() const |
| QString | toString() const |
| QString | toString(const QString &defaultValue) const |
(since 6.10) QAnyStringView | toStringView(QAnyStringView defaultValue = {}) const |
| QVariant | toVariant() const |
| QJsonValue::Type | type() const |
| QJsonValue & | operator=(QJsonValue &&other) |
| QJsonValue & | operator=(const QJsonValue &other) |
| const QJsonValue | operator[](const QString &key) const |
| const QJsonValue | operator[](qsizetype i) const |
| const QJsonValue | operator[](QLatin1StringView key) const |
| const QJsonValue | operator[](QStringView key) const |
Miembros públicos estáticos
(since 6.9) QJsonValue | fromJson(QByteArrayView json, QJsonParseError *error = nullptr) |
| QJsonValue | fromVariant(const QVariant &variant) |
Elementos no miembros relacionados
| bool | operator!=(const QJsonValue &lhs, const QJsonValue &rhs) |
| bool | operator==(const QJsonValue &lhs, const QJsonValue &rhs) |
Descripción detallada
Un valor en JSON puede ser de uno de estos 6 tipos básicos:
JSON es un formato para almacenar datos estructurados. Cuenta con seis tipos de datos básicos:
- bool QJsonValue::Bool
- double QJsonValue::Double
- string QJsonValue::String
- array QJsonValue::Array
- object QJsonValue::Object
- null QJsonValue::Null
Un valor puede representar cualquiera de los tipos de datos anteriores. Además, QJsonValue cuenta con un indicador especial para representar valores indefinidos. Esto se puede consultar mediante ` isUndefined()`.
El tipo del valor se puede consultar mediante ` type()` o mediante accesores como ` isBool()`, ` isString()`, etc. Del mismo modo, el valor se puede convertir al tipo almacenado en él utilizando ` toBool()`, ` toString()`, etc.
Los valores están estrictamente tipados internamente y, a diferencia de QVariant, no intentarán realizar ninguna conversión de tipo implícita. Esto implica que, al convertir a un tipo que no esté almacenado en el valor, se devolverá un valor de retorno construido por defecto.
QJsonValueRef
QJsonValueRef es una clase auxiliar para QJsonArray y QJsonObject. Cuando se obtiene un objeto de tipo QJsonValueRef, se puede utilizar como si fuera una referencia a un QJsonValue. Si se le asigna un valor, la asignación se aplicará al elemento de QJsonArray o QJsonObject del que se obtuvo la referencia.
Los siguientes métodos devuelven un ` QJsonValueRef`:
- QJsonArray::operator[](qsizetype i)
- QJsonObject::operator[](const QString & key) const
Véase también «Compatibilidad con JSON en Qt » y «Guardar y cargar una partida».
Documentación sobre tipos de miembros
[alias, since 6.9] QJsonValue::JsonFormat
Es lo mismo que « QJsonDocument::JsonFormat ».
Este typedef se introdujo en Qt 6.9.
enum QJsonValue::Type
Esta enumeración describe el tipo del valor JSON.
| Constante | Valor | Descripción |
|---|---|---|
QJsonValue::Null | 0x0 | Un valor nulo |
QJsonValue::Bool | 0x1 | Un valor booleano. Utiliza toBool() para convertirlo a un valor booleano. |
QJsonValue::Double | 0x2 | Un valor numérico. Utiliza ` toDouble()` para convertirlo a un `double`, o ` toInteger()` para convertirlo a un `qint64`. |
QJsonValue::String | 0x3 | Una cadena. Utiliza toString() para convertirla en un QString. |
QJsonValue::Array | 0x4 | Un array. Utiliza ` toArray()` para convertirlo a un ` QJsonArray`. |
QJsonValue::Object | 0x5 | Un objeto. Utiliza ` toObject()` para convertirlo a ` QJsonObject`. |
QJsonValue::Undefined | 0x80 | El valor no está definido. Suele devolverse como condición de error al intentar leer un valor fuera de los límites de un array o una clave inexistente en un objeto. |
Documentación de funciones de miembro
QJsonValue::QJsonValue(QJsonValue::Type type = Null)
Crea un objeto `QJsonValue` de tipo ` type`.
Por defecto, se crea un valor nulo.
QJsonValue::QJsonValue(QLatin1StringView s)
Crea un valor de tipo String con la cadena en codificación Latin-1 tal y como la interpreta s.
QJsonValue::QJsonValue(bool b)
Crea un valor de tipo Bool, con el valor « b ».
QJsonValue::QJsonValue(const QJsonArray &a)
Crea un valor de tipo Array, con el valor « a ».
QJsonValue::QJsonValue(const QJsonObject &o)
Crea un valor de tipo Object, con el valor « o ».
QJsonValue::QJsonValue(const QString &s)
Crea un valor de tipo String, con el valor « s ».
QJsonValue::QJsonValue(const char *s)
Crea un valor de tipo String con el valor « s », suponiendo que la entrada está codificada en UTF-8.
Puedes desactivar este constructor definiendo ` QT_NO_CAST_FROM_ASCII ` al compilar tus aplicaciones.
QJsonValue::QJsonValue(double v)
Crea un valor de tipo Double con el valor « v ».
[noexcept, since 6.3] QJsonValue::QJsonValue(QJsonArray &&a)
Esta es una función sobrecargada.
Esta función se introdujo en Qt 6.3.
[noexcept, since 6.3] QJsonValue::QJsonValue(QJsonObject &&o)
Esta es una función sobrecargada.
Esta función se introdujo en Qt 6.3.
QJsonValue::QJsonValue(int v)
Crea un valor de tipo Double con el valor « v ».
Se trata de una función sobrecargada.
QJsonValue::QJsonValue(qint64 v)
Crea un valor de tipo Double, con el valor v.
Este valor se almacena internamente como un entero de 64 bits, por lo que conserva toda su precisión siempre que se recupere mediante ` toInteger()`. Sin embargo, si se recupera su valor mediante ` toDouble()`, se perderá precisión a menos que el valor se encuentre entre ±2^53.
Se trata de una función sobrecargada.
Véanse también toInteger() y toDouble().
[noexcept] QJsonValue::QJsonValue(const QJsonValue &other)
Crea una copia de other.
[noexcept] QJsonValue::QJsonValue(QJsonValue &&other)
Crea un objeto `QJsonValue` a partir de ` other`.
[noexcept] QJsonValue::~QJsonValue()
Destruye el valor.
[static, since 6.9] QJsonValue QJsonValue::fromJson(QByteArrayView json, QJsonParseError *error = nullptr)
Analiza json como un valor JSON codificado en UTF-8 y crea un QJsonValue a partir de él.
Devuelve un objeto ` QJsonValue ` válido si el análisis se realiza correctamente. Si falla, el valor devuelto será ` undefined`, y la variable opcional ` error ` contendrá más detalles sobre el error.
Esta función se introdujo en Qt 6.9.
Véase también QJsonParseError, isUndefined() y toJson().
[static] QJsonValue QJsonValue::fromVariant(const QVariant &variant)
Convierte un objeto ` variant ` en un objeto ` QJsonValue ` y lo devuelve.
La conversión transformará los tipos de « QVariant » de la siguiente manera:
| Tipo de origen | Tipo de destino |
|---|---|
| QJsonValue::Null | |
| QJsonValue::Bool | |
| QJsonValue::Double | |
| QJsonValue::String | |
| QJsonValue::Array | |
| QJsonValue::Object | |
| QJsonValue::String. La conversión utilizará ` QUrl::toString()` con el indicador ` QUrl::FullyEncoded`, con el fin de garantizar la máxima compatibilidad al analizar la URL | |
| QJsonValue::String. A partir de Qt 5.11, la cadena resultante no incluirá llaves | |
| Sea cual sea el tipo que devuelva QCborValue::toJsonValue(). | |
| QJsonValue::Array. Consulte QCborValue::toJsonValue() para conocer las restricciones de conversión. | |
| QJsonValue::Map. Consulta QCborValue::toJsonValue() para conocer las restricciones de conversión y la «conversión a cadena» de las claves del mapa. |
Pérdida de información y otros tipos
QVariant pueden contener más información de la que se puede representar en JSON. Si el ` QVariant ` no es uno de los tipos anteriores, la conversión no está garantizada y está sujeta a cambios en futuras versiones de Qt, tal y como ocurrió con el tipo UUID. El código debe procurar no utilizar ningún otro tipo que no sea uno de los enumerados anteriormente.
Si QVariant::isNull() devuelve true, se devuelve un QJsonValue nulo o se inserta en la lista u objeto, independientemente del tipo que contenga QVariant. Tenga en cuenta que el cambio de comportamiento en Qt 6.0 que afecta a QVariant::isNull() también afecta a esta función.
Un valor de coma flotante que sea infinito o NaN se convertirá en un valor JSON nulo. Desde Qt 6.0, QJsonValue puede almacenar toda la precisión de cualquier entero con signo de 64 bits sin pérdida, pero en versiones anteriores los valores fuera del rango de ±2^53 pueden perder precisión. Los valores sin signo de 64 bits mayores o iguales a 2^63 perderán precisión o se convertirán en valores negativos, por lo que debe evitarse el uso de ` QMetaType::ULongLong `.
Para otros tipos no mencionados anteriormente, se intentará una conversión a cadena, normalmente —aunque no siempre— llamando a ` QVariant::toString()`. Si la conversión falla, el valor se sustituye por un valor JSON nulo. Ten en cuenta que QVariant::toString() también conlleva pérdida de información para la mayoría de los tipos. Por ejemplo, si el QVariant pasado representa datos sin procesar de una matriz de bytes, se recomienda codificarlo previamente a Base64 (u otra codificación sin pérdida); de lo contrario, se utilizará una conversión con pérdida mediante QString::fromUtf8().
Tenga en cuenta que las conversiones realizadas mediante QVariant::toString() están sujetas a cambios en cualquier momento. Tanto QVariant como QJsonValue podrían ampliarse en el futuro para admitir más tipos, lo que supondría un cambio en la forma en que esta función realiza las conversiones.
Véase también toVariant() y QCborValue::fromVariant().
bool QJsonValue::isArray() const
Devuelve « true » si el valor contiene una matriz.
Véase también toArray().
bool QJsonValue::isBool() const
Devuelve « true » si el valor contiene un valor booleano.
Véase también toBool().
bool QJsonValue::isDouble() const
Devuelve ` true ` si el valor contiene un número de tipo `double`.
Véase también toDouble().
bool QJsonValue::isNull() const
Devuelve « true » si el valor es nulo.
bool QJsonValue::isObject() const
Devuelve « true » si el valor contiene un objeto.
Véase también toObject().
bool QJsonValue::isString() const
Devuelve « true » si el valor contiene una cadena.
Véase también toString().
bool QJsonValue::isUndefined() const
Devuelve « true » si el valor no está definido. Esto puede ocurrir en determinados casos de error, como, por ejemplo, al acceder a una clave que no existe en un « QJsonObject ».
[noexcept] void QJsonValue::swap(QJsonValue &other)
Intercambia este valor con other. Esta operación es muy rápida y nunca falla.
QJsonArray QJsonValue::toArray(const QJsonArray &defaultValue) const
Convierte el valor en una matriz y lo devuelve.
Si type() no es un array, se devolverá el valor de defaultValue.
QJsonArray QJsonValue::toArray() const
Convierte el valor en una matriz y lo devuelve.
Si type() no es un Array, se devolverá un QJsonArray().
Esta es una función sobrecargada.
bool QJsonValue::toBool(bool defaultValue = false) const
Convierte el valor en un valor booleano y lo devuelve.
Si type() no es de tipo bool, se devolverá el valor « defaultValue ».
double QJsonValue::toDouble(double defaultValue = 0) const
Convierte el valor a un tipo «double» y lo devuelve.
Si type() no es de tipo «Double», se devolverá el valor defaultValue.
int QJsonValue::toInt(int defaultValue = 0) const
Convierte el valor en un entero y lo devuelve.
Si type() no es de tipo «Double» o el valor no es un número entero, se devolverá el error « defaultValue ».
[since 6.0] qint64 QJsonValue::toInteger(qint64 defaultValue = 0) const
Convierte el valor en un entero y lo devuelve.
Si type() no es de tipo Double o el valor no es un número entero representable como qint64, se devolverá el error « defaultValue ».
Esta función se introdujo en Qt 6.0.
[since 6.9] QByteArray QJsonValue::toJson(QJsonValue::JsonFormat format = JsonFormat::Indented) const
Convierte el objeto ` QJsonValue ` en un valor JSON codificado en UTF-8 en el objeto ` format` facilitado.
Esta función se introdujo en Qt 6.9.
Véase también fromJson() y JsonFormat.
QJsonObject QJsonValue::toObject(const QJsonObject &defaultValue) const
Convierte el valor en un objeto y lo devuelve.
Si type() no es un objeto, se devolverá el objeto defaultValue.
QJsonObject QJsonValue::toObject() const
Convierte el valor en un objeto y lo devuelve.
Si type() no es un objeto, se devolverá QJsonObject().
Esta es una función sobrecargada.
QString QJsonValue::toString() const
Convierte el valor en un ` QString ` y lo devuelve.
Si type() no es una cadena, se devolverá un valor nulo QString.
Véase también ` QString::isNull()`.
QString QJsonValue::toString(const QString &defaultValue) const
Convierte el valor en un objeto « QString » y lo devuelve.
Si type() no es una cadena, se devolverá el valor de « defaultValue ».
Véase también toStringView().
[since 6.10] QAnyStringView QJsonValue::toStringView(QAnyStringView defaultValue = {}) const
Devuelve el valor de cadena almacenado en este QJsonValue, si es de tipo string. En caso contrario, devuelve defaultValue. Dado que QJsonValue almacena cadenas en US-ASCII, UTF-8 o UTF-16, el QAnyStringView devuelto puede estar en cualquiera de estas codificaciones.
Esta función no asigna memoria. El valor devuelto es válido hasta la siguiente llamada a una función miembro no const de este objeto. Si este objeto sale del ámbito, el valor devuelto es válido hasta la siguiente llamada a una función miembro no const del objeto JSON padre o del array.
Esta función se introdujo en Qt 6.10.
Véase también toString().
QVariant QJsonValue::toVariant() const
Convierte el valor a un tipo « QVariant » ().
Los tipos de « QJsonValue » se convertirán de la siguiente manera:
| Constante | Descripción |
|---|---|
Null | QMetaType::Nullptr |
Bool | QMetaType::Bool |
Double | QMetaType::Double o QMetaType::LongLong |
String | QString |
Array | QVariantList |
Object | QVariantMap |
Undefined | QVariant() |
Véase también fromVariant().
QJsonValue::Type QJsonValue::type() const
Devuelve el tipo del valor.
Véase también QJsonValue::Type.
[noexcept] QJsonValue &QJsonValue::operator=(QJsonValue &&other)
La instrucción «Move» asigna a ` other ` este valor.
[noexcept] QJsonValue &QJsonValue::operator=(const QJsonValue &other)
Asigna a este objeto el valor almacenado en ` other `.
const QJsonValue QJsonValue::operator[](const QString &key) const
Devuelve un objeto ` QJsonValue ` que representa el valor de la clave ` key`.
Equivale a llamar a toObject().value(key).
El objeto ` QJsonValue ` devuelto es ` QJsonValue::Undefined ` si la clave no existe o si ` isObject()` es falso.
Véase también ` QJsonValue`, ` QJsonValue::isUndefined()` y ` QJsonObject`.
const QJsonValue QJsonValue::operator[](qsizetype i) const
Devuelve un objeto ` QJsonValue ` que representa el valor correspondiente al índice ` i`.
Equivale a llamar a ` toArray()`.at(i).
El objeto ` QJsonValue ` devuelto es ` QJsonValue::Undefined` si ` i ` está fuera de límites o si ` isArray()` es falso.
Véase también QJsonValue, QJsonValue::isUndefined() y QJsonArray.
const QJsonValue QJsonValue::operator[](QLatin1StringView key) const
Esta es una función sobrecargada.
const QJsonValue QJsonValue::operator[](QStringView key) const
Esta es una función sobrecargada.
Elementos relacionados que no son miembros
[noexcept] bool operator!=(const QJsonValue &lhs, const QJsonValue &rhs)
Devuelve « true » si el valor de « lhs » no es igual al valor de « rhs »; en caso contrario, devuelve « false ».
[noexcept] bool operator==(const QJsonValue &lhs, const QJsonValue &rhs)
Devuelve « true » si el valor de « lhs » es igual al valor de « rhs »; en caso contrario, devuelve « false ».
© 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.