Incorporación de objetos C++ en QML mediante propiedades de contexto
Advertencia: Al utilizar propiedades de contexto en tu código QML, creas una dependencia de tu código QML respecto al contexto específico que tienes en mente al escribirlo. Esto limita la reutilización de tu código, ya que el contexto puede ser diferente en otros lugares donde se pueda utilizar. Además, la dependencia no se declara. Nunca se especifica import el contexto ni se indica de ningún otro modo lo que se espera. Por lo tanto, cualquiera que intente reutilizar tu código tendrá dificultades para averiguar si el lugar de reutilización cuenta con un contexto suficiente para tu código.
Advertencia: Las propiedades de contexto son invisibles para cualquier herramienta que procese el código QML por adelantado, antes de cargarlo en el motor QML. El compilador deQt Quick , qmllint y el QML Language Server no tienen conocimiento alguno de tus propiedades de contexto y considerarán cualquier acceso a ellas como un acceso no calificado.
Nota: Las propiedadesde contexto pueden sustituirse, por lo general, bien por propiedades normales en el objeto raíz de un componente, bien por singletons definidos en C++ mediante QML_SINGLETON o en QML mediante pragma Singleton.
Al cargar un objeto QML en una aplicación de C++, puede resultar útil incrustar directamente algunos datos de C++ que se puedan utilizar desde el código QML. Esto permite, por ejemplo, invocar un método de C++ en el objeto incrustado o utilizar una instancia de un objeto de C++ como modelo de datos para una vista QML.
La capacidad de inyectar datos de C++ en un objeto QML es posible gracias a la clase ` QQmlContext `. Esta clase expone los datos al contexto de un objeto QML, de modo que se pueda hacer referencia a ellos directamente desde el ámbito del código QML.
Configuración de una propiedad de contexto sencilla
Por ejemplo, he aquí un elemento QML que hace referencia a un valor de ` currentDateTime ` que no existe en el ámbito actual:
// MyItem.qml
import QtQuick
Text { text: currentDateTime }Este valor de ` currentDateTime ` puede establecerse directamente desde la aplicación en C++ que carga el componente QML, utilizando ` QQmlContext::setContextProperty()`:
QQuickView view;
view.rootContext()->setContextProperty("currentDateTime", QDateTime::currentDateTime());
view.setSource(QUrl::fromLocalFile("MyItem.qml"));
view.show();Nota: Dado que todas las expresiones evaluadas en QML se evalúan en un contexto concreto, si se modifica el contexto, se volverán a evaluar todos los enlaces de ese contexto. Por lo tanto, las propiedades de contexto deben utilizarse con precaución fuera de la inicialización de la aplicación, ya que esto puede provocar una disminución del rendimiento de la aplicación.
Establecer un objeto como propiedad de contexto
Las propiedades de contexto pueden contener valores de tipo ` QVariant ` o ` QObject*`. Esto significa que también se pueden inyectar objetos C++ personalizados mediante este enfoque, y que dichos objetos se pueden modificar y leer directamente en QML. A continuación, modificamos el ejemplo anterior para incrustar una instancia de ` QObject ` en lugar de un valor de tipo ` QDateTime `, y el código QML invoca un método sobre la instancia del objeto:
| C++ | |
| QML | |
(Ten en cuenta que los valores de fecha y hora devueltos desde C++ a QML se pueden formatear mediante Qt.formatDateTime() y las funciones asociadas.)
Si el elemento QML necesita recibir señales de la propiedad de contexto, puede conectarse a ellas utilizando el tipo Connections. Por ejemplo, si ApplicationData tiene una señal llamada dataChanged(), esta señal se puede conectar mediante un controlador onDataChanged dentro de un objeto Connections:
Text {
text: applicationData.getCurrentDateTime()
Connections {
target: applicationData
onDataChanged: console.log("The application data changed!")
}
}Consulta también la documentación de QQmlContext para obtener más información.
© 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.