En esta página

Exposición de atributos de tipos de C++ en QML

QML se puede ampliar fácilmente con funcionalidades definidas en código C++. Gracias a la estrecha integración del motor de QML con el sistema de metaobjetos de Qt, se puede acceder desde el código QML a cualquier funcionalidad que esté correctamente expuesta por una clase derivada de ` QObject` o un tipo ` Q_GADGET `. Esto permite acceder a los datos y funciones de C++ directamente desde QML, a menudo con pocas o ninguna modificación.

El motor QML tiene la capacidad de introspectar instancias de ` QObject ` a través del sistema de metaobjetos. Esto significa que cualquier código QML puede acceder a los siguientes miembros de una instancia de una clase derivada de ` QObject`:

  • Propiedades
  • Métodos (siempre que sean ranuras públicas o estén marcados con ` Q_INVOKABLE`)
  • Señales

(Además, las enumeraciones están disponibles si se han declarado con ` Q_ENUM`. Para más detalles, véase «Conversión de tipos de datos entre QML y C++» ).

En general, se puede acceder a ellos desde QML independientemente de si se ha registrado o no una clase derivada de ` QObject` en el sistema de tipos de QML. Sin embargo, si una clase se va a utilizar de tal forma que requiera que el motor acceda a información adicional sobre los tipos —por ejemplo, si la propia clase se va a utilizar como parámetro de un método o como propiedad, o si uno de sus tipos de enumeración se va a utilizar de esta manera—, entonces puede que sea necesario registrar la clase. Se recomienda registrar todos los tipos que se utilicen en QML, ya que solo los tipos registrados pueden analizarse en tiempo de compilación.

El registro es obligatorio para los tipos « Q_GADGET », ya que no derivan de una base común conocida y no pueden ponerse a disposición automáticamente. Sin el registro, no se puede acceder a sus propiedades ni a sus métodos.

Puedes hacer que los tipos de C++ de otro módulo estén disponibles en tu propio módulo añadiendo una dependencia a tu llamada a ` qt_add_qml_module ` mediante la opción ` DEPENDENCIES `. Por ejemplo, es posible que desees depender de QtQuick para que tus tipos de C++ expuestos en QML puedan utilizar QColor como argumentos de métodos y valores de retorno. QtQuick expone QColor como un tipo de valor «color». Estas dependencias pueden inferirse automáticamente en tiempo de ejecución, pero no debes confiar en ello.

Ten en cuenta también que varios de los conceptos importantes tratados en este documento se muestran en el tutorial «Escritura de extensiones QML con C++ ».

Para obtener más información sobre C++ y los diferentes métodos de integración con QML, consulta la página de descripción general de la integración de C++ y QML.

Manejo y propiedad de los tipos de datos

Cualquier dato que se transfiera de C++ a QML, ya sea como valor de una propiedad, parámetro o valor de retorno de un método, o como valor de un parámetro de señal, debe ser de un tipo compatible con el motor de QML.

Por defecto, el motor admite varios tipos de Qt C++ y puede convertirlos automáticamente de forma adecuada cuando se utilizan desde QML. Además, las clases de C++ registradas en el sistema de tipos de Qml pueden utilizarse como tipos de datos, al igual que sus enumeraciones, siempre que estén debidamente registradas. Consulte «Conversión de tipos de datos entre Qml y C++» para obtener más información.

Además, se tienen en cuenta las reglas de propiedad de los datos cuando estos se transfieren de C++ a QML. Consulte Propiedad de los datos para obtener más detalles.

Exposición de propiedades

Se puede especificar una propiedad para cualquier clase derivada de « QObject » utilizando la macro « Q_PROPERTY()». Una propiedad es un miembro de datos de la clase con una función de lectura asociada y una función de escritura opcional.

Se puede acceder desde QML a todas las propiedades de una clase derivada de ` QObject` o de una clase ` Q_GADGET `.

Por ejemplo, a continuación se muestra una clase « Message » con una propiedad « author ». Tal y como se especifica en la llamada a la macro « Q_PROPERTY », esta propiedad se puede leer mediante el método « author() » y se puede escribir mediante el método « setAuthor() »:

Nota: No utilices «typedef» ni «using» para los tipos « Q_PROPERTY », ya que esto confundirá a moc. Esto podría provocar que fallaran ciertas comparaciones de tipos.

En lugar de:

using FooEnum = Foo::Enum;

class Bar : public QObject
{
    Q_OBJECT
    Q_PROPERTY(FooEnum enum READ enum WRITE setEnum NOTIFY enumChanged)
};

Haz referencia al tipo directamente:

class Bar : public QObject
{
    Q_OBJECT
    Q_PROPERTY(Foo::Enum enum READ enum WRITE setEnum NOTIFY enumChanged)
};

Para que « Message » esté disponible, debes utilizar « QML_ELEMENT » en C++ y «qt_add_qml_module» en CMake.

class Message : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    Q_PROPERTY(QString author READ author WRITE setAuthor NOTIFY authorChanged)
public:
    void setAuthor(const QString &a)
    {
        if (a != m_author) {
            m_author = a;
            emit authorChanged();
        }
    }

    QString author() const
    {
        return m_author;
    }

signals:
    void authorChanged();

private:
    QString m_author;
};

Para que una instancia de Message esté disponible, se puede pasar como propiedad «required» a un archivo llamado MyItem.qml:

int main(int argc, char *argv[]) {
    QGuiApplication app(argc, argv);

    QQuickView view;
    Message msg;
    view.setInitialProperties({{"msg", &msg}});
    view.setSource(QUrl::fromLocalFile("MyItem.qml"));
    view.show();

    return app.exec();
}

A continuación, la propiedad ` author ` se podría leer desde ` MyItem.qml`:

// MyItem.qml
import QtQuick

Text {
    required property Message msg

    width: 100; height: 100
    text: msg.author    // invokes Message::author() to get this value

    Component.onCompleted: {
        msg.author = "Jonah"  // invokes Message::setAuthor()
    }
}

Para lograr la máxima interoperabilidad con QML, cualquier propiedad en la que se pueda escribir debe tener asociada una señal NOTIFY que se emita cada vez que cambie el valor de la propiedad. Esto permite utilizar la propiedad con el enlace de propiedades, una característica esencial de QML que garantiza las relaciones entre propiedades al actualizar automáticamente una propiedad cada vez que cambia el valor de cualquiera de sus dependencias.

En el ejemplo anterior, la señal NOTIFY asociada a la propiedad « author » es « authorChanged », tal y como se especifica en la llamada a la macro « Q_PROPERTY()». Esto significa que cada vez que se emite la señal —como ocurre cuando se cambia el autor en `Message::setAuthor()`—, se notifica al motor de QML que deben actualizarse todos los enlaces que involucren a la propiedad ` author ` y, a su vez, el motor actualizará la propiedad ` text ` llamando de nuevo a ` Message::author() `.

Si la propiedad author fuera modificable pero no tuviera una señal NOTIFY asociada, el valor de text se inicializaría con el valor inicial devuelto por Message::author(), pero no se actualizaría con los cambios posteriores que se produjeran en esta propiedad. Además, cualquier intento de vincularse a la propiedad desde QML generaría una advertencia en tiempo de ejecución por parte del motor.

Nota: Se recomienda que la señal NOTIFY se denomine <property>Changed, donde <property> es el nombre de la propiedad. El controlador de señales de cambio de propiedad asociado generado por el motor QML siempre adoptará la forma on<Property>Changed, independientemente del nombre de la señal C++ relacionada, por lo que se recomienda que el nombre de la señal siga esta convención para evitar cualquier confusión.

Notas sobre el uso de las señales «Notify»

Para evitar bucles o evaluaciones excesivas, los desarrolladores deben asegurarse de que la señal de cambio de propiedad solo se emita cuando el valor de la propiedad haya cambiado realmente. Además, si una propiedad o un grupo de propiedades se utiliza con poca frecuencia, está permitido utilizar la misma señal NOTIFY para varias propiedades. Esto debe hacerse con cuidado para garantizar que el rendimiento no se vea afectado.

La presencia de una señal NOTIFY conlleva una pequeña sobrecarga. Hay casos en los que el valor de una propiedad se establece en el momento de la construcción del objeto y no cambia posteriormente. El caso más habitual es el de una propiedad de solo lectura que contiene un subobjeto, a la que normalmente se accede mediante la sintaxis de propiedades agrupadas, en la que el subobjeto se asigna una sola vez y solo se libera cuando se elimina el propietario. En estos casos, se puede añadir el atributo CONSTANT a la declaración de la propiedad en lugar de una señal NOTIFY.

El atributo CONSTANT solo debe utilizarse para propiedades cuyo valor se establezca y se fije definitivamente únicamente en el constructor de la clase. Todas las demás propiedades que se deseen utilizar en enlaces deben tener, en su lugar, una señal NOTIFY.

Propiedades con tipos de objeto

Se puede acceder a las propiedades de tipo objeto desde QML siempre que el tipo de objeto se haya registrado adecuadamente en el sistema de tipos de QML.

Por ejemplo, el tipo ` Message ` podría tener una propiedad ` body ` de tipo ` MessageBody*`:

class Message : public QObject
{
    Q_OBJECT
    Q_PROPERTY(MessageBody* body READ body WRITE setBody NOTIFY bodyChanged)
public:
    MessageBody* body() const;
    void setBody(MessageBody* body);
};

class MessageBody : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QString text READ text WRITE text NOTIFY textChanged)
// ...
}

Supongamos que el tipo ` Message ` se ha registrado en el sistema de tipos de QML, lo que permite utilizarlo como tipo de objeto desde el código QML:

Message {
    // ...
}

Si el tipo ` MessageBody ` también se hubiera registrado en el sistema de tipos, sería posible asignar ` MessageBody ` a la propiedad ` body ` de un ` Message`, todo ello desde el código QML:

Message {
    body: MessageBody {
        text: "Hello, world!"
    }
}

Propiedades con tipos de lista de objetos

Las propiedades que contienen listas de tipos derivados de ` QObject` también pueden exponerse a QML. Sin embargo, para ello se debe utilizar ` QQmlListProperty ` en lugar de ` QList<T>` como tipo de propiedad. Esto se debe a que ` QList ` no es un tipo derivado de ` QObject` y, por lo tanto, no puede proporcionar las características necesarias de las propiedades de QML a través del sistema de metobjetos de Qt, como las notificaciones de señales cuando se modifica una lista.

Por ejemplo, la clase MessageBoard que se muestra a continuación tiene una propiedad messages de tipo QQmlListProperty que almacena una lista de instancias de Message:

class MessageBoard : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QQmlListProperty<Message> messages READ messages)
public:
    QQmlListProperty<Message> messages();

private:
    static void append_message(QQmlListProperty<Message> *list, Message *msg);

    QList<Message *> m_messages;
};

La función `MessageBoard::messages()` simplemente crea y devuelve un ` QQmlListProperty ` a partir de su miembro ` QList<T> m_messages `, pasando las funciones de modificación de la lista adecuadas según lo requiera el constructor de ` QQmlListProperty `:

QQmlListProperty<Message> MessageBoard::messages()
{
    return QQmlListProperty<Message>(this, 0, &MessageBoard::append_message);
}

void MessageBoard::append_message(QQmlListProperty<Message> *list, Message *msg)
{
    MessageBoard *msgBoard = qobject_cast<MessageBoard *>(list->object);
    if (msg)
        msgBoard->m_messages.append(msg);
}

Ten en cuenta que el tipo de clase de plantilla para el ` QQmlListProperty ` —en este caso, ` Message `— debe estar registrado en el sistema de tipos de QML.

Propiedades agrupadas

Cualquier propiedad cuyo tipo tenga subpropiedades propias puede manipularse utilizando la sintaxis de propiedades agrupadas, independientemente de si ese tipo es un tipo de valor, como font, o un tipo de objeto. Las propiedades agrupadas resultan útiles para exponer un grupo de propiedades relacionadas que describen un conjunto de atributos de un tipo.

Por ejemplo, supongamos que la propiedad « Message::author » fuera de tipo « MessageAuthor » en lugar de una simple cadena, con las subpropiedades « name » y « email »:

class MessageAuthor : public QObject
{
    Q_PROPERTY(QString name READ name WRITE setName)
    Q_PROPERTY(QString email READ email WRITE setEmail)
public:
    ...
};

class Message : public QObject
{
    Q_OBJECT
    Q_PROPERTY(MessageAuthor* author READ author)
public:
    Message(QObject *parent)
        : QObject(parent), m_author(new MessageAuthor(this))
    {
    }
    MessageAuthor *author() const {
        return m_author;
    }
private:
    MessageAuthor *m_author;
};

La propiedad author se podría escribir utilizando la sintaxis de propiedades agrupadas en QML, de la siguiente manera:

Message {
    author.name: "Alexandra"
    author.email: "alexandra@mail.com"
}

Dado que « author » es una propiedad de tipo objeto, las asignaciones agrupadas no crean el objeto « MessageAuthor ». Se asignan al objeto que devuelva « Message::author() ». Esto tiene algunas consecuencias:

  • Los nombres de las subpropiedades se resuelven en función del tipo declarado de la propiedad, en este caso MessageAuthor, y no en función del tipo del objeto que se almacene en ella en tiempo de ejecución. Diferentes instanciaciones de Message podrían generar objetos author de distintos tipos. Lo único en lo que podemos confiar al crear el componente QML es el tipo declarado.
  • El objeto tiene que existir cuando se aplican las asignaciones agrupadas. De lo contrario, el motor lanza un error similar a « Cannot set properties on author as it is null ». Crear el objeto en el constructor del propietario, como se ha visto anteriormente, es la forma más sencilla de garantizarlo, pero un getter que cree el objeto en el primer acceso funciona igual de bien.
  • La vida útil del objeto es la que le asigne la implementación en C++. La sintaxis de las propiedades agrupadas no crea ni destruye objetos.

Declarar « author » como de solo lectura, tal y como se muestra en el ejemplo anterior, impide además que el código QML sustituya el objeto « MessageAuthor ». Si « author » tuviera un accesor « WRITE », también se le podría asignar un nuevo objeto:

Message {
    author: MessageAuthor {
        name: "Alexandra"
        email: "alexandra@mail.com"
    }
}

No se pueden combinar las dos formas para la misma propiedad en la misma definición de objeto. Asignar un objeto a author y escribir también author.name en el mismo Message genera un error. Puedes eludir esto colocando la propiedad agrupada en un ámbito diferente. Sin embargo, hacerlo da lugar a resultados confusos, ya que ahora tienes dos objetos ` MessageAuthor `: el creado por el constructor y el asignado explícitamente. Solo el orden de evaluación de los enlaces determina a cuál de ellos se aplica la propiedad agrupada.

Esto significa que la buena práctica es:

  • Mantener los objetos utilizados como propiedades agrupadas como de solo lectura.
  • Evita la sintaxis de las propiedades agrupadas si también manipulas la propiedad base del propio grupo.

En el caso de una propiedad de tipo valor, como font, las asignaciones agrupadas requieren que la propiedad sea modificable, ya que el motor lee el valor, lo modifica y lo vuelve a escribir. Sin embargo, la posible confusión sigue siendo un problema. Si reasignas todo el font in situ y luego manipulas la propiedad font.bold en otro lugar, el orden de evaluación de los enlaces determina cuál se realiza primero y qué valor de bold resultará de ello.

Exposición de métodos (incluidas las ranuras de Qt)

Se puede acceder a cualquier método de un tipo derivado de ` QObject` desde el código QML si cumple las siguientes condiciones:

  • Un método público marcado con la macro Q_INVOKABLE()
  • Un método que sea una ranura Qt pública

Por ejemplo, la clase ` MessageBoard ` que se muestra a continuación tiene un método ` postMessage() ` marcado con la macro ` Q_INVOKABLE `, así como un método ` refresh() ` que es una ranura pública:

class MessageBoard : public QObject
{
    Q_OBJECT
    QML_ELEMENT

public:
    Q_INVOKABLE bool postMessage(const QString&msg) {
        qDebug() << "Called the C++ method with" << msg;
       return true;
    }

public slots:
    void refresh() {
        qDebug() << "Called the C++ slot";
    }
};

Si se ha establecido una instancia de ` MessageBoard ` como propiedad obligatoria para un archivo ` MyItem.qml`, entonces ` MyItem.qml ` podría invocar los dos métodos tal y como se muestra en los ejemplos siguientes:

C++
int main(int argc, char *argv[]) {
    QGuiApplication app(argc, argv);

    MessageBoard msgBoard;
    QQuickView view;
    view.setInitialProperties({{"msgBoard", &msgBoard}});
    view.setSource(QUrl::fromLocalFile("MyItem.qml"));
    view.show();

    return app.exec();
}
QML
// MyItem.qml
import QtQuick 2.0

Item {
    required property MessageBoard msgBoard

    width: 100; height: 100

    MouseArea {
        anchors.fill: parent
        onClicked: {
            var result = msgBoard.postMessage("Hello from QML")
            console.log("Result of postMessage():", result)
            msgBoard.refresh();
        }
    }
}

Si un método de C++ tiene un parámetro de tipo ` QObject* `, el valor del parámetro se puede pasar desde QML utilizando un objeto ` id ` o un valor de JavaScript ` var ` que haga referencia a dicho objeto.

QML admite la llamada a funciones C++ sobrecargadas. Si hay varias funciones C++ con el mismo nombre pero con argumentos diferentes, se llamará a la función correcta en función del número y los tipos de los argumentos que se proporcionen.

Los valores devueltos por los métodos de C++ se convierten a valores de JavaScript cuando se accede a ellos desde expresiones de JavaScript en QML.

Métodos de C++ y el objeto «this»

Es posible que quieras recuperar un método de C++ de un objeto y llamarlo en otro objeto. Considera el siguiente ejemplo, dentro de un módulo QML llamado « Example »:

C++
class Invokable : public QObject
{
    Q_OBJECT
    QML_ELEMENT
public:
    Invokable(QObject *parent = nullptr) : QObject(parent) {}

    Q_INVOKABLE void invoke() { qDebug() << "invoked on " << objectName(); }
};
QML
import QtQml
import Example

Invokable {
    objectName: "parent"
    property Invokable child: Invokable {}
    Component.onCompleted: child.invoke.call(this)
}

Si cargas el código QML desde un archivo main.cpp adecuado, debería mostrar «invoked on parent». Sin embargo, debido a un error que existe desde hace tiempo, no es así. Históricamente, el objeto «this» de los métodos basados en C++ está indisolublemente vinculado al método. Cambiar este comportamiento en el código existente provocaría errores sutiles, ya que el objeto «this» está implícito en muchos lugares. A partir de Qt 6.5, puedes optar explícitamente por el comportamiento correcto y permitir que los métodos de C++ acepten un objeto «this». Para ello, añade el siguiente pragma a tus documentos Qml:

pragma NativeMethodBehavior: AcceptThisObject

Con esta línea añadida, el ejemplo anterior funcionará como se espera.

Sobrescribir toString()

Si se define un método ` Q_INVOKABLE ` llamado `toString ` (sin argumentos), dicho método se utilizará para convertir el objeto en una cadena, en lugar de la implementación nativa de `toString` de JavaScript.

Exposición de señales

Se puede acceder a cualquier señal pública de un tipo derivado de ` QObject` desde el código QML.

El motor de QML crea automáticamente un controlador de señal para cualquier señal de un tipo derivado de ` QObject` que se utilice desde QML. Los controladores de señal siempre se denominan `on<Signal>`, donde ` <Signal> ` es el nombre de la señal, con la primera letra en mayúscula. Todos los parámetros pasados por la señal están disponibles en el controlador de señal a través de los nombres de los parámetros.

Por ejemplo, supongamos que la clase ` MessageBoard ` tiene una señal ` newMessagePosted() ` con un único parámetro, ` subject`:

class MessageBoard : public QObject
{
    Q_OBJECT
public:
   // ...
signals:
   void newMessagePosted(const QString &subject);
};

Si el tipo ` MessageBoard ` se hubiera registrado en el sistema de tipos de QML, entonces un objeto ` MessageBoard ` declarado en QML podría recibir la señal ` newMessagePosted() ` mediante un controlador de señal denominado ` onNewMessagePosted` y examinar el valor del parámetro ` subject `:

MessageBoard {
    onNewMessagePosted: (subject)=> console.log("New message received:", subject)
}

Al igual que ocurre con los valores de las propiedades y los parámetros de los métodos, un parámetro de señal debe tener un tipo compatible con el motor de QML; véase «Conversión de tipos de datos entre QML y C++». (El uso de un tipo no registrado no generará un error, pero no se podrá acceder al valor del parámetro desde el controlador.)

Las clases pueden tener varias señales con el mismo nombre, pero solo se puede acceder a la última señal como señal QML. Tenga en cuenta que las señales con el mismo nombre pero con parámetros diferentes no se pueden distinguir entre sí.

Véase también « QML Type Registration Macros » y «Definición de tipos QML desde 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.