Enlace de propiedades
A la propiedad de un objeto se le puede asignar un valor estático que permanece constante hasta que se le asigne explícitamente un nuevo valor. Sin embargo, para sacar el máximo partido a QML y a su soporte integrado para comportamientos dinámicos de los objetos, la mayoría de los objetos QML utilizan enlaces de propiedades.
Los enlaces de propiedades son una característica fundamental de QML que permite a los desarrolladores especificar relaciones entre diferentes propiedades de los objetos. Cuando el valor de las dependencias de una propiedad cambia, la propiedad se actualiza automáticamente según la relación especificada.
En segundo plano, el motor de QML supervisa las dependencias de la propiedad (es decir, las variables de la expresión de enlace). Cuando se detecta un cambio, el motor de QML reevalúa la expresión de enlace y aplica el nuevo resultado a la propiedad.
Descripción general
Para crear un enlace de propiedad, se asigna a una propiedad una expresión JavaScript cuyo resultado es el valor deseado. En su forma más sencilla, un enlace puede ser una referencia a otra propiedad. Veamos el siguiente ejemplo, en el que la altura del elemento azul Rectangle está vinculada a la altura de su elemento padre:
Cada vez que cambia la altura del rectángulo padre, la altura del rectángulo azul se actualiza automáticamente para que tenga el mismo valor.
Un enlace puede contener cualquier expresión o instrucción válida de JavaScript, ya que QML utiliza un motor de JavaScript compatible con los estándares. Los enlaces pueden acceder a propiedades de objetos, llamar a métodos y utilizar objetos JavaScript integrados, como Date y Math. A continuación se muestran otros enlaces posibles para el ejemplo anterior:
height: parent.height / 2
height: Math.min(parent.width, parent.height)
height: parent.height > 100 ? parent.height : parent.height/2
height: {
if (parent.height > 100)
return parent.height
else
return parent.height / 2
}
height: someMethodThatReturnsHeight()A continuación se muestra un ejemplo más complejo en el que intervienen más objetos y tipos:
Column {
id: column
width: 200
height: 200
Rectangle {
id: topRect
width: Math.max(bottomRect.width, parent.width/2)
height: (parent.height / 3) + 10
color: "yellow"
TextInput {
id: myTextInput
text: "Hello QML!"
}
}
Rectangle {
id: bottomRect
width: 100
height: 50
color: myTextInput.text.length <= 10 ? "red" : "blue"
}
}En el ejemplo anterior,
topRect.widthdepende de «bottomRect.width» ycolumn.widthtopRect.heightdepende decolumn.heightbottomRect.colordepende demyTextInput.text.length
Además, cualquier propiedad a la que se haga referencia dentro de una función de JavaScript que, a su vez, se utilice como enlace, se volverá a evaluar. Por ejemplo, en el fragmento de código siguiente, cada vez que cambie la propiedad « enabled » de « Rectangle », se volverán a evaluar los enlaces de las propiedades « x » y « y »:
Rectangle {
x: rectPosition()
y: rectPosition()
width: 200
height: 200
color: "lightblue"
function rectPosition() {
return enabled ? 0 : 100
}
}Sintácticamente, se permite que los enlaces tengan una complejidad arbitraria. Sin embargo, si un enlace es excesivamente complejo —por ejemplo, si implica varias líneas o bucles imperativos—, podría indicar que se está utilizando para algo más que describir relaciones entre propiedades. Los enlaces complejos pueden reducir el rendimiento, la legibilidad y la facilidad de mantenimiento del código. Puede ser una buena idea rediseñar los componentes que tengan enlaces complejos o, al menos, extraer el enlace a una función independiente. Como norma general, los usuarios no deben basarse en el orden de evaluación de los enlaces.
Creación de enlaces de propiedades desde JavaScript
Una propiedad con un enlace se actualiza automáticamente según sea necesario. Sin embargo, si posteriormente se le asigna a la propiedad un valor estático mediante una instrucción de JavaScript, el enlace se eliminará.
Por ejemplo, el « Rectangle » que se muestra a continuación garantiza inicialmente que su « height » sea siempre el doble de su « width ». Sin embargo, al pulsar la tecla de espacio, el valor actual de « width*3 » se asignará a « height » como valor estático. A partir de ese momento, el « height » permanecerá fijo en este valor, incluso si cambia el « width ». La asignación del valor estático elimina el enlace.
import QtQuick 2.0
Rectangle {
width: 100
height: width * 2
focus: true
Keys.onSpacePressed: {
height = width * 3
}
}Si la intención es dar al rectángulo una altura fija y detener las actualizaciones automáticas, esto no supone ningún problema. Sin embargo, si la intención es establecer una nueva relación entre width y height, la nueva expresión de enlace debe incluirse dentro de la función Qt.binding():
import QtQuick 2.0
Rectangle {
width: 100
height: width * 2
focus: true
Keys.onSpacePressed: {
height = Qt.binding(function() { return width * 3 })
}
}Ahora, tras pulsar la tecla de espacio, la altura del rectángulo seguirá actualizándose automáticamente para que sea siempre tres veces su anchura.
Depuración de la sobrescritura de enlaces
Una causa habitual de errores en las aplicaciones QML es la sobrescritura accidental de enlaces con valores estáticos procedentes de sentencias de JavaScript. Para ayudar a los desarrolladores a localizar problemas de este tipo, el motor QML puede emitir mensajes cada vez que se pierde un enlace debido a asignaciones imperativas.
Para generar dichos mensajes, es necesario habilitar la salida informativa de la categoría de registro « qt.qml.binding.removal », por ejemplo, llamando a:
QLoggingCategory::setFilterRules(QStringLiteral("qt.qml.binding.removal.info=true"));Consulta la documentación de « QLoggingCategory » para obtener más información sobre cómo habilitar la salida de las categorías de registro.
Ten en cuenta que, en determinadas circunstancias, es perfectamente razonable sobrescribir los enlaces. Cualquier mensaje generado por el motor QML debe considerarse una ayuda para el diagnóstico y no necesariamente una indicación de que existe un problema sin que se haya realizado una investigación más exhaustiva.
Uso de « this » con enlaces de propiedades
Al crear un enlace de propiedad desde JavaScript, se puede utilizar la palabra clave « this » para hacer referencia al objeto que recibe el enlace. Esto resulta útil para resolver ambigüedades con los nombres de las propiedades.
Por ejemplo, el controlador « Component.onCompleted » que se muestra a continuación está definido dentro del ámbito de « Item ». En este ámbito, « width » hace referencia al ancho de « Item », no al de « Rectangle ». Para vincular la propiedad « height » de « Rectangle » a su propio « width », la expresión de enlace debe hacer referencia explícita a « this.width » (o, alternativamente, a « rect.width »):
Item {
width: 500
height: 500
Rectangle {
id: rect
width: 100
color: "yellow"
}
Component.onCompleted: {
rect.height = Qt.binding(function() { return this.width * 2 })
console.log("rect.height = " + rect.height) // prints 200, not 1000
}
}Nota: El valor de this no está definido fuera de los enlaces de propiedades. Consulte Restricciones del entorno de JavaScript para obtener más detalles.
Véase también «Posicionamiento con anclajes».
© 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.