Binding QML Type
Permite crear enlaces de propiedades de forma arbitraria. Más...
| Import Statement: | import QtQml |
Propiedades
- delayed : bool
- property : string
- restoreMode : enumeration
- target : QtObject
- value : var
- when : bool
Descripción detallada
En QML, los enlaces de propiedades dan lugar a una dependencia entre las propiedades de diferentes objetos.
Enlace a una propiedad inaccesible
A veces es necesario vincular la propiedad de un objeto a la de otro objeto que no ha sido instanciado directamente por QML, como por ejemplo una propiedad de una clase exportada a QML desde C++. Puedes utilizar el tipo Binding para establecer esta dependencia, vinculando cualquier valor a la propiedad de cualquier objeto.
Por ejemplo, en una aplicación en C++ que asigna la propiedad «app.enteredText» a QML, se puede utilizar Binding para actualizar la propiedad enteredText.
TextEdit { id: myTextField; text: "Please type here..." }
Binding { app.enteredText: myTextField.text }Cuando cambia « text », la propiedad de C++ « enteredText » se actualizará automáticamente.
Enlaces condicionales
En algunos casos, es posible que desees modificar el valor de una propiedad cuando se cumpla una determinada condición, pero dejarlo sin modificar en caso contrario. A menudo, no es posible hacerlo con enlaces directos, ya que hay que proporcionar valores para todas las ramas posibles.
Por ejemplo, el fragmento de código siguiente genera una advertencia cada vez que se suelta el ratón. Esto se debe a que el valor del enlace no está definido cuando no se pulsa el ratón.
// produces warning: "Unable to assign [undefined] to double value"
targetProperty: if (mouse.pressed) mouse.mouseXEl tipo «Binding» puede evitar esta advertencia.
Binding on targetProperty {
when: mouse.pressed
value: mouse.mouseX
}El tipo «Binding» restaura cualquier enlace directo establecido previamente en la propiedad.
Sin embargo, el enlace a la propiedad value de Binding sigue evaluándose de forma incondicional, incluso cuando when es false.
Esto podría provocar advertencias cuando, por ejemplo, el Binding se utiliza para evitar que un valor sea ` null`:
Binding on targetProperty {
when: root.object !== null
// produces warning: "TypeError: Cannot read property 'someProperty' of null"
value: root.object.someProperty
}Hay dos formas de evitar este problema:
- Si el objetivo tiene un «
id», puedes utilizar la sintaxis descrita en Multiple targets in one Binding, lo que también hace que la expresión de enlace solo se ejecute cuando el «Binding» esté habilitado:Binding { when: root.object !== null root.targetProperty: root.object.someProperty } - Puedes repetir la comprobación en el enlace y salir antes de tiempo:
Binding on targetProperty { when: root.object !== null value: { if (root.object === null) return return root.object.someProperty } }
Varios objetivos en un único elemento «Binding»
Puedes especificar varios enlaces al mismo objeto en un único elemento Binding:
Text {
id: t1
}
Binding {
t1 {
color: "#00FF00"
text: "green text"
}
}También puedes especificar varios enlaces con diferentes objetos de destino en un único elemento «Binding»:
Text {
id: t1
}
Text {
id: t2
}
Binding {
t1.text: "Foo"
t2.text: "Bar"
}Véase también Qt Qml.
Documentación de propiedades
delayed : bool
Esta propiedad determina si el enlace debe retrasarse.
Un enlace diferido no actualizará inmediatamente el destino, sino que esperará hasta que se haya vaciado la cola de eventos. Esto puede utilizarse como optimización o para evitar que se asignen valores intermedios.
Binding {
contactName.text.value: givenName + " " + familyName
when: list.ListView.isCurrentItem
delayed: true
}Nota: El uso de la propiedad «delayed» conlleva un coste de tiempo de ejecución, ya que el elemento «Binding» tiene que crear un proxy para el valor, de modo que pueda retrasar su aplicación al destino real. Al utilizar las propiedades « target » y « property », este coste es menor, ya que la propiedad « value » puede reutilizarse como proxy. Al utilizar el formulario que se muestra arriba, «Binding» asignará un objeto independiente con un metaobjeto dinámico para almacenar los valores del proxy.
property : string
La propiedad que se va a actualizar.
Puede tratarse de una propiedad de grupo si la expresión da como resultado el acceso a una propiedad de tipo valor. Por ejemplo:
Item {
id: item
property rect rectangle: Qt.rect(0, 0, 200, 200)
}
Binding {
target: item
property: "rectangle.x"
value: 100
}Solo es necesario utilizar esta propiedad si no se puede especificar el destino del enlace de forma declarativa. El siguiente fragmento de código es equivalente al enlace anterior, pero más compacto:
Binding { item.rectangle.x: 100 }restoreMode : enumeration
Esta propiedad permite indicar si se debe restablecer el valor original y de qué forma cuando se desactiva el enlace.
Los valores posibles son:
| Constante | Descripción |
|---|---|
Binding.RestoreNone | El valor original no se restaura en absoluto |
Binding.RestoreBinding | El valor original se restaura si se trataba de otro enlace. En ese caso, el enlace anterior vuelve a estar activo. |
Binding.RestoreValue | El valor original se restablece si se trataba de un valor simple en lugar de un enlace. |
Binding.RestoreBindingOrValue | El valor original siempre se restablece. |
El valor por defecto es Binding.RestoreBindingOrValue.
Nota: Esta propiedad existe por motivos de compatibilidad con versiones anteriores de Qt. No la utilices en código nuevo.
target : QtObject
El objeto que se va a actualizar. Debes utilizar esta propiedad si el objetivo del enlace no tiene un atributo « id » (por ejemplo, cuando el objetivo es un singleton). En caso contrario, los dos fragmentos de código siguientes son equivalentes:
Binding { contactName.text: name }Binding {
target: contactName
property: "text"
value: name
}El primero es mucho más compacto, pero no permite sustituir el objeto o la propiedad de destino en tiempo de ejecución. Con el segundo sí es posible.
value : var
El valor que se va a asignar al objeto y a la propiedad de destino. Puede ser una constante (lo cual no resulta muy útil) o una expresión vinculada.
Solo es necesario utilizar esta propiedad si no se puede especificar el destino del enlace de forma declarativa. En caso contrario, se puede establecer el enlace directamente con el destino.
when : bool
Esta propiedad se mantiene cuando el enlace está activo. Debe establecerse en una expresión que devuelva «true» cuando se desee que el enlace esté activo.
Binding {
contactName.text: name
when: list.ListView.isCurrentItem
}De forma predeterminada, cualquier enlace o valor establecido anteriormente se restaura cuando el enlace pasa a estar inactivo. Puedes personalizar el comportamiento de restauración mediante la propiedad restoreMode.
Véase también « restoreMode ».
© 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.