Vinculación de propiedades

A una propiedad de un objeto se le puede asignar un valor estático que permanece constante hasta que se le asigna explícitamente un nuevo valor. Sin embargo, para aprovechar al máximo QML y su soporte integrado para comportamientos dinámicos de objetos, la mayoría de los objetos QML utilizan propiedades.

Los enlaces de propiedades son una característica esencial de QML que permite a los desarrolladores especificar relaciones entre distintas propiedades de objetos. Cuando las dependencias de una propiedad cambian de valor, la propiedad se actualiza automáticamente de acuerdo con la relación especificada.

Entre bastidores, el motor QML supervisa las dependencias de la propiedad (es decir, las variables de la expresión de vinculación). Cuando se detecta un cambio, el motor QML reevalúa la expresión de vinculación y aplica el nuevo resultado a la propiedad.

Vista general

Para crear un enlace de propiedad, se asigna a una propiedad una expresión JavaScript que se evalúa con el valor deseado. En su forma más simple, un enlace puede ser una referencia a otra propiedad. En el siguiente ejemplo, la altura del elemento azul Rectangle está vinculada a la altura de su elemento principal:

Rectangle {
    width: 200; height: 200

    Rectangle {
        width: 100
        height: parent.height
        color: "blue"
    }
}

Cada vez que la altura del rectángulo padre cambia, la altura del rectángulo azul se actualiza automáticamente para tener el mismo valor.

Un enlace puede contener cualquier expresión o sentencia JavaScript válida, ya que QML utiliza un motor 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 posibles enlaces 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.width depende de bottomRect.width y column.width
• topRect.height depende de column.height
• bottomRect.color depende de myTextInput.text.length

Además, se reevaluará cualquier propiedad a la que se haga referencia dentro de una función JavaScript que se utilice a su vez como enlace. Por ejemplo, en el siguiente fragmento, cada vez que cambie la propiedad enabled de Rectangle, se reevaluarán los vínculos 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 una vinculación es demasiado compleja (por ejemplo, si implica varias líneas o bucles imperativos), podría indicar que la vinculación se está utilizando para algo más que para describir las 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 tienen enlaces complejos, o al menos factorizar el enlace en una función separada. Como regla general, los usuarios no deben confiar 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 cuando es necesario. Sin embargo, si posteriormente se asigna a la propiedad un valor estático desde una sentencia JavaScript, se eliminará la vinculación.

Por ejemplo, el siguiente Rectangle asegura inicialmente que su height es siempre el doble que su width. Sin embargo, al pulsar la tecla de espacio, el valor actual de width*3 se asignará a height como valor estático. Después de eso, el height permanecerá fijo en este valor, incluso si el width cambia. La asignación del valor estático elimina la vinculación.

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, entonces esto no es un problema. Sin embargo, si la intención es establecer una nueva relación entre width y height, entonces la nueva expresión de vinculación debe ser envuelta en la función Qt.binding() en su lugar:

import QtQuick 2.0

Rectangle {
    width: 100
    height: width * 2

    focus: true
    Keys.onSpacePressed: {
        height = Qt.binding(function() { return width * 3 })
    }
}

Ahora, después de pulsar la tecla espacio, la altura del rectángulo continuará actualizándose automáticamente para ser siempre tres veces su anchura.

Depuración de la sobreescritura de bindings

Una causa común de errores en las aplicaciones QML es la sobreescritura accidental de bindings con valores estáticos de sentencias JavaScript. Para ayudar a los desarrolladores a localizar problemas de este tipo, el motor QML es capaz de emitir mensajes cada vez que se pierde una vinculación debido a asignaciones imperativas.

Para generar estos mensajes, es necesario activar la salida informativa para la categoría de registro qt.qml.binding.removal, por ejemplo, llamando a:

QLoggingCategory::setFilterRules(QStringLiteral("qt.qml.binding.removal.info=true"));

Consulte la documentación de QLoggingCategory para obtener más información sobre la activación de la salida de las categorías de registro.

Tenga en cuenta que en algunas circunstancias es perfectamente razonable sobrescribir las vinculaciones. Cualquier mensaje generado por el motor QML debe ser tratado como una ayuda para el diagnóstico, y no necesariamente como evidencia de un problema sin más investigación.

Uso de this con Property Binding

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 es útil para resolver ambigüedades con nombres de 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 a la anchura de Item, no a la anchura de Rectangle. Para vincular height de Rectangle a su propio width, la expresión de vinculación debe referirse explícitamente 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
    }
}