En esta página

QQmlContext Class

La clase QQmlContext define un contexto dentro de un motor QML. Más información...

Encabezado: #include <QQmlContext>
CMake: find_package(Qt6 REQUIRED COMPONENTS Qml)
target_link_libraries(mytarget PRIVATE Qt6::Qml)
qmake: QT += qml
Heredado de: 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 su id en un documento QML. Se pueden utilizar nameForObject() y objectForName() para recuperarlos.

Nota: Es responsabilidad del creador eliminar cualquier QQmlContext que cree. Si un QQmlContext ya no es necesario, debe destruirse explícitamente. La forma más sencilla de garantizarlo es llamar a parent en el QQmlContext.

La jerarquía de contextos

Los contextos forman una jerarquía. La raíz de esta jerarquía es el ` root context` del motor QML. 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 dicho contexto, sí lo son sus enlaces. Si se destruye un contexto, los enlaces de propiedades de los objetos QML pendientes dejarán de evaluarse.

Propiedades del contexto

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 , así como para futuros lectores de los documentos QML en cuestión. Solo se expondrán si el componente QML se instancia en el contexto específico de C++ que se esté considerando. En otros lugares, es posible que se expongan datos de contexto diferentes.

En lugar de utilizar el contexto QML para exponer datos a tus componentes QML, deberías crear propiedades de objeto adicionales para almacenar los datos o utilizar singletons. Consulta «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 explícitamente datos a un contexto por su nombre. Las propiedades de contexto se pueden definir y actualizar llamando a ` QQmlContext::setContextProperty()`.

Para simplificar el enlace y el mantenimiento de conjuntos de datos más grandes, se puede establecer un objeto de contexto en un `QQmlContext`. Todas las propiedades del objeto de contexto están disponibles por su nombre en el contexto, como si 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 `notify` 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 mediante 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 (ya que, en esencia, obliga a reevaluar todos los enlaces). Por lo tanto, si necesitas utilizar propiedades de contexto, deberías 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` indicado y el ` QObject ` parent.

QQmlContext::QQmlContext(QQmlEngine *engine, QObject *parent = nullptr)

Crea un nuevo `QQmlContext` como elemento secundario del contexto raíz de ` engine`, y el ` QObject ` parent.

[override virtual noexcept] QQmlContext::~QQmlContext()

Elimina el objeto ` QQmlContext`.

Cualquier expresión o subcontexto que dependa de este contexto quedará invalidado, pero no se destruirá (a menos que esté vinculado al objeto « QQmlContext »).

QUrl QQmlContext::baseUrl() const

Devuelve la URL base del componente o, si no se ha establecido ninguna, la del componente que lo contiene.

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 ningún objeto de contexto.

Véase también setContextObject().

QVariant QQmlContext::contextProperty(const QString &name) const

Devuelve el valor de la propiedad « name » de este contexto como un objeto « QVariant ». Si sabes que la propiedad que buscas es un objeto « QObject » asignado mediante un identificador QML en el contexto actual, la función « objectForName()» resulta más práctica y rápida. A diferencia de objectForName() y nameForObject(), este método sí recorre la jerarquía de contextos y busca en los contextos superiores si no encuentra el name en el contexto actual. También tiene en cuenta cualquier contextObject() que hayas podido establecer.

Véase también setContextProperty(), objectForName(), nameForObject() y contextObject().

QQmlEngine *QQmlContext::engine() const

Devuelve el ` QQmlEngine` del contexto, o ` nullptr ` si el contexto no tiene ` QQmlEngine ` o si el ` QQmlEngine ` se ha destruido.

[since 6.11] QObject *QQmlContext::findObjectRecursively(const QString &id) const

Busca en este contexto y en sus elementos secundarios, de forma recursiva, un objeto con el ID id. Si se encuentra dicho objeto, se devuelve dicho objeto. De lo contrario, devuelve nullptr.

Solo puede haber un objeto con el id dado en cualquier contexto, pero se pueden crear muchos contextos dentro de un mismo documento, por ejemplo, con vistas y delegados. Cada uno de esos contextos puede contener un objeto con el id dado. Aquí solo se devuelve el primero que se encuentre. La búsqueda se realiza mediante búsqueda en anchura.

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 en este contexto y en sus elementos secundarios, de forma recursiva, objetos con el ID id. Devuelve una lista de dichos objetos.

Solo puede haber un objeto con el id dado en cualquier contexto, pero se pueden crear muchos contextos dentro de un mismo documento, por ejemplo, con vistas y delegados. Cada uno de esos contextos puede contener un objeto con el id dado.

Esta función se introdujo en Qt 6.11.

Véanse también findObjectRecursively(), objectForName() y childContexts().

bool QQmlContext::isValid() const

Devuelve si el contexto es válido.

Para que un contexto sea válido, debe tener un motor, y su ` contextObject()` (si lo tiene) 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 está nombrado en el contexto. Los objetos se nombran mediante « setContextProperty()», como propiedades de un objeto de contexto o mediante identificadores en el caso de los contextos creados con QML.

Si el objeto tiene varios nombres, se devuelve el primero.

A diferencia de ` contextProperty()`, este método no recorre la jerarquía del contexto. Si no se encuentra el nombre en el contexto actual, se devuelve una cadena vacía.

Véanse también contextProperty() y objectForName().

[since 6.2] QObject *QQmlContext::objectForName(const QString &name) const

Devuelve el objeto correspondiente a un « name » dado en este contexto. Devuelve «nullptr» si « name » no está disponible en el contexto o si el valor asociado a « name » no es un « QObject ». Los objetos se identifican mediante « setContextProperty()», como propiedades de un objeto de contexto o mediante identificadores («ids») en el caso de los contextos creados con QML. A diferencia de ` contextProperty()`, este método no recorre la jerarquía del contexto. Si no se encuentra el nombre 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 elemento padre del contexto ` QQmlContext`, o ` nullptr ` si este contexto no tiene elemento padre o si el elemento padre ha sido destruido.

QUrl QQmlContext::resolvedUrl(const QUrl &src) const

Resuelve la URL src de forma relativa a la URL del componente que la contiene.

Véase también QQmlEngine::baseUrl() y setBaseUrl().

void QQmlContext::setBaseUrl(const QUrl &baseUrl)

Establece explícitamente la URL que utilizará resolvedUrl() para las referencias relativas a baseUrl.

Al llamar a esta función, se anulará la URL del componente contenedor utilizada por defecto.

Véase también baseUrl() y resolvedUrl().

void QQmlContext::setContextObject(QObject *object)

Establece el contexto object.

Nota: Nodebes utilizar objetos de contexto para inyectar valores en tus componentes QML. En su lugar, utiliza 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 de una sola vez evita la actualización innecesaria de expresiones, por lo que se recomienda hacerlo en lugar de llamar a ` setContextProperty()` para cada propiedad individual.

Nota: Nodebes utilizar propiedades de contexto para inyectar valores en tus componentes QML. Utiliza en su lugar singletons o propiedades de objeto normales.

Véase también ` QQmlContext::setContextProperty()`.

void QQmlContext::setContextProperty(const QString &name, QObject *value)

Establece el valor de « value » de la propiedad « name » en este contexto.

QQmlContext No asume la propiedad de ` value`.

Nota: Nodebes utilizar propiedades de contexto para inyectar valores en tus componentes QML. En su lugar, utiliza singletons o propiedades de objeto normales.

Véase también contextProperty().

void QQmlContext::setContextProperty(const QString &name, const QVariant &value)

Establece el valor « value » de la propiedad « name » en este contexto.

Nota: Nodebes utilizar las propiedades del contexto para inyectar valores en tus componentes QML. En su lugar, utiliza singletons o propiedades de objetos 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.