Liaison de propriété

La liaison de propriété est une manière déclarative de spécifier la valeur d'une propriété. La liaison permet à une valeur de propriété d'être exprimée comme une expression JavaScript qui définit la valeur par rapport à d'autres valeurs de propriété ou à des données accessibles dans l'application. La valeur de propriété est automatiquement mise à jour si les autres propriétés ou les valeurs des données changent.

Les liaisons de données sont implicitement créées dans QML lorsqu'une propriété est attribuée à une expression JavaScript. Le code QML ci-dessous utilise deux liaisons de propriété pour relier la taille du rectangle à celle de otherItem.

 Rectangle {
     width: otherItem.width
     height: otherItem.height
 }

QML étend un moteur JavaScript conforme aux standards, donc n'importe quelle expression JavaScript valide peut être utilisée comme une liaison de propriété. Les liaisons peuvent accéder aux propriétés de l'objet, appeler des fonctions et même utiliser les objets natifs à JavaScript tels que Date et Math. Assigner une valeur constante à une propriété peut même être considéré comme une liaison - Après tout, une constante est une expression JavaScript valide ! - Voici quelques exemples de liaisons plus complexes :

 Rectangle {
     function calculateMyHeight() {
         return Math.max(otherItem.height, thirdItem.height);
     }
 
     anchors.centerIn: parent
     width: Math.min(otherItem.width, 10)
     height: calculateMyHeight()
     color: { if (width > 10) "blue"; else "red" }
 }

Alors que, syntaxiquement, les liaisons peuvent être de complexité arbitraire, si une liaison commence à devenir trop complexe - tel que l'utilisation de plusieurs lignes ou une boucle impérative - il peut être préférable de remanier entièrement le composant ou au moins le facteur hors de la liaison dans une fonction distincte.

Changements de liaison

L'élément PropertyChanges peut être utilisé au sein d'un changement d'état pour modifier les liaisons sur les propriétés.

Cet exemple modifie la liaison de propriété de la largeur de Rectangle pour devenir otherItem.height quand on arrive dans l'état « square ». Lorsqu'il retournera à son état par défaut, la liaison de propriété originale de la largeur aura été restaurée.

 Rectangle {
     id: rectangle
     width: otherItem.width
     height: otherItem.height
 
     states: State {
         name: "square"
         PropertyChanges {
             target: rectangle
             width: otherItem.height
         }
     }
 }

Effets de l'assignation de propriété en JavaScript

Assigner une valeur de propriété depuis JavaScript ne crée pas une liaison de propriété. Par exemple :

 Rectangle {
 
     Component.onCompleted: {
         width = otherItem.width;
     }
 }

Au lieu de créer une liaison de propriété, cela fixe simplement la largeur width du Rectangle à la valeur de other.width dès que le code JavaScript est appelé. Voir assignation de propriété vs liaison de propriété pour plus de détails.

Notez également qu'assigner une valeur à une propriété qui est déjà liée supprimera la liaison. Une propriété ne peut avoir qu'une valeur à la fois et si un code fixe explicitement cette valeur, la liaison sera supprimée. Le Rectangle dans l'exemple ci-dessous aura une largeur de 13, indépendamment de la largeur de otherItem.

 Rectangle {
     width: otherItem.width
 
     Component.onCompleted: {
         width = 13;
     }
 }

Il n'est pas possible de créer une liaison de propriété directement dans le code impératif JavaScript, bien qu'il soit possible de mettre en place un objet Binding (voir plus bas).

Liaison d'élément

La syntaxe implicite de la liaison montrée précédemment est facile à utiliser et fonctionne parfaitement pour la plupart des utilisations de liaisons. Dans certains cas avancés, il est nécessaire de créer les liaisons explicitement en utilisant l'élément Binding.

Par exemple, pour lier une propriété exposée depuis le C++ (system.brightness) vers une valeur provenant de QML (slider.value), vous pourriez utiliser l'élément Binding comme suit :

 Binding {
     target: system
     property: "brightness"
     value: slider.value
 }

Remerciements

Merci à Dimitry Ernot pour la traduction ainsi qu'à Jonathan Courtois et Claude Leloup pour leur relecture !