Tipos adjuntos de QML
Las propiedades y señales adjuntas son un mecanismo que permite anotar objetos con propiedades o señales adicionales que no forman parte de su tipo base. Se accede a las propiedades adjuntas mediante una sintaxis con espacio de nombres que identifica el tipo que proporciona dichas propiedades.
Descripción general
Algunos tipos tienen propiedades o señales que pueden adjuntarse a otros objetos, lo que proporciona funcionalidad adicional sin necesidad de herencia. Se accede a una propiedad o señal adjunta anteponiendo al nombre de la propiedad o señal el nombre del tipo que la adjunta.
Por ejemplo, el tipo ` ListView ` tiene una propiedad adjunta llamada ` isCurrentItem ` a la que se puede acceder en cualquier elemento dentro del delegado de ` ListView`:
ListView {
width: 240
height: 320
model: 3
delegate: Rectangle {
width: 100
height: 30
color: ListView.isCurrentItem ? "red" : "yellow"
}
}En este caso, ` ListView.isCurrentItem ` es una propiedad adjunta que ` ListView` pone a disposición de cada elemento del delegado.
Propiedades adjuntas
Las propiedades adjuntas permiten añadir propiedades a objetos que, de otro modo, estarían definidos por un tipo base. Los valores de las propiedades se almacenan externamente al objeto y se accede a ellos a través del nombre del tipo que las adjunta.
Algunos ejemplos comunes son:
- ListView propiedades adjuntas (
isCurrentItem,view) - GridView propiedades adjuntas
- Keys propiedades adjuntas para la gestión de eventos del teclado
- Component propiedades adjuntas (
onCompleted,onDestruction)
Señales asociadas
Al igual que las propiedades asociadas, las señales asociadas permiten a los tipos proporcionar controladores de señales adicionales a los objetos. Se utilizan habitualmente para eventos del ciclo de vida.
Por ejemplo, el tipo «Component» proporciona señales asociadas:
Rectangle {
Component.onCompleted: {
console.log("Rectangle creation completed")
}
Component.onDestruction: {
console.log("Rectangle is being destroyed")
}
}Creación de propiedades asociadas en C++
Para crear propiedades asociadas para tus propios tipos desde C++, debes:
- Crear una clase de propiedades asociadas que herede de QObject
- Implementar las propiedades adjuntas en esta clase
- Añadir la macro `
QML_ATTACHED` a tu tipo principal - Implementar un método estático `
qmlAttachedProperties()`
Ejemplo:
class MyAttachedType : public QObject
{
Q_OBJECT
Q_PROPERTY(int value READ value WRITE setValue NOTIFY valueChanged)
QML_ANONYMOUS
public:
MyAttachedType(QObject *parent = nullptr) : QObject(parent) {}
int value() const { return m_value; }
void setValue(int value)
{
if (m_value != value) {
m_value = value;
emit valueChanged();
}
}
signals:
void valueChanged();
private:
int m_value = 0;
};
class MyType : public QObject
{
Q_OBJECT
QML_ELEMENT
QML_ATTACHED(MyAttachedType)
public:
static MyAttachedType *qmlAttachedProperties(QObject *object)
{
return new MyAttachedType(object);
}
};Uso en QML:
Item {
MyType.value: 42
}Si el tipo de adjuntado (en este caso, `MyType `) no hace más que adjuntar propiedades a otros objetos, puedes expresarlo como una única clase:
class MyType : public QObject
{
Q_OBJECT
Q_PROPERTY(int value READ value WRITE setValue NOTIFY valueChanged)
QML_ELEMENT
QML_ATTACHED(MyType)
public:
static MyType *qmlAttachedProperties(QObject *object)
{
return new MyType(object);
}
MyType(QObject *parent = nullptr) : QObject(parent) {}
int value() const { return m_value; }
void setValue(int value)
{
if (m_value != value) {
m_value = value;
emit valueChanged();
}
}
signals:
void valueChanged();
private:
int m_value = 0;
};Cuándo utilizar propiedades adjuntas
Las propiedades adjuntas resultan útiles cuando:
- Se desea añadir información específica del contexto a los elementos (como «
isCurrentItem» de ListView) - Las propiedades pertenecen lógicamente a un contenedor o contexto, más que al propio elemento
- Se desea evitar sobrecargar los tipos base con propiedades especializadas
Véase también Tipos de objetos QML, El sistema de tipos de QML 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.