QQmlContext Class
La clase QQmlContext define un contexto dentro de un motor QML. Más...
| Cabecera: | #include <QQmlContext> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Qml)target_link_libraries(mytarget PRIVATE Qt6::Qml) |
| qmake: | QT += qml |
| Hereda: | QObject |
Tipos Públicos
| struct | PropertyPair |
Funciones Públicas
| QQmlContext(QQmlContext *parentContext, QObject *parent = nullptr) | |
| QQmlContext(QQmlEngine *engine, QObject *parent = nullptr) | |
| virtual | ~QQmlContext() override |
| QUrl | baseUrl() const |
(since 6.11) QList<QQmlContext *> | childContexts() const |
| QObject * | contextObject() const |
| QVariant | contextProperty(const QString &name) const |
| QQmlEngine * | engine() const |
(since 6.11) QObject * | findObjectRecursively(const QString &id) const |
(since 6.11) QList<QObject *> | findObjectsRecursively(const QString &id) const |
| bool | isValid() const |
| QString | nameForObject(const QObject *object) const |
(since 6.2) QObject * | objectForName(const QString &name) const |
| QQmlContext * | parentContext() const |
| QUrl | resolvedUrl(const QUrl &src) const |
| void | setBaseUrl(const QUrl &baseUrl) |
| void | setContextObject(QObject *object) |
| void | setContextProperties(const QList<QQmlContext::PropertyPair> &properties) |
| void | setContextProperty(const QString &name, QObject *value) |
| void | setContextProperty(const QString &name, const QVariant &value) |
Descripción detallada
Los contextos contienen los objetos identificados por id en un documento QML. Puede utilizar nameForObject() y objectForName() para recuperarlos.
Nota: Es responsabilidad del creador borrar cualquier QQmlContext que construya. Si un QQmlContext ya no es necesario, debe destruirse explícitamente. La forma más sencilla de asegurar esto es darle al QQmlContext un parent.
Jerarquía de contextos
Los contextos forman una jerarquía. La raíz de esta jerarquía es el motor QML root context. Cada componente QML crea su propio contexto al instanciarse y algunos elementos QML crean contextos adicionales para sí mismos.
Aunque los objetos QML instanciados en un contexto no son estrictamente propiedad de ese contexto, sus enlaces sí lo son. Si se destruye un contexto, los enlaces de propiedad de los objetos QML pendientes dejarán de evaluarse.
Propiedades de los contextos
Los contextos también permiten exponer datos a los componentes QML instanciados por el motor QML. Dichos datos son invisibles para cualquier herramienta, incluido el compiladorQt Quick y para futuros lectores de los documentos QML en cuestión. Sólo se expondrán si el componente QML se instancia en el contexto C++ específico previsto. En otros lugares, es posible que se expongan datos de contexto diferentes.
En lugar de utilizar el contexto QML para exponer datos a sus componentes QML, debe crear propiedades de objeto adicionales para contener los datos o utilizar singletons. Consulte Exposición del estado de C++ a QML para obtener una explicación detallada.
Cada QQmlContext contiene un conjunto de propiedades, distintas de sus propiedades QObject, que permiten vincular datos explícitamente a un contexto por nombre. Las propiedades de contexto pueden definirse y actualizarse llamando a QQmlContext::setContextProperty().
Para simplificar la vinculación y el mantenimiento de conjuntos de datos más grandes, puede establecerse un objeto context en un QQmlContext. Todas las propiedades del objeto de contexto están disponibles por nombre en el contexto, como si todas se hubieran añadido individualmente mediante llamadas a QQmlContext::setContextProperty(). Los cambios en los valores de las propiedades se detectan a través de la señal de notificación de la propiedad. Establecer un objeto de contexto es más rápido y sencillo que añadir y mantener manualmente los valores de las propiedades de contexto.
Todas las propiedades añadidas explícitamente por QQmlContext::setContextProperty() tienen prioridad sobre las propiedades del objeto de contexto.
Los contextos hijos heredan las propiedades de contexto de sus padres; si un contexto hijo establece una propiedad de contexto que ya existe en su padre, la nueva propiedad de contexto anula la del padre.
Advertencia: Establecer el objeto de contexto o añadir nuevas propiedades de contexto después de que se haya creado un objeto en ese contexto es una operación costosa (esencialmente obliga a reevaluar todos los enlaces). Por lo tanto, si necesita utilizar propiedades de contexto, debería al menos completar la "configuración" del contexto antes de utilizarlo para crear cualquier objeto.
Véase también Exposición de atributos de tipos C++ a QML.
Documentación de funciones miembro
QQmlContext::QQmlContext(QQmlContext *parentContext, QObject *parent = nullptr)
Crea un nuevo QQmlContext con el parentContext dado , y el QObject parent .
QQmlContext::QQmlContext(QQmlEngine *engine, QObject *parent = nullptr)
Crea un nuevo QQmlContext como hijo de engine's root context, y el QObject parent .
[override virtual noexcept] QQmlContext::~QQmlContext()
Destruye QQmlContext.
Cualquier expresión o sub-contexto que dependa de este contexto será invalidado, pero no destruido (a no ser que esté relacionado con el objeto QQmlContext ).
QUrl QQmlContext::baseUrl() const
Devuelve la url base del componente, o del componente contenedor si no se ha establecido ninguna.
Véase también setBaseUrl().
[since 6.11] QList<QQmlContext *> QQmlContext::childContexts() const
Devuelve los QQmlContexts hijos inmediatos del contexto.
Esta función se introdujo en Qt 6.11.
Véase también parentContext(), findObjectRecursively(), y findObjectsRecursively().
QObject *QQmlContext::contextObject() const
Devuelve el objeto de contexto, o nullptr si no hay objeto de contexto.
Véase también setContextObject().
QVariant QQmlContext::contextProperty(const QString &name) const
Devuelve el valor de la propiedad name para este contexto como QVariant. Si sabe que la propiedad que está buscando es una QObject asignada usando un id QML en el contexto actual, objectForName() es más conveniente y rápido. A diferencia de objectForName() y nameForObject(), este método sí recorre la jerarquía de contextos y busca en los contextos padre si el name no se encuentra en el actual. También tiene en cuenta cualquier contextObject() que haya establecido.
Véase también setContextProperty(), objectForName(), nameForObject() y contextObject().
QQmlEngine *QQmlContext::engine() const
Devuelve el contexto QQmlEngine, o nullptr si el contexto no tiene QQmlEngine o el QQmlEngine fue destruido.
[since 6.11] QObject *QQmlContext::findObjectRecursively(const QString &id) const
Busca recursivamente en este contexto y en sus hijos un objeto con el ID id. Si lo encuentra, devuelve el objeto. En caso contrario, devuelve nullptr.
Sólo puede haber un objeto con el ID id en un contexto determinado, pero se pueden crear varios contextos dentro de un mismo documento, por ejemplo con vistas y delegados. Cada uno de esos contextos puede contener un objeto con el valor id. Sólo se devuelve el primero que se encuentra. La búsqueda se realiza utilizando breadth-first search.
Esta función se introdujo en Qt 6.11.
Véase también findObjectsRecursively(), objectForName(), y childContexts().
[since 6.11] QList<QObject *> QQmlContext::findObjectsRecursively(const QString &id) const
Busca recursivamente en este contexto y sus hijos objetos con ID id. Devuelve una lista de estos objetos.
Sólo puede haber un objeto con el ID id en un contexto determinado, pero se pueden crear varios contextos dentro de un mismo documento, por ejemplo con vistas y delegados. Cada uno de esos contextos puede contener un objeto con la dirección id.
Esta función se introdujo en Qt 6.11.
Véase también findObjectRecursively(), objectForName(), y childContexts().
bool QQmlContext::isValid() const
Devuelve si el contexto es válido.
Para ser válido, un contexto debe tener un motor, y su contextObject(), si existe, no debe haber sido eliminado.
QString QQmlContext::nameForObject(const QObject *object) const
Devuelve el nombre de object en este contexto, o una cadena vacía si object no se nombra en el contexto. Los objetos se nombran mediante setContextProperty(), o como propiedades de un objeto de contexto, o mediante ids en el caso de contextos creados mediante QML.
Si el objeto tiene varios nombres, se devuelve el primero.
A diferencia de contextProperty(), este método no recorre la jerarquía de contextos. Si el nombre no se encuentra en el contexto actual, se devuelve una cadena vacía.
Véase también contextProperty() y objectForName().
[since 6.2] QObject *QQmlContext::objectForName(const QString &name) const
Devuelve el objeto para un name dado en este contexto. Devuelve nullptr si name no está disponible en el contexto o si el valor asociado con name no es un QObject. Los objetos son nombrados por setContextProperty(), o como propiedades de un objeto de contexto, o por ids en el caso de contextos creados por QML. A diferencia de contextProperty(), este método no recorre la jerarquía de contextos. Si el nombre no se encuentra en el contexto actual, se devuelve nullptr.
Esta función se introdujo en Qt 6.2.
Véase también contextProperty() y nameForObject().
QQmlContext *QQmlContext::parentContext() const
Devuelve el contexto padre QQmlContext, o nullptr si este contexto no tiene padre o si el padre ha sido destruido.
QUrl QQmlContext::resolvedUrl(const QUrl &src) const
Resuelve la URL src relativa a la URL del componente contenedor.
Véase también QQmlEngine::baseUrl() y setBaseUrl().
void QQmlContext::setBaseUrl(const QUrl &baseUrl)
Establece explícitamente la url que resolvedUrl() utilizará para las referencias relativas a baseUrl.
La llamada a esta función anulará la url del componente contenedor utilizada por defecto.
Véase también baseUrl() y resolvedUrl().
void QQmlContext::setContextObject(QObject *object)
Establezca el contexto object.
Nota: No debe utilizar objetos de contexto para inyectar valores en sus componentes QML. En su lugar, utilice singletons o propiedades de objetos normales.
Véase también contextObject().
void QQmlContext::setContextProperties(const QList<QQmlContext::PropertyPair> &properties)
Establece un lote de properties en este contexto.
Establecer todas las propiedades en un lote evita expresiones de actualización innecesarias, y por lo tanto se recomienda en lugar de llamar a setContextProperty() para cada propiedad individual.
Nota: No debe utilizar propiedades de contexto para inyectar valores en sus componentes QML. En su lugar, utilice singletons o propiedades de objeto normales.
Véase también QQmlContext::setContextProperty().
void QQmlContext::setContextProperty(const QString &name, QObject *value)
Establece el value de la propiedad name en este contexto.
QQmlContext no toma la propiedad value.
Nota: No debe utilizar propiedades de contexto para inyectar valores en sus componentes QML. En su lugar, utilice singletons o propiedades de objeto normales.
Véase también contextProperty().
void QQmlContext::setContextProperty(const QString &name, const QVariant &value)
Establece un value de la propiedad name en este contexto.
Nota: No debe utilizar propiedades de contexto para inyectar valores en sus componentes QML. En su lugar, utilice singletons o propiedades de objeto normales.
© 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.
