En esta página

Exposición del estado desde C++ a QML

A menudo resulta conveniente exponer algunas propiedades desde C++ a todos los elementos QML de un componente concreto, a todos los elementos QML de un módulo o incluso a todos los elementos QML en general. Esto se puede lograr introduciendo singletons o añadiendo propiedades a los objetos raíz de determinados componentes.

Uso de singletons

Si deseas exponer varias propiedades globales a todos los elementos de un módulo o a todos los elementos en general, puedes definir un singleton en C++. Para ello, añade las macros « QML_ELEMENT » o « QML_NAMED_ELEMENT » y la macro «QML_SINGLETON» a una clase que contenga las propiedades que deseas exponer como declaraciones « Q_PROPERTY »:

// Singleton.h
class Singleton : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int thing READ thing WRITE setThing NOTIFY thingChanged FINAL)
    QML_ELEMENT
    QML_SINGLETON

public:
    Singleton(QObject *parent = nullptr) : QObject(parent) {}

    int thing() const { return m_value; }
    void setThing(int v)
    {
        if (v != m_value) {
            m_value = v;
            emit thingChanged();
        }
    }

signals:
    void thingChanged();

private:
    int m_value = 12;
};

Ahora puedes acceder a la propiedad `thing` del singleton desde cualquier código QML que importe este módulo:

import QtQml

QtObject {
    objectName: "The thing is " + Singleton.thing
}

Si has colocado tus archivos QML en el mismo directorio que el módulo (lo cual es muy recomendable), el singleton estará disponible mediante la importación implícita dentro de tu módulo. No es necesario importar nada de forma explícita. Si no es así, o si deseas acceder a la propiedad «thing» desde otros módulos, sí que tendrás que importar el módulo al que pertenece el singleton.

Para establecer el valor de la propiedad desde C++, es posible que tengas que recuperar la instancia del singleton. Para ello, puedes utilizar ` QQmlEngine::singletonInstance`. La forma recomendada de hacerlo es pasando un módulo y un nombre de tipo como parámetros:

    Singleton *singleton
            = engine->singletonInstance<Singleton *>("MyModule", "Singleton");
    singleton->setThing(77);

Uso de propiedades de objeto

Si deseas exponer algunas propiedades únicamente a los elementos QML de un componente específico, puedes añadirlas como propiedades normales al objeto raíz del componente. Para asegurarte de que se establezcan realmente en todos los casos, puedes convertirlas en propiedades obligatorias. Podrías escribir tu componente QML de la siguiente manera:

pragma ComponentBehavior: Bound

import QtQuick

Window {
    id: root
    visible: true

    required property int thing

    Text {
        anchors.fill: parent
        text: "The thing is " + root.thing
    }

    component Inner: QtObject {
        objectName: "I can see " + root.thing + " because I'm bound."
    }
}

Utilizamos un ID para el elemento raíz del componente y hacemos referencia a la propiedad por su ID y su nombre desde cualquier objeto interno. Para que el ID del elemento raíz esté disponible de forma segura para cualquier componente anidado, utilizamos ComponentBehavior.

A continuación, en C++, al crear un objeto a partir de dicho componente, debes asegurarte de llamar a ` QQmlComponent::createWithInitialProperties`, ` QQmlApplicationEngine::setInitialProperties` o ` QQuickView::setInitialProperties ` para inicializar las propiedades. Por ejemplo:

    QQmlEngine engine;

    QQmlComponent component(&engine, "MyModule", "RequiredProperties");
    QScopedPointer<QObject> o(component.createWithInitialProperties({
            {"thing", 11}
    }));

Esto supone que la URI de tu módulo es MyModule y que el módulo está disponible en la ruta de importación de QML.

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