En esta página

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

Nota: Todas las funciones de esta clase son reentrantes.

Comparaciones de QJsonValue

CategoríaTipos comparables
igualdadQJsonValue
igualdadQJsonValueConstRef 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)
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:

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`:

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.

ConstanteValorDescripción
QJsonValue::Null0x0Un valor nulo
QJsonValue::Bool0x1Un valor booleano. Utiliza toBool() para convertirlo a un valor booleano.
QJsonValue::Double0x2Un valor numérico. Utiliza ` toDouble()` para convertirlo a un `double`, o ` toInteger()` para convertirlo a un `qint64`.
QJsonValue::String0x3Una cadena. Utiliza toString() para convertirla en un QString.
QJsonValue::Array0x4Un array. Utiliza ` toArray()` para convertirlo a un ` QJsonArray`.
QJsonValue::Object0x5Un objeto. Utiliza ` toObject()` para convertirlo a ` QJsonObject`.
QJsonValue::Undefined0x80El 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 origenTipo 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:

ConstanteDescripción
NullQMetaType::Nullptr
BoolQMetaType::Bool
DoubleQMetaType::Double o QMetaType::LongLong
StringQString
ArrayQVariantList
ObjectQVariantMap
UndefinedQVariant()

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.