ViewTransition QML Type (Uncreatable)

Spécifie les éléments en cours de transition dans une vue. En savoir plus...

Remarque : il s'agit d'un type non instanciable. Il ne peut pas être instancié en QML.

• Liste de tous les membres, y compris les membres hérités

Propriétés associées

• destination : point
• index : int
• item : item
• targetIndexes : list
• targetItems : list

Description détaillée

Grâce à ListView et GridView, il est possible de spécifier les transitions à appliquer chaque fois que les éléments de la vue changent à la suite de modifications apportées au modèle de la vue. Ces deux éléments disposent des propriétés suivantes, qui peuvent être configurées pour définir les transitions appropriées à exécuter lors de diverses opérations :

• populate - la transition à appliquer aux éléments créés initialement pour la vue, ou lorsque le modèle change
• add - la transition à appliquer aux éléments ajoutés à la vue après sa création
• remove - la transition à appliquer aux éléments supprimés de la vue
• move - la transition à appliquer aux éléments déplacés au sein de la vue (c’est-à-dire à la suite d’une opération de déplacement dans le modèle)
• displaced - la transition générique à appliquer à tout élément déplacé par une opération d’ajout, de déplacement ou de suppression
• addDisplaced, removeDisplaced et moveDisplaced - les transitions à appliquer lorsque des éléments sont déplacés par des opérations d’ajout, de déplacement ou de suppression, respectivement (celles-ci remplacent la transition générique « displaced » si elles sont spécifiées)

Pour les types de positionneurs Row, Column, Grid et Flow, qui fonctionnent avec des collections d’éléments enfants plutôt qu’avec des modèles de données, les propriétés suivantes sont utilisées à la place :

• populate - la transition à appliquer aux éléments qui ont été ajoutés au positionneur au moment de sa création
• add - la transition à appliquer aux éléments ajoutés au positionneur ou dont le parent a été modifié, ou aux éléments qui sont devenus visible
• move - la transition à appliquer aux éléments qui se sont déplacés au sein du positionneur, y compris lorsqu’ils sont déplacés en raison de l’ajout ou de la suppression d’autres éléments, ou lorsque les éléments sont réorganisés d’une autre manière au sein du positionneur, ou encore lorsqu’ils sont repositionnés en raison du redimensionnement d’autres éléments dans le positionneur

Les transitions de vue ont accès à une propriété attachée ViewTransition qui fournit des détails sur les éléments en cours de transition et sur l’opération qui a déclenché la transition. Étant donné que les transitions de vue s’exécutent une fois par élément, ces détails peuvent être utilisés pour personnaliser chaque transition pour chaque élément individuel.

La propriété attachée ViewTransition fournit les propriétés suivantes spécifiques à l’élément auquel la transition s’applique :

• ViewTransition.item : l’élément en cours de transition
• ViewTransition.index : l’index de cet élément
• ViewTransition.destination : le point (x, y) vers lequel cet élément se déplace dans le cadre de l’opération de vue concernée

De plus, ViewTransition fournit des propriétés spécifiques aux éléments cibles de l’opération ayant déclenché la transition :

• ViewTransition.targetIndexes: les indices des éléments cibles
• ViewTransition.targetItems — les éléments cibles eux-mêmes

(Notez que pour les types de positionneurs Row, Column, Grid et Flow, la transition move ne fournit ces deux détails supplémentaires que lorsque la transition est déclenchée par l’ajout d’éléments à un positionneur.)

Les transitions de vue peuvent être écrites sans faire référence à aucun des attributs énumérés ci-dessus. Ces attributs fournissent simplement des détails supplémentaires utiles pour personnaliser les transitions de vue.

Vous trouverez ci-dessous une introduction aux transitions de vue et aux différentes façons dont la propriété attachée ViewTransition peut être utilisée pour enrichir ces transitions.

Transitions de vue : un exemple simple

Voici un exemple simple d’utilisation des transitions de vue. La vue ci-dessous spécifie des transitions pour les propriétés ` add ` et ` displaced `, qui s’exécuteront lorsque des éléments seront ajoutés à la vue :

ListView {
    width: 240; height: 320
    model: ListModel {}

    delegate: Rectangle {
        width: 100; height: 30
        border.width: 1
        color: "lightsteelblue"
        Text {
            anchors.centerIn: parent
            text: name
        }
    }

    add: Transition {
        NumberAnimation { property: "opacity"; from: 0; to: 1.0; duration: 400 }
        NumberAnimation { property: "scale"; from: 0; to: 1.0; duration: 400 }
    }

    displaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 400; easing.type: Easing.OutBounce }
    }

    focus: true
    Keys.onSpacePressed: model.insert(0, { "name": "Item " + model.count })
}

Lorsque la touche espace est enfoncée, ce qui ajoute un élément au modèle, le nouvel élément apparaît progressivement et s’agrandit en 400 millisecondes au fur et à mesure de son ajout à la vue. De même, tout élément déplacé par l’ajout d’un nouvel élément s’animera vers sa nouvelle position dans la vue en 400 millisecondes, comme spécifié par la transition « displaced ».

Si cinq éléments étaient insérés successivement à l’index 0, l’effet serait le suivant :

Notez que les objets « NumberAnimation » ci-dessus n’ont pas besoin de spécifier une valeur « target » pour animer l’élément concerné. De même, la propriété « NumberAnimation » de l’objet « addTransition » n’a pas besoin de spécifier la valeur « to » pour déplacer l’élément vers sa position correcte dans la vue. En effet, la vue définit implicitement les valeurs « target » et « to » avec les valeurs correctes de l’élément et de sa position finale si ces propriétés ne sont pas explicitement définies.

Dans sa forme la plus simple, une transition de vue peut se contenter d’animer un élément vers sa nouvelle position à la suite d’une opération sur la vue, comme le fait la transition displaced ci-dessus, ou d’animer certaines propriétés d’un élément, comme dans la transition add ci-dessus. De plus, une transition de vue peut utiliser la propriété attachée ViewTransition pour personnaliser le comportement de l’animation en fonction des différents éléments. Voici quelques exemples illustrant comment y parvenir.

Utilisation de la propriété attachée ViewTransition

Comme indiqué, les différentes propriétés de ViewTransition fournissent des détails spécifiques à l’élément individuel faisant l’objet de la transition ainsi qu’à l’opération qui a déclenché celle-ci. Dans l’animation ci-dessus, cinq éléments sont insérés successivement à l’index 0. Lorsque la cinquième et dernière insertion a lieu, ajoutant « Élément 4 » à la vue, la transition add est exécutée une fois (pour l’élément inséré) et la transition displaced est exécutée quatre fois (une fois pour chacun des quatre éléments existants dans la vue).

À ce stade, si l’on examine la transition « displaced » exécutée pour l’élément déplacé vers le bas (« Élément 0 »), les valeurs de la propriété ViewTransition fournies à cette transition seraient les suivantes :

Les listes ViewTransition.targetIndexes et ViewTransition.targetItems fournissent les éléments et les indices de toutes les instances de délégué qui sont les cibles de l’opération concernée. Pour une opération d’ajout, il s’agit de tous les éléments ajoutés à la vue ; pour une opération de suppression, il s’agit de tous les éléments supprimés de la vue, et ainsi de suite. (Notez que ces listes ne contiennent que des références aux éléments créés au sein de la vue ou figurant dans son cache d'éléments ; les cibles qui ne se trouvent pas dans la zone visible de la vue ou dans le cache d'éléments ne seront pas accessibles.)

Ainsi, alors que les valeurs ViewTransition.item, ViewTransition.index et ViewTransition.destination varient pour chaque transition exécutée individuellement, les valeurs ViewTransition.targetIndexes et ViewTransition.targetItems sont identiques pour toutes les transitions « add » et « displaced » déclenchées par une opération d’ajout particulière.

Retard des animations en fonction de l’index

Étant donné que chaque transition de vue est exécutée une fois pour chaque élément concerné par la transition, les propriétés de ViewTransition peuvent être utilisées au sein d’une transition pour définir un comportement personnalisé pour la transition de chaque élément. Par exemple, la transition ListView de l’exemple précédent pourrait utiliser ces informations pour créer un effet de type « ondulation » lors du déplacement des éléments déplacés.

Pour ce faire, il suffit de modifier la transition « displaced » de manière à ce qu’elle retarde l’animation de chaque élément déplacé en fonction de la différence entre son index (fourni par ViewTransition.index) et le premier index supprimé (fourni par ViewTransition.targetIndexes) :

    displaced: Transition {
        id: dispTrans
        SequentialAnimation {
            PauseAnimation {
                duration: (dispTrans.ViewTransition.index -
                        dispTrans.ViewTransition.targetIndexes[0]) * 100
            }
            NumberAnimation { properties: "x,y"; duration: 400; easing.type: Easing.OutBounce }
        }
    }

Chaque élément déplacé retarde son animation de 100 millisecondes supplémentaires, ce qui produit un effet de vague subtil lorsque les éléments sont déplacés par l’ajout, comme ceci :

Animation des éléments vers des positions intermédiaires

La propriété ViewTransition.item fournit une référence à l’élément auquel la transition est appliquée. Elle peut être utilisée pour accéder à n’importe quel attribut de l’élément, aux valeurs d’ property s personnalisées, etc.

Vous trouverez ci-dessous une modification de la transition « displaced » de l’exemple précédent. Elle ajoute un objet ` ParallelAnimation ` contenant des objets ` NumberAnimation ` imbriqués qui font référence à `ViewTransition.item` pour accéder aux valeurs ` x ` et ` y ` de chaque élément au début de leur transition. Cela permet à chaque élément d’effectuer une animation vers une position intermédiaire par rapport à son point de départ pour la transition, avant de se déplacer vers sa position finale dans la vue :

    displaced: Transition {
        id: dispTrans
        SequentialAnimation {
            PauseAnimation {
                duration: (dispTrans.ViewTransition.index -
                        dispTrans.ViewTransition.targetIndexes[0]) * 100
            }
            ParallelAnimation {
                NumberAnimation {
                    property: "x"; to: dispTrans.ViewTransition.item.x + 20
                    easing.type: Easing.OutQuad
                }
                NumberAnimation {
                    property: "y"; to: dispTrans.ViewTransition.item.y + 50
                    easing.type: Easing.OutQuad
                }
            }
            NumberAnimation { properties: "x,y"; duration: 500; easing.type: Easing.OutBounce }
        }
    }

Désormais, un élément déplacé se déplacera d’abord vers une position (20, 50) par rapport à sa position de départ, puis vers sa position finale correcte dans la vue :

Comme l’ NumberAnimation finale ne spécifie pas de valeur « to », la vue définit implicitement cette valeur comme étant la position finale de l’élément dans la vue ; cette dernière animation déplacera donc cet élément à l’endroit correct. Si la transition a besoin de la position finale de l’élément pour effectuer un calcul, celle-ci est accessible via `ViewTransition.destination`.

Au lieu d’utiliser plusieurs NumberAnimations, vous pouvez utiliser une PathAnimation pour animer un élément le long d’un chemin courbe. Par exemple, la transition add de l’exemple précédent pourrait être complétée par une PathAnimation comme suit : pour animer les éléments nouvellement ajoutés le long d’un chemin :

    add: Transition {
        id: addTrans
        NumberAnimation { property: "opacity"; from: 0; to: 1.0; duration: 400 }
        NumberAnimation { property: "scale"; from: 0; to: 1.0; duration: 400 }

        PathAnimation {
            duration: 1000
            path: Path {
                startX: addTrans.ViewTransition.destination.x + 200
                startY: addTrans.ViewTransition.destination.y + 200
                PathCurve { relativeX: -100; relativeY: -50 }
                PathCurve { relativeX: 50; relativeY: -150 }
                PathCurve {
                    x: addTrans.ViewTransition.destination.x
                    y: addTrans.ViewTransition.destination.y
                }
            }
        }
    }

Cela anime les éléments nouvellement ajoutés le long d’un chemin. Notez que chaque chemin est spécifié par rapport au point de destination final de chaque élément, de sorte que les éléments insérés à des indices différents commencent leur chemin à partir de positions différentes :

Gestion des animations interrompues

Une transition de vue peut être interrompue à tout moment si une autre transition de vue doit être appliquée alors que la transition d’origine est en cours. Par exemple, supposons que l’élément A soit inséré à l’index 0 et subisse une transition « add » ; ensuite, l’élément B est inséré à l’index 0 peu après, avant que la transition de l’élément A ne soit terminée. Comme l’élément B est inséré avant l’élément A, il va déplacer ce dernier, ce qui entraîne l’interruption de la transition « add » de l’élément A en cours d’exécution et le lancement d’une transition « displaced » à la place pour cet élément.

Pour les animations simples qui se contentent d’animer le déplacement d’un élément vers sa destination finale, cette interruption ne devrait pas nécessiter de prise en compte particulière. Cependant, si une transition modifie d’autres propriétés, cette interruption peut entraîner des effets secondaires indésirables. Prenons le premier exemple de cette page, reproduit ci-dessous pour plus de clarté :

ListView {
    width: 240; height: 320
    model: ListModel {}

    delegate: Rectangle {
        width: 100; height: 30
        border.width: 1
        color: "lightsteelblue"
        Text {
            anchors.centerIn: parent
            text: name
        }
    }

    add: Transition {
        NumberAnimation { property: "opacity"; from: 0; to: 1.0; duration: 400 }
        NumberAnimation { property: "scale"; from: 0; to: 1.0; duration: 400 }
    }

    displaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 400; easing.type: Easing.OutBounce }
    }

    focus: true
    Keys.onSpacePressed: model.insert(0, { "name": "Item " + model.count })
}

Si plusieurs éléments sont ajoutés en succession rapide, sans attendre la fin de la transition précédente, voici le résultat :

Chaque élément nouvellement ajouté subit une transition « add », mais avant que celle-ci ne puisse se terminer, un autre élément est ajouté, déplaçant ainsi l’élément ajouté précédemment. De ce fait, la transition « add » sur l’élément ajouté précédemment est interrompue et une transition « displaced » est lancée à la place sur cet élément. En raison de cette interruption, les animations « opacity » et « scale » ne se sont pas achevées, ce qui donne lieu à des éléments dont l’opacité et l’échelle sont inférieures à 1,0.

Pour résoudre ce problème, la transition « displaced » doit en outre garantir que les propriétés de l’élément sont définies sur les valeurs finales spécifiées dans la transition « add », en réinitialisant effectivement ces valeurs chaque fois qu’un élément est déplacé. Dans ce cas, cela implique de définir l’opacité et l’échelle de l’élément sur 1,0 :

    displaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 400; easing.type: Easing.OutBounce }

        // ensure opacity and scale values return to 1.0
        NumberAnimation { property: "opacity"; to: 1.0 }
        NumberAnimation { property: "scale"; to: 1.0 }
    }

Désormais, lorsqu’une transition « add » d’un élément est interrompue, son opacité et son échelle sont animées vers 1,0 au moment du déplacement, ce qui évite les effets visuels indésirables observés auparavant :

Le même principe s'applique à toute combinaison de transitions de vue. Un élément ajouté peut être déplacé avant la fin de sa transition d’ajout, ou un élément déplacé peut être supprimé avant la fin de sa transition de déplacement, et ainsi de suite ; la règle générale est donc que chaque transition doit gérer le même ensemble de propriétés.

Restrictions concernant ScriptAction

Lorsqu’une transition de vue est initialisée, toutes les liaisons de propriétés faisant référence à la propriété attachée ViewTransition sont évaluées en vue de la préparation de la transition. En raison de la nature de la structure interne d’une transition de vue, les attributs de la propriété attachée ViewTransition ne sont valides pour l’élément concerné qu’au moment de l’initialisation de la transition, et peuvent ne plus l’être lorsque celle-ci est effectivement exécutée.

Par conséquent, une action de script ( ScriptAction ) au sein d’une transition de vue ne doit pas faire référence à la propriété attachée ViewTransition, car elle pourrait ne pas renvoyer les valeurs attendues au moment où l’ ScriptAction est effectivement appelée. Prenons l’exemple suivant :

ListView {
    width: 240; height: 320
    model: ListModel {
        Component.onCompleted: {
            for (var i=0; i<8; i++)
                append({"name": i})
        }
    }

    delegate: Rectangle {
        width: 100; height: 30
        border.width: 1
        color: "lightsteelblue"
        Text {
            anchors.centerIn: parent
            text: name
        }
        objectName: name
    }

    move: Transition {
        id: moveTrans
        SequentialAnimation {
            ColorAnimation { property: "color"; to: "yellow"; duration: 400 }
            NumberAnimation { properties: "x,y"; duration: 800; easing.type: Easing.OutBack }
            ScriptAction { script: moveTrans.ViewTransition.item.color = "lightsteelblue" }
        }
    }

    displaced: Transition {
        NumberAnimation { properties: "x,y"; duration: 400; easing.type: Easing.OutBounce }
    }

    focus: true
    Keys.onSpacePressed: model.move(5, 1, 3)
}

Lorsque la touche « espace » est enfoncée, trois éléments sont déplacés de l’index 5 vers l’index 1. Pour chaque élément déplacé, la séquence d’ moveTransition s est censée animer la couleur de l’élément vers « jaune », puis l’animer vers sa position finale, avant de ramener la couleur de l’élément à « lightsteelblue » à l’aide d’une ScriptAction. Cependant, une fois exécutée, la transition ne produit pas le résultat escompté :

Seul le dernier élément déplacé reprend la couleur « lightsteelblue » ; les autres restent jaunes. Cela s’explique par le fait que la méthode ` ScriptAction ` n’est exécutée qu’après l’initialisation de la transition ; à ce moment-là, la valeur de `ViewTransition.item` a déjà changé pour désigner un autre élément ; l’élément auquel le script était censé faire référence n’est pas celui détenu par `ViewTransition.item` au moment où la méthode ` ScriptAction ` est effectivement appelée.

Dans ce cas précis, pour éviter ce problème, la vue pourrait définir la propriété à l’aide d’une méthode ` PropertyAction ` à la place :

    move: Transition {
        id: moveTrans
        SequentialAnimation {
            ColorAnimation { property: "color"; to: "yellow"; duration: 400 }
            NumberAnimation { properties: "x,y"; duration: 800; easing.type: Easing.OutBack }
            //ScriptAction { script: moveTrans.ViewTransition.item.color = "lightsteelblue" } BAD!

            PropertyAction { property: "color"; value: "lightsteelblue" }
        }
    }

Lors de l’initialisation de la transition, l’ PropertyAction target sera définie sur la valeur ViewTransition.item correspondante pour la transition et s’exécutera ensuite avec la cible d’élément correcte, comme prévu.

Documentation sur les propriétés associées

ViewTransition.destination : point [read-only attached]

Cette propriété associée contient la position de destination finale de l'élément ayant subi une transition au sein de la vue.

La valeur de cette propriété est un objet de type « point » doté des propriétés « x » et « y ».

ViewTransition.index : int [read-only attached]

Cette propriété associée contient l'index de l'élément en cours de transition.

Notez que si l'élément est déplacé, cette propriété contient l'index vers lequel il est déplacé, et non celui d'où il provient.

ViewTransition.item : item [read-only attached]

Cette propriété associée contient l'élément faisant l'objet de la transition.

ViewTransition.targetIndexes : list [read-only attached]

Cette propriété associée contient une liste des index des éléments de la vue qui sont la cible de l'opération concernée.

Les cibles sont les éléments concernés par l'opération. Pour une opération d'ajout, il s'agit des éléments ajoutés ; pour une opération de suppression, il s'agit des éléments supprimés ; pour une opération de déplacement, il s'agit des éléments déplacés.

Par exemple, si la transition a été déclenchée par une opération d’insertion qui a ajouté deux éléments aux index 1 et 2, cette liste targetIndexes aurait pour valeur [1,2].

Voir également QtQuick::ViewTransition::targetItems.

ViewTransition.targetItems : list [read-only attached]

Cette propriété associée contient la liste des éléments de la vue qui sont la cible de l'opération concernée.

Les cibles sont les éléments concernés par l’opération. Pour une opération d’ajout, il s’agit des éléments ajoutés ; pour une opération de suppression, il s’agit des éléments supprimés ; pour une opération de déplacement, il s’agit des éléments déplacés.

Par exemple, si la transition a été déclenchée par une opération d’insertion qui a ajouté deux éléments aux indices 1 et 2, cette liste targetItems contiendrait ces deux éléments.

Voir également QtQuick::ViewTransition::targetIndexes.