En esta página

Descripción general: integración de QML y C++

QML está diseñado para ser fácilmente extensible mediante código C++. Las clases del Qt Qml permiten cargar y manipular objetos QML desde C++, y la forma en que el motor de QML se integra con el sistema de metobjetos de Qt permite invocar funcionalidades de C++ directamente desde QML. Esto permite el desarrollo de aplicaciones híbridas que se implementan con una combinación de código QML, JavaScript y C++.

La integración de QML y C++ ofrece diversas posibilidades, entre las que se incluye la capacidad de:

  • Separar el código de la interfaz de usuario del código de la lógica de la aplicación, implementando el primero con QML y JavaScript dentro de documentos QML, y el segundo con C++
  • Utilizar e invocar ciertas funcionalidades de C++ desde QML (por ejemplo, para invocar la lógica de la aplicación, utilizar un modelo de datos implementado en C++ o llamar a algunas funciones de una biblioteca de C++ de terceros)
  • Acceder a la funcionalidad de la Qt Qml o Qt Quick API de C++ (por ejemplo, para generar imágenes dinámicamente utilizando QQuickImageProvider)
  • Implementar tus propios tipos de objetos QML desde C++, ya sea para utilizarlos en tu propia aplicación específica o para distribuirlos a otros

Para proporcionar datos o funcionalidades de C++ a QML, estos deben estar disponibles a través de una clase derivada de ` QObject`. Debido a la integración del motor de QML con el sistema de metaobjetos, se puede acceder desde QML a las propiedades, métodos y señales de cualquier clase derivada de QObject, tal y como se describe en «Exposición de atributos de tipos de C++ a QML». Una vez que dicha clase proporciona la funcionalidad necesaria, esta se puede exponer a QML de diversas formas:

  • La clase puede registrarse como un tipo QML instanciable, de modo que pueda instanciarse y utilizarse como cualquier tipo de objeto QML ordinario desde el código QML
  • La clase puede registrarse como un tipo «singleton», de modo que se pueda importar una única instancia de la clase desde el código QML, lo que permite acceder a las propiedades, métodos y señales de la instancia desde QML

Estos son los métodos más habituales para acceder a la funcionalidad de C++ desde el código QML. El módulo « QML Type Registration Macros » ofrece otras opciones y variantes. Además, aparte de la capacidad de acceder a la funcionalidad de C++ desde QML, el Qt Qml módulo también ofrece formas de hacer lo contrario y manipular objetos QML desde código C++. Consulta Interactuar con objetos QML desde C++ para obtener más detalles.

A menudo resulta conveniente exponer cierto estado como propiedades globales a QML. En «Exposición del estado desde C++ a QML » se describe cómo hacerlo.

El código C++ puede integrarse en una aplicación C++ o en un módulo QML independiente, dependiendo de si se va a distribuir como aplicación independiente o como biblioteca. Un módulo QML puede contener un complemento de C++ que, a su vez, puede ser cargado dinámicamente por el motor de QML. Esto permite que una aplicación utilice módulos QML que no se hayan enlazado en el binario.

También puedes crear manualmente complementos independientes. Consulta «Proporcionar tipos y funcionalidad en un complemento de C++» para obtener más información. No se recomienda esta opción.

Por último, una instancia de la clase puede integrarse en el código QML como una propiedad de contexto u objeto de contexto, lo que permite acceder a las propiedades, métodos y señales de la instancia desde QML. Se debe evitar el uso de propiedades de contexto.

Elección del método de integración adecuado entre C++ y QML

Para determinar rápidamente qué método de integración es el adecuado para su situación, puede utilizar el siguiente diagrama de flujo:

El diagrama de flujo ayuda al usuario a seleccionar la integración correcta

Para obtener una descripción de las macros del diagrama de flujo, consulta la documentación «Definición de tipos QML desde C++ ».

Exposición de atributos de clases de C++ a QML

QML se puede ampliar fácilmente desde C++ gracias a la integración del motor de QML con el sistema de metaobjetos de Qt. Esta integración permite acceder desde QML a las propiedades, métodos y señales de cualquier clase derivada de ` QObject`: las propiedades se pueden leer y modificar, los métodos se pueden invocar desde expresiones de JavaScript y se crean automáticamente controladores de señales según sea necesario. Además, se puede acceder desde QML a los valores de enumeración de una clase derivada de ` QObject`.

Consulta «Exposición de atributos de tipos de C++ a QML» para obtener más información.

Definición de tipos QML desde C++

Los tipos QML se pueden definir en C++ y, a continuación, registrarse en el sistema de tipos de QML. Esto permite instanciar una clase de C++ como un tipo de objeto QML, lo que permite implementar tipos de objetos personalizados en C++ e integrarlos en el código QML existente. Una clase de C++ también puede registrarse con otros fines: por ejemplo, podría registrarse como tipo singleton para permitir que el código QML importe una única instancia de la clase, o bien para que los valores de enumeración de una clase no instanciable sean accesibles desde QML.

Además, el Qt Qml módulo proporciona mecanismos para definir tipos QML que se integran con conceptos de QML como las propiedades adjuntas y las propiedades por defecto.

Para obtener más información sobre cómo registrar y crear tipos QML personalizados desde C++, consulta la documentación «Definición de tipos QML desde C++ ».

Incrustación de objetos C++ en QML con propiedades de contexto

Los objetos y valores de C++ pueden integrarse directamente en el contexto (o ámbito) de los objetos QML cargados mediante propiedades de contexto y objetos de contexto. Esto se consigue a través de la clase ` QQmlContext `, proporcionada por el Qt Qml módulo, que expone datos al contexto de un componente QML, lo que permite inyectar datos desde C++ en QML.

Consulta «Incrustación de objetos C++ en QML mediante propiedades de contexto » para obtener más información.

Interacción con objetos QML desde C++

Los tipos de objetos QML pueden instanciarse desde C++ e inspeccionarse para acceder a sus propiedades, invocar sus métodos y recibir sus notificaciones de señales. Esto es posible gracias a que todos los tipos de objetos QML se implementan mediante clases derivadas de ` QObject`, lo que permite al motor de QML cargar e inspeccionar objetos de forma dinámica a través del sistema de metaobjetos de Qt.

Advertencia: Aunque es posible acceder a objetos QML desde C++ y manipularlos, no es el enfoque recomendado, salvo con fines de prueba y creación de prototipos. Uno de los puntos fuertes de la integración entre QML y C++ es la capacidad de implementar interfaces de usuario en QML separadas de la lógica en C++ y del backend de datos, y esto falla si el lado de C++ empieza a manipular QML directamente. Este enfoque también dificulta la modificación de la interfaz de usuario de QML sin afectar a su equivalente en C++.

Para obtener más información sobre cómo acceder a objetos QML desde C++, consulta la documentación sobre «Interacción con objetos QML desde C++» y la sección «Exposición de datos desde C++ a QML» de la página de prácticas recomendadas.

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 desde QML o C++, siempre que el motor conozca los tipos de datos implicados.

Consulte «Conversión de tipos de datos entre QML y C++» para obtener información sobre los tipos integrados que admite el motor y cómo se convierten estos tipos para su uso cuando se intercambian entre QML y C++.

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