ViewTransition QML Type

Spécifie les éléments en cours de transition dans une vue. Plus d'informations...

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

Propriétés attachées

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

Description détaillée

Avec ListView et GridView, il est possible de spécifier des transitions qui doivent être appliquées chaque fois que les éléments de la vue changent à la suite de modifications du modèle de la vue. Ils ont tous deux les propriétés suivantes qui peuvent être définies pour les transitions appropriées à exécuter pour 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 qui sont supprimés de la vue
• move - la transition à appliquer aux éléments qui sont déplacés dans 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 à tous les éléments déplacés par une opération d'ajout, de déplacement ou de suppression.
• addDisplaced removeDisplaced et - les transitions à appliquer lorsque des éléments sont déplacés par des opérations d'ajout, de déplacement ou de suppression, respectivement (ces transitions remplacent la transition générique déplacée si elle est spécifiée). moveDisplaced

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 qui sont ajoutés ou reparentés au positionneur, ou aux éléments qui sont devenus des objets. visible
• move - la transition à appliquer aux éléments qui ont été déplacés dans le positionneur, y compris lorsqu'ils sont déplacés en raison de l'ajout ou du retrait d'autres éléments, ou lorsque les éléments sont réarrangés d'une autre manière dans le positionneur, ou lorsque les éléments 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. Comme les transitions de vue sont exécutées une fois par élément, ces détails peuvent être utilisés pour personnaliser chaque transition pour chaque élément individuel.

La propriété ViewTransition attached fournit les propriétés suivantes, spécifiques à l'élément auquel la transition est appliquée :

• ViewTransition.item - l'élément qui fait l'objet de la transition
• ViewTransition.index - l'index de cet élément
• ViewTransition.destination - le point (x,y) vers lequel l'élément se déplace pour l'opération de visualisation concernée.

En outre, ViewTransition fournit des propriétés spécifiques aux éléments qui sont la cible de l'opération qui a déclenché la transition :

• ViewTransition.targetIndexes - les index 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.

Voici une introduction aux transitions de vue et à la manière dont la propriété attachée ViewTransition peut être utilisée pour augmenter les transitions de vue.

Transitions de vue : un exemple simple

Voici un exemple simple de l'utilisation des transitions de vue. La vue ci-dessous spécifie des transitions pour les propriétés add et displaced, qui seront exécutées 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 l'on appuie sur la touche Espace pour ajouter un élément au modèle, le nouvel élément s'affiche en fondu et augmente d'échelle en 400 millisecondes au fur et à mesure qu'il est ajouté à la vue. De même, tout élément déplacé par l'ajout d'un nouvel élément s'animera jusqu'à 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 :

Remarquez que les objets NumberAnimation ci-dessus n'ont pas besoin de spécifier un target pour animer l'élément approprié. De même, l'objet NumberAnimation dans l'objet addTransition n'a pas besoin de spécifier la valeur to pour déplacer l'élément à 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 la position finale de l'élément si ces propriétés ne sont pas explicitement définies.

Dans sa forme la plus simple, une transition de vue peut simplement animer un élément vers sa nouvelle position à la suite d'une opération de vue, comme le fait la transition displaced ci-dessus, ou animer certaines propriétés de l'élément, comme dans la transition add ci-dessus. En outre, une transition de vue peut utiliser la propriété attachée ViewTransition pour personnaliser le comportement de l'animation pour différents éléments. Voici quelques exemples de la manière dont cela peut être réalisé.

Utilisation de la propriété ViewTransition attached

Comme indiqué, les différentes propriétés ViewTransition fournissent des détails spécifiques à l'élément individuel faisant l'objet de la transition, ainsi que l'opération qui a déclenché la transition. 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'"é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 nous examinons la transition displaced qui a été exécutée pour l'élément déplacé le plus 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 index 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 contiendront que des références à des éléments qui ont été créés dans la vue ou dans ses éléments mis en cache ; 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 individuelle exécutée, les valeurs ViewTransition.targetIndexes et ViewTransition.targetItems sont les mêmes pour chaque transition add et displaced déclenchée par une opération d'ajout particulière.

Retarder les animations en fonction de l'index

Étant donné que chaque transition de vue est exécutée une fois pour chaque élément affecté par la transition, les propriétés 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, le site ListView de l'exemple précédent pourrait utiliser ces informations pour créer un effet d'ondulation sur le mouvement des éléments déplacés.

Pour ce faire, modifiez la transition displaced de manière à retarder 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 subtil effet d'ondulation lorsque les éléments sont déplacés par l'ajout, comme ceci :

Animation d'éléments à des positions intermédiaires

La propriété ViewTransition.item donne une référence à l'élément auquel la transition est appliquée. Elle peut être utilisée pour accéder à tous les attributs de l'élément, aux valeurs personnalisées de property, etc.

Voici une modification de la transition displaced de l'exemple précédent. Elle ajoute un ParallelAnimation avec 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 leurs transitions. Cela permet à chaque élément de s'animer jusqu'à une position intermédiaire par rapport à son point de départ pour la transition, avant de s'animer jusqu'à 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 de (20, 50) par rapport à sa position de départ, puis vers sa position finale, correcte, dans la vue :

Étant donné que l'adresse NumberAnimation ne spécifie pas de valeur to, la vue définit implicitement cette valeur à la position finale de l'élément dans la vue, et cette dernière animation déplacera donc l'élément à la bonne place. Si la transition nécessite la position finale de l'élément pour un certain calcul, celle-ci est accessible via ViewTransition.destination.

Au lieu d'utiliser plusieurs NumberAnimations, vous pouvez utiliser PathAnimation pour animer un élément sur une trajectoire 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'une trajectoire :

    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
                }
            }
        }
    }

Cette méthode permet d'animer les éléments nouvellement ajoutés le long d'un chemin. Notez que chaque chemin est spécifié par rapport au point de destination finale de chaque élément, de sorte que les éléments insérés à des index 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 originale est en cours. Par exemple, supposons que l'élément A soit inséré à l'index 0 et subisse une transition "ajouter" ; ensuite, l'élément B est inséré à l'index 0 dans une succession rapide 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 déplace l'élément A, ce qui oblige la vue à interrompre la transition "ajout" de l'élément A à mi-chemin et à démarrer une transition "déplacement" sur l'élément A à la place.

Pour les animations simples qui se contentent d'animer le mouvement d'un élément vers sa destination finale, il est peu probable que cette interruption nécessite une attention 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, répété ci-dessous pour plus de commodité :

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 d'une transition précédente, voici le résultat :

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

Pour remédier à ce problème, la transition displaced doit en outre s'assurer que les propriétés de l'élément sont définies sur les valeurs finales spécifiées dans la transition add, ce qui permet de réinitialiser ces valeurs chaque fois qu'un élément est déplacé. Dans ce cas, cela signifie que l'opacité et l'échelle de l'élément doivent être fixées à 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, lorsque la transition add d'un élément est interrompue, son opacité et son échelle sont ramenées à 1,0 lors du déplacement, ce qui évite les effets visuels erronés précédents :

Le même principe s'applique à toute combinaison de transitions de vue. Un élément ajouté peut être déplacé avant que sa transition d'ajout ne se termine, ou un élément déplacé peut être supprimé avant que sa transition de déplacement ne se termine, et ainsi de suite ; la règle de base 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 qui font référence à la propriété attachée ViewTransition sont évaluées en préparation de la transition. En raison de la nature de la construction interne d'une transition de vue, les attributs de la propriété ViewTransition attached ne sont valables que pour l'élément concerné lors de l'initialisation de la transition, et peuvent ne pas être valables lorsque la transition est effectivement exécutée.

Par conséquent, une adresse ScriptAction dans une transition de vue ne doit pas faire référence à la propriété attachée ViewTransition, car elle peut ne pas faire référence aux valeurs attendues au moment où l'adresse ScriptAction est effectivement invoqué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 l'on appuie sur la touche espace, trois éléments sont déplacés de l'index 5 à l'index 1. Pour chaque élément déplacé, la séquence moveTransition anime vraisemblablement la couleur de l'élément en "jaune", puis l'anime jusqu'à sa position finale, puis change à nouveau la couleur de l'élément en "bleu acier" à l'aide d'une séquence ScriptAction. Cependant, lorsqu'elle est exécutée, la transition ne produit pas le résultat escompté :

Seul le dernier élément déplacé reprend la couleur "bleu acier" ; les autres restent jaunes. Cela est dû au fait que ScriptAction n'est exécuté qu'après l'initialisation de la transition, alors que la valeur de ViewTransition.item a changé pour faire référence à un élément différent ; l'élément auquel le script avait l'intention de faire référence n'est pas celui détenu par ViewTransition.item au moment où ScriptAction est effectivement invoqué.

Dans ce cas, pour éviter ce problème, la vue pourrait définir la propriété à l'aide d'un PropertyAction:

    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" }
        }
    }

Lorsque la transition est initialisée, la propriété PropertyAction target sera définie sur le ViewTransition.item correspondant à la transition et s'exécutera plus tard avec la cible correcte, comme prévu.

Documentation sur les propriétés attachées

ViewTransition.destination : point [read-only]

Cette propriété jointe contient la position de destination finale de l'élément transféré dans la vue.

La valeur de cette propriété est un point avec les propriétés x et y.

ViewTransition.index : int [read-only]

Cette propriété jointe contient l'index de l'élément qui fait l'objet d'une transition.

Notez que si l'élément est déplacé, cette propriété contient l'index vers lequel l'élément est déplacé, et non à partir duquel il est déplacé.

ViewTransition.item : item [read-only]

Cette propriété jointe contient l'élément qui fait l'objet de la transition.

ViewTransition.targetIndexes : list [read-only]

Cette propriété jointe 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 qui font l'objet de l'opération. Dans le cas d'une opération d'ajout, il s'agit des éléments ajoutés ; dans le cas d'une opération de suppression, il s'agit des éléments supprimés ; dans le cas d'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, la liste targetIndexes aura la valeur [1,2].

Voir également QtQuick::ViewTransition::targetItems.

ViewTransition.targetItems : list [read-only]

Cette propriété jointe 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 qui font l'objet de l'opération. Dans le cas d'une opération d'ajout, il s'agit des éléments ajoutés ; dans le cas d'une opération de suppression, il s'agit des éléments supprimés ; dans le cas d'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, la liste targetItems contiendra ces deux éléments.

Voir également QtQuick::ViewTransition::targetIndexes.