Conversión de tipos de datos entre QML y C++
Cuando se intercambian valores de datos entre QML y C++, el motor de QML los convierte para que tengan los tipos de datos correctos, según corresponda para su uso en QML o C++. Para ello, es necesario que los datos intercambiados sean de un tipo que el motor pueda reconocer.
El motor de Qml ofrece compatibilidad integrada con un gran número de tipos de datos de Qt C++. Además, los tipos de C++ personalizados pueden registrarse en el sistema de tipos de Qml para que el motor pueda utilizarlos.
Para obtener más información sobre C++ y los diferentes métodos de integración con QML, consulta la página de descripción general de la integración entre C++ y QML.
En esta página se describen los tipos de datos compatibles con el motor QML y cómo se convierten entre QML y C++.
Propiedad de los datos
Cuando los datos se transfieren de C++ a QML, la propiedad de los datos siempre recae en C++. La excepción a esta regla se da cuando se devuelve un objeto ` QObject ` a partir de una llamada explícita a un método de C++: en este caso, el motor de QML asume la propiedad del objeto, a menos que se haya establecido explícitamente que la propiedad del objeto permanezca en C++ mediante la invocación de ` QQmlEngine::setObjectOwnership()` con `QQmlEngine::CppOwnership` especificado.
Además, el motor QML respeta la semántica habitual de propiedad de los padres de los objetos Qt C++ de tipo « QObject », y nunca eliminará una instancia de ` QObject ` que tenga un padre.
Tipos de datos básicos de Qt
Por defecto, QML reconoce los siguientes tipos de datos de Qt, que se convierten automáticamente al tipo de valor Qml correspondiente cuando se pasan de C++ a Qml y viceversa:
| Tipo de Qt | Tipo de valor de QML |
| bool | bool |
| unsigned int, int | int |
| double | double |
| float, qreal | real |
| QString | string |
| QUrl | url |
| QColor | color |
| QFont | font |
| QDateTime | date |
| QPoint, QPointF | point |
| QSize, QSizeF | size |
| QRect, QRectF | rect |
| QMatrix4x4 | matrix4x4 |
| QQuaternion | quaternion |
| QVector2D, QVector3D, QVector4D | vector2d, vector3d, vector4d |
Nota: Las clases proporcionadas por el Qt GUI módulo, como QColor, QFont, QQuaternion y QMatrix4x4, solo están disponibles desde QML cuando se incluye el Qt Quick se incluye el módulo.
Para mayor comodidad, muchos de estos tipos pueden especificarse en QML mediante valores de cadena o mediante un método relacionado proporcionado por el objeto QtQml::Qt. Por ejemplo, la propiedad Image::sourceSize es de tipo size (que se traduce automáticamente al tipo QSize ) y puede especificarse mediante un valor de cadena con el formato «widthxheight», o mediante la función Qt.size():
Consulta la documentación de cada tipo concreto en «Tipos de valor de QML» para obtener más información.
Tipos derivados de QObject
Cualquier clase derivada de ` QObject` puede utilizarse como tipo para el intercambio de datos entre QML y C++, siempre que la clase se haya registrado en el sistema de tipos de QML.
El motor permite el registro tanto de tipos instanciables como de tipos no instanciables. Una vez que una clase se ha registrado como tipo de QML, puede utilizarse como tipo de datos para el intercambio de datos entre QML y C++. Consulte «Registro de tipos de C++ en el sistema de tipos de QML» para obtener más detalles sobre el registro de tipos.
Conversión entre tipos de Qt y JavaScript
El motor de QML cuenta con soporte integrado para convertir una serie de tipos de Qt a tipos de JavaScript relacionados, y viceversa, al transferir datos entre QML y C++. Esto permite utilizar estos tipos y recibirlos en C++ o JavaScript sin necesidad de implementar tipos personalizados que proporcionen acceso a los valores de los datos y a sus atributos.
(Ten en cuenta que el entorno de JavaScript en QML modifica los prototipos de los objetos nativos de JavaScript, incluidos los de String, Date y Number, para proporcionar funcionalidades adicionales. Consulta el apartado «Entorno de JavaScript» para obtener más detalles.)
QVariantList y QVariantMap a tipos similares a las matrices y a los objetos de JavaScript
El motor de QML proporciona conversión automática de tipos entre QVariantList y las estructuras similares a matrices de JavaScript, así como entre QVariantMap y los objetos de JavaScript.
Un «array-like», en términos de ECMAScript, es un objeto que se utiliza como una matriz. Los «array-likes» generados mediante la conversión de QVariantList (y otros contenedores secuenciales de C++) no solo son eso, sino que también ofrecen los métodos habituales de las matrices y sincronizan automáticamente la propiedad «length ». Se pueden utilizar igual que las matrices de JavaScript para cualquier fin práctico. Sin embargo, el método ` Array.isArray()` sigue devolviendo `false` para ellos.
Por ejemplo, la función definida a continuación en QML espera dos argumentos, un array y un objeto, e imprime su contenido utilizando la sintaxis estándar de JavaScript para acceder a los elementos de un array y de un objeto. El código C++ que aparece a continuación llama a esta función, pasando un ` QVariantList ` y un ` QVariantMap`, que se convierten automáticamente en valores de tipo «array-like» y de objeto de JavaScript, respectivamente:
| QML | |
| C++ | |
Esto genera una salida similar a la siguiente:
Array item: 10
Array item: #00ff00
Array item: bottles
Object item: language = QML
Object item: released = Tue Sep 21 2010 00:00:00 GMT+1000 (EST)Del mismo modo, si un tipo de C++ utiliza un tipo ` QVariantList ` o ` QVariantMap ` para el tipo de una propiedad o el parámetro de un método, el valor se puede crear como un array u objeto de JavaScript en QML, y se convierte automáticamente en un ` QVariantList ` o ` QVariantMap ` cuando se pasa a C++.
Desde Qt 6.5, las propiedades « QVariantList » de tipos de C++ pueden modificarse directamente mediante código QML. Desde Qt 6.9, las propiedades « QVariantMap » de tipos de C++ pueden modificarse directamente mediante código QML.
QDateTime a fecha de JavaScript
El motor de QML proporciona una conversión automática de tipos entre valores de « QDateTime » y objetos « Date » de JavaScript.
Por ejemplo, la función definida en QML a continuación espera un objeto ` Date ` de JavaScript y, además, devuelve un nuevo objeto ` Date ` con la fecha y la hora actuales. El código C++ que se muestra a continuación llama a esta función, pasando un valor ` QDateTime ` que el motor convierte automáticamente en un objeto ` Date ` al pasarlo a la función ` readDate() `. A su vez, la función `readDate()` devuelve un objeto ` Date ` que se convierte automáticamente en un valor ` QDateTime ` al recibirse en C++:
| QML | |
| C++ | |
Del mismo modo, si un tipo de C++ utiliza un objeto ` QDateTime ` como tipo de propiedad o parámetro de método, el valor se puede crear en QML como un objeto ` Date ` de JavaScript y se convierte automáticamente en un valor ` QDateTime ` cuando se pasa a C++.
Nota: Ten en cuenta la diferencia en la numeración de los meses: en JavaScript, enero se numera como 0 y diciembre como 11, lo que supone una diferencia de un en la numeración respecto a Qt, donde enero se numera como 1 y diciembre como 12.
Nota: Al utilizar una cadena en JavaScript como valor de un objeto ` Date `, ten en cuenta que una cadena sin campos de hora (es decir, una fecha simple) se interpreta como el inicio UTC del día en cuestión, a diferencia de ` new Date(y, m, d) `, que utiliza el inicio del día en hora local. La mayoría de las demás formas de construir un objeto ` Date ` en JavaScript producen una hora local, a menos que se utilicen métodos que incluyan «UTC» en su nombre. Si tu programa se ejecuta en una zona situada detrás de UTC (nominalmente al oeste del meridiano de Greenwich), el uso de una cadena que contenga solo la fecha dará lugar a un objeto ` Date ` cuyo ` getDate() ` será uno menos que el número de día de tu cadena; normalmente tendrá un valor elevado para ` getHours()`. Las variantes en UTC de estos métodos, getUTCDate() y getUTCHours(), darán los resultados esperados para dichos objetos Date. Véase también la siguiente sección.
QDate y Date de JavaScript
El motor QML realiza automáticamente la conversión entre « QDate » y el tipo « Date » de JavaScript representando la fecha mediante el inicio UTC de su día. Una fecha se asigna de nuevo a « QDate » mediante « QDateTime », seleccionando su método « date()» y utilizando el formato de hora local de la fecha, a menos que el formato UTC coincida con el inicio del día siguiente, en cuyo caso se utiliza el formato UTC.
Este sistema, ligeramente peculiar, es una solución alternativa al hecho de que, en JavaScript, la construcción de un objeto ` Date ` a partir de una cadena que solo contiene una fecha utiliza el inicio del día en UTC, mientras que ` new Date(y, m, d) ` utiliza el inicio de la fecha indicada en hora local, tal y como se explica en una nota al final de la sección anterior.
Como resultado, cuando una propiedad o parámetro de tipo ` QDate ` se expone a QML, hay que tener cuidado al leer su valor: los métodos ` Date.getUTCFullYear()`, ` Date.getUTCMonth() ` y ` Date.getUTCDate() ` tienen más probabilidades de ofrecer los resultados que esperan los usuarios que los métodos correspondientes que no incluyen «UTC» en sus nombres.
Por lo tanto, suele ser más fiable utilizar una propiedad « QDateTime ». Esto permite controlar, en el lado de QDateTime, si la fecha (y la hora) se especifica en UTC o en hora local; siempre que el código JavaScript esté escrito para funcionar con el mismo estándar, debería ser posible evitar problemas.
QTime y la fecha en JavaScript
El motor QML proporciona una conversión automática de tipos de valores de ` QTime ` a objetos ` Date ` de JavaScript. Dado que los valores de ` QTime ` no contienen un componente de fecha, se crea uno exclusivamente para la conversión. Por lo tanto, no debes fiarte del componente de fecha del objeto `Date` resultante.
En realidad, la conversión de un objeto « Date » de JavaScript a « QTime » se realiza convirtiéndolo a un objeto « QDateTime » (utilizando la hora local) y llamando a su método « time()».
Tipo de secuencia a matriz de JavaScript
Consulta «Tipos de secuencia de QML » para obtener una descripción general de los tipos de secuencia. El QtQml module contiene algunos tipos de secuencia que quizá te interese utilizar.
También puede crear una estructura de datos similar a una lista construyendo un ` QJSValue ` mediante ` QJSEngine::newArray()`. Este tipo de matriz de JavaScript no requiere ninguna conversión al pasarla entre QML y C++. Consulte QJSValue#Working With Arrays para obtener más detalles sobre cómo manipular matrices de JavaScript desde C++.
De QByteArray a ArrayBuffer de JavaScript
El motor de QML proporciona una conversión automática de tipos entre valores de ` QByteArray ` y objetos ` ArrayBuffer ` de JavaScript.
Tipos de valor
Algunos tipos de valor de Qt, como ` QPoint `, se representan en JavaScript como objetos que tienen las mismas propiedades y funciones que en la API de C++. Esta misma representación es posible con tipos de valor personalizados de C++. Para habilitar un tipo de valor personalizado con el motor de QML, la declaración de la clase debe anotarse con ` Q_GADGET`. Las propiedades que se desee que sean visibles en la representación de JavaScript deben declararse con ` Q_PROPERTY`. Del mismo modo, las funciones deben marcarse con ` Q_INVOKABLE`. Esto es igual que en las API de C++ basadas en ` QObject `. Por ejemplo, la clase ` Actor ` que se muestra a continuación está anotada como «gadget» y tiene las siguientes propiedades:
class Actor
{
Q_GADGET
Q_PROPERTY(QString name READ name WRITE setName)
public:
QString name() const { return m_name; }
void setName(const QString &name) { m_name = name; }
private:
QString m_name;
};
Q_DECLARE_METATYPE(Actor)Lo habitual es utilizar una clase de gadget como tipo de una propiedad, o emitir un gadget como argumento de una señal. En tales casos, la instancia del gadget se pasa por valor entre C++ y QML (ya que es un tipo de valor). Si el código QML modifica una propiedad de un gadget, se vuelve a crear el gadget completo y se devuelve al setter de la propiedad de C++. En Qt 5, los tipos de gadget no se pueden instanciar mediante una declaración directa en QML. En cambio, sí se puede declarar una instancia de « QObject »; y las instancias de « QObject » siempre se pasan por puntero desde C++ a QML.
Tipos de enumeración
Para utilizar una enumeración personalizada como tipo de datos, es necesario registrar su clase y, además, declarar la enumeración con Q_ENUM() para registrarla en el sistema de metaobjetos de Qt. Por ejemplo, la clase Message que se muestra a continuación tiene una enumeración Status:
class Message : public QObject
{
Q_OBJECT
Q_PROPERTY(Status status READ status NOTIFY statusChanged)
public:
enum Status {
Ready,
Loading,
Error
};
Q_ENUM(Status)
Status status() const;
signals:
void statusChanged();
};Siempre que la clase ` Message ` se haya registrado en el sistema de tipos de QML, su enumeración ` Status ` se podrá utilizar desde QML:
Message {
onStatusChanged: {
if (status == Message.Ready)
console.log("Message is loaded!")
}
}Para utilizar una enumeración como tipo « flags » en QML, consulte Q_FLAG().
Nota: Los nombres de los valores de la enumeración deben comenzar con mayúscula para que sean accesibles desde QML.
...
enum class Status {
Ready,
Loading,
Error
}
Q_ENUM(Status)
...Las clases de enumeración se registran en QML como propiedades con ámbito y sin ámbito. El valor « Ready » se registrará como « Message.Status.Ready » y « Message.Ready ».
Al utilizar clases de enumeración, puede haber varias enumeraciones que utilicen los mismos identificadores. El registro sin ámbito se sobrescribirá con el último enumerado registrado. Para las clases que contengan este tipo de conflictos de nombres, es posible desactivar el registro sin ámbito anotando la clase con una macro especial Q_CLASSINFO. Utiliza el nombre RegisterEnumClassesUnscoped con el valor false para evitar que los enumerados con ámbito se fusionen en el mismo espacio de nombres.
class Message : public QObject
{
Q_OBJECT
Q_CLASSINFO("RegisterEnumClassesUnscoped", "false")
Q_ENUM(ScopedEnum)
Q_ENUM(OtherValue)
public:
enum class ScopedEnum {
Value1,
Value2,
OtherValue
};
enum class OtherValue {
Value1,
Value2
};
};Las enumeraciones de tipos relacionados suelen registrarse en el ámbito del tipo relacionado. Por ejemplo, cualquier enumeración de un tipo diferente utilizada en una declaración « Q_PROPERTY » hace que todas las enumeraciones de ese tipo estén disponibles en QML. Esto suele ser más un inconveniente que una ventaja. Para evitar que esto ocurra, anota tu clase con una macro especial de Q_CLASSINFO. Utiliza el nombre RegisterEnumsFromRelatedTypes con el valor false para evitar que las enumeraciones de tipos relacionados se registren en este tipo.
Debes registrar explícitamente los tipos contenedores de cualquier enumeración que desees utilizar en QML, utilizando QML_ELEMENT o QML_NAMED_ELEMENT, en lugar de confiar en que sus enumeraciones se inyecten en otros tipos.
class OtherType : public QObject
{
Q_OBJECT
QML_ELEMENT
public:
enum SomeEnum { A, B, C };
Q_ENUM(SomeEnum)
enum AnotherEnum { D, E, F };
Q_ENUM(AnotherEnum)
};
class Message : public QObject
{
Q_OBJECT
QML_ELEMENT
// This would usually cause all enums from OtherType to be registered
// as members of Message ...
Q_PROPERTY(OtherType::SomeEnum someEnum READ someEnum CONSTANT)
// ... but this way it doesn't.
Q_CLASSINFO("RegisterEnumsFromRelatedTypes", "false")
public:
OtherType::SomeEnum someEnum() const { return OtherType::B; }
};La diferencia importante radica en el ámbito de las enumeraciones en QML. Si se registra automáticamente una enumeración de una clase relacionada, el ámbito es el tipo en el que se importa. En el caso anterior, sin el Q_CLASSINFO adicional, se utilizaría Message.A, por ejemplo. Si el tipo de C++ que contiene las enumeraciones se registra explícitamente y se suprime el registro de las enumeraciones de los tipos relacionados, el tipo de QML correspondiente al tipo de C++ que contiene las enumeraciones constituye el ámbito de todas sus enumeraciones. En QML se utilizaría ` OtherType.A ` en lugar de ` Message.A `.
Ten en cuenta que puedes utilizar ` QML_FOREIGN ` para registrar un tipo que no puedas modificar. También puedes utilizar ` QML_FOREIGN_NAMESPACE ` para registrar los enumeradores de un tipo de C++ en un espacio de nombres de QML con cualquier nombre en mayúsculas, incluso si ese mismo tipo de C++ también está registrado como tipo de valor de QML.
Tipos de enumeración como parámetros de señales y métodos
Las señales y métodos de C++ con parámetros de tipo enumerado pueden utilizarse desde QML siempre que tanto la enumeración como la señal o el método estén declarados dentro de la misma clase, o que el valor de la enumeración sea uno de los declarados en Qt Namespace.
Además, si se desea conectar una señal de C++ con un parámetro de tipo enumeración a una función de QML mediante la función connect(), el tipo de enumeración debe registrarse utilizando qRegisterMetaType().
En el caso de las señales QML, los valores de enumeración pueden pasarse como parámetros de señal utilizando el tipo int:
Message {
signal someOtherSignal(int statusValue)
Component.onCompleted: {
someOtherSignal(Message.Loading)
}
}© 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.