ViewTransition QML Type (Uncreatable)

Gibt Elemente an, die sich in einer Ansicht im Übergang befinden. Mehr...

Hinweis: Dies ist ein nicht erstellbarer Typ. Er kann in QML nicht instanziiert werden.

• Liste aller Mitglieder, einschließlich geerbter Mitglieder

Angeschlossene Eigenschaften

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

Ausführliche Beschreibung

Mit „ ListView “ und „ GridView “ lassen sich Übergänge festlegen, die immer dann angewendet werden sollen, wenn sich die Elemente in der Ansicht infolge von Änderungen am Modell der Ansicht ändern. Beide verfügen über die folgenden Eigenschaften, die so eingestellt werden können, dass für verschiedene Vorgänge die entsprechenden Übergänge ausgeführt werden:

• populate - den Übergang, der auf die ursprünglich für die Ansicht erstellten Elemente oder bei Änderungen am Modell angewendet werden soll
• add - der Übergang, der auf Elemente angewendet werden soll, die der Ansicht nach ihrer Erstellung hinzugefügt werden
• remove - der Übergang, der auf Elemente anzuwenden ist, die aus der Ansicht entfernt werden
• move - der Übergang, der auf Elemente anzuwenden ist, die innerhalb der Ansicht verschoben werden (d. h. infolge einer Verschiebungsoperation im Modell)
• displaced - der generische Übergang, der auf alle Elemente anzuwenden ist, die durch eine Hinzufügungs-, Verschiebungs- oder Entfernungsoperation verdrängt werden
• addDisplaced, removeDisplaced und moveDisplaced – die Übergänge, die anzuwenden sind, wenn Elemente durch Hinzufügungs-, Verschiebungs- bzw. Entfernungsoperationen verdrängt werden (diese überschreiben den generischen „displaced“-Übergang, sofern angegeben)

Für die Positioner-Typen „ Row “, „ Column “, „ Grid “ und „ Flow “, die mit Sammlungen von untergeordneten Elementen statt mit Datenmodellen arbeiten, werden stattdessen die folgenden Eigenschaften verwendet:

• populate - der Übergang, der auf Elemente angewendet werden soll, die dem Positionierer zum Zeitpunkt seiner Erstellung hinzugefügt wurden
• add - der Übergang, der auf Elemente anzuwenden ist, die dem Positionierer hinzugefügt oder ihm neu zugeordnet werden, oder auf Elemente, die visible
• move - der Übergang, der auf Elemente angewendet werden soll, die innerhalb des Positioners verschoben wurden, einschließlich der Fälle, in denen sie durch das Hinzufügen oder Entfernen anderer Elemente verdrängt werden, oder wenn Elemente auf andere Weise innerhalb des Positioners neu angeordnet werden, oder wenn Elemente aufgrund der Größenänderung anderer Elemente im Positioner neu positioniert werden

Ansichtsübergänge haben Zugriff auf die angehängte Eigenschaft „ViewTransition“, die Details zu den Elementen liefert, die sich im Übergang befinden, sowie zu der Operation, die den Übergang ausgelöst hat. Da Ansichtsübergänge einmal pro Element ausgeführt werden, können diese Details verwendet werden, um jeden Übergang für jedes einzelne Element individuell anzupassen.

Die angehängte Eigenschaft „ViewTransition“ stellt die folgenden Eigenschaften bereit, die für das Element spezifisch sind, auf das der Übergang angewendet wird:

• ViewTransition.item – das Element, das sich im Übergang befindet
• ViewTransition.index – der Index dieses Elements
• ViewTransition.destination – der (x,y)-Punkt, zu dem dieses Element im Rahmen des jeweiligen Ansichtsvorgangs bewegt wird

Darüber hinaus stellt „ViewTransition“ Eigenschaften bereit, die sich speziell auf die Elemente beziehen, die das Ziel des Vorgangs sind, der den Übergang ausgelöst hat:

• ViewTransition.targetIndexes – die Indizes der Zielelemente
• ViewTransition.targetItems – die Zielelemente selbst

(Beachten Sie, dass für die Positionierertypen „ Row “, „ Column “, „ Grid “ und „ Flow “ der Übergang „ move “ diese beiden zusätzlichen Details nur dann bereitstellt, wenn der Übergang durch das Hinzufügen von Elementen zu einem Positionierer ausgelöst wird.)

Ansichtsübergänge können geschrieben werden, ohne auf eines der oben aufgeführten Attribute Bezug zu nehmen. Diese Attribute liefern lediglich zusätzliche Details, die für die Anpassung von Ansichtsübergängen nützlich sind.

Im Folgenden finden Sie eine Einführung in Ansichtsübergänge und die Möglichkeiten, wie die angehängte Eigenschaft „ViewTransition“ zur Erweiterung von Ansichtsübergängen genutzt werden kann.

Ansichtsübergänge: ein einfaches Beispiel

Hier ist ein einfaches Beispiel für die Verwendung von Ansichtsübergängen. Die folgende Ansicht legt Übergänge für die Eigenschaften „ add “ und „ displaced “ fest, die ausgeführt werden, wenn Elemente zur Ansicht hinzugefügt werden:

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

Wenn die Leertaste gedrückt wird, wodurch ein Element zum Modell hinzugefügt wird, wird das neue Element über einen Zeitraum von 400 Millisekunden eingeblendet und vergrößert, während es der Ansicht hinzugefügt wird. Außerdem bewegt sich jedes Element, das durch das Hinzufügen eines neuen Elements verdrängt wird, über einen Zeitraum von 400 Millisekunden animiert an seine neue Position in der Ansicht, wie durch den Übergang „ displaced “ festgelegt.

Würden fünf Elemente nacheinander am Index 0 eingefügt, sähe der Effekt wie folgt aus:

Beachten Sie, dass die oben genannten „ NumberAnimation “-Objekte keinen „ target “-Wert angeben müssen, um das entsprechende Element zu animieren. Auch muss der „ NumberAnimation “-Parameter im „ addTransition “ keinen „ to “-Wert angeben, um das Element an seine korrekte Position in der Ansicht zu verschieben. Dies liegt daran, dass die Ansicht die Werte für „ target “ und „ to “ implizit mit den korrekten Werten für das Element und die endgültige Elementposition festlegt, sofern diese Eigenschaften nicht explizit definiert sind.

Im einfachsten Fall kann ein Ansichtsübergang ein Element nach einer Ansichtsoperation lediglich an seine neue Position animieren, so wie es der Übergang „ displaced “ oben tut, oder bestimmte Elementeigenschaften animieren, wie im Übergang „ add “ oben. Darüber hinaus kann ein Ansichtsübergang die angehängte Eigenschaft „ViewTransition“ nutzen, um das Animationsverhalten für verschiedene Elemente anzupassen. Im Folgenden finden Sie einige Beispiele, wie dies erreicht werden kann.

Verwendung der angehängten Eigenschaft „ViewTransition“

Wie bereits erwähnt, liefern die verschiedenen „ViewTransition“-Eigenschaften spezifische Details sowohl zum einzelnen Element, für das der Übergang erfolgt, als auch zur Operation, die den Übergang ausgelöst hat. In der obigen Animation werden nacheinander fünf Elemente am Index 0 eingefügt. Wenn die fünfte und letzte Einfügung stattfindet – das Hinzufügen von „Element 4“ zur Ansicht –, wird der Übergang „ add “ einmal (für das eingefügte Element) und der Übergang „ displaced “ viermal (jeweils einmal für jedes der vier bereits in der Ansicht vorhandenen Elemente) ausgeführt.

Wenn wir nun den Übergang „ displaced “ untersuchen würden, der für das nach unten verschobene Element („Element 0“) ausgeführt wurde, wären die diesem Übergang zugewiesenen Werte der „ViewTransition“-Eigenschaft wie folgt:

Die Listen „ViewTransition.targetIndexes “ und „ViewTransition.targetItems “ enthalten die Elemente und Indizes aller Delegatinstanzen, die Ziele des jeweiligen Vorgangs sind. Bei einem Hinzufügungsvorgang sind dies alle Elemente, die der Ansicht hinzugefügt werden; bei einem Entfernungsvorgang sind dies alle Elemente, die aus der Ansicht entfernt werden, und so weiter. (Beachten Sie, dass diese Listen nur Verweise auf Elemente enthalten, die innerhalb der Ansicht erstellt wurden, oder auf deren zwischengespeicherte Elemente; Ziele, die sich nicht im sichtbaren Bereich der Ansicht oder im Element-Cache befinden, sind nicht zugänglich.)

Während also die Werte für `ViewTransition.item`, `ViewTransition.index` und `ViewTransition.destination` bei jedem einzelnen ausgeführten Übergang variieren, sind die Werte für `ViewTransition.targetIndexes ` und `ViewTransition.targetItems ` für jeden Übergang von ` add ` und ` displaced `, der durch einen bestimmten Hinzufügungsvorgang ausgelöst wird, identisch.

Animationen basierend auf dem Index verzögern

Da jeder Ansichtsübergang einmal für jedes vom Übergang betroffene Element ausgeführt wird, können die ViewTransition-Eigenschaften innerhalb eines Übergangs verwendet werden, um ein benutzerdefiniertes Verhalten für den Übergang jedes einzelnen Elements festzulegen. Beispielsweise könnte der „ ListView “ im vorherigen Beispiel diese Informationen nutzen, um einen Welleneffekt bei der Bewegung der verschobenen Elemente zu erzeugen.

Dies lässt sich erreichen, indem der Übergang „ displaced “ so angepasst wird, dass er die Animation jedes verdrängten Elements basierend auf der Differenz zwischen dessen Index (bereitgestellt von `ViewTransition.index`) und dem Index des ersten entfernten Elements (bereitgestellt von `ViewTransition.targetIndexes`) verzögert:

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

Jedes verschobene Element verzögert seine Animation um weitere 100 Millisekunden, wodurch ein subtiler Welleneffekt entsteht, wenn Elemente durch das Hinzufügen verschoben werden, wie hier gezeigt:

Animieren von Elementen zu Zwischenpositionen

Die Eigenschaft `ViewTransition.item` liefert eine Referenz auf das Element, auf das der Übergang angewendet wird. Diese kann verwendet werden, um auf alle Attribute des Elements, benutzerdefinierte ` property `-Werte usw. zuzugreifen.

Im Folgenden finden Sie eine Modifikation des Übergangs „ displaced “ aus dem vorherigen Beispiel. Dabei wird ein „ ParallelAnimation “ mit verschachtelten „ NumberAnimation “-Objekten hinzugefügt, die auf „ViewTransition.item“ verweisen, um zu Beginn ihrer Übergänge auf die Werte „ x “ und „ y “ der einzelnen Elemente zuzugreifen. Dadurch kann jedes Element zunächst zu einer Zwischenposition relativ zu seinem Startpunkt für den Übergang animiert werden, bevor es zu seiner Endposition in der Ansicht animiert wird:

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

Nun bewegt sich ein verschobenes Element zunächst relativ zu seiner Startposition an die Position (20, 50) und anschließend an seine endgültige, korrekte Position in der Ansicht:

Da die abschließende „ NumberAnimation “ keinen Wert für „ to “ angibt, setzt die Ansicht diesen Wert implizit auf die Endposition des Elements in der Ansicht, sodass diese letzte Animation das Element an die richtige Stelle bewegt. Falls der Übergang die Endposition des Elements für eine Berechnung benötigt, ist diese über „ViewTransition.destination“ abrufbar.

Anstelle mehrerer `NumberAnimations` könntest du eine ` PathAnimation ` verwenden, um ein Element entlang eines gekrümmten Pfades zu animieren. Beispielsweise könnte der Übergang ` add ` aus dem vorherigen Beispiel wie folgt um eine ` PathAnimation ` erweitert werden, um neu hinzugefügte Elemente entlang eines Pfades zu animieren:

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

Dadurch werden neu hinzugefügte Elemente entlang eines Pfades animiert. Beachten Sie, dass jeder Pfad relativ zum endgültigen Zielpunkt des jeweiligen Elements festgelegt wird, sodass Elemente, die an unterschiedlichen Indizes eingefügt werden, ihre Pfade von unterschiedlichen Positionen aus beginnen:

Umgang mit unterbrochenen Animationen

Ein Ansichtsübergang kann jederzeit unterbrochen werden, wenn während des laufenden ursprünglichen Übergangs ein anderer Ansichtsübergang angewendet werden muss. Nehmen wir beispielsweise an, Element A wird am Index 0 eingefügt und durchläuft einen „add“-Übergang; anschließend wird Element B kurz darauf am Index 0 eingefügt, noch bevor der Übergang von Element A abgeschlossen ist. Da Element B vor Element A eingefügt wird, verdrängt es Element A, was dazu führt, dass die Ansicht den „add“-Übergang von Element A mittendrin unterbricht und stattdessen einen „displaced“-Übergang für Element A startet.

Bei einfachen Animationen, die lediglich die Bewegung eines Elements zu seinem Endziel animieren, erfordert diese Unterbrechung wahrscheinlich keine zusätzliche Berücksichtigung. Wenn ein Übergang jedoch andere Eigenschaften verändert, kann diese Unterbrechung unerwünschte Nebeneffekte verursachen. Betrachten Sie das erste Beispiel auf dieser Seite, das der Einfachheit halber unten wiederholt wird:

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

Werden mehrere Elemente in schneller Folge hinzugefügt, ohne abzuwarten, bis ein vorheriger Übergang abgeschlossen ist, ergibt sich folgendes Bild:

Jedes neu hinzugefügte Element durchläuft einen „ add “-Übergang, doch bevor dieser abgeschlossen ist, wird ein weiteres Element hinzugefügt, wodurch das zuvor hinzugefügte Element verdrängt wird. Aus diesem Grund wird der „ add “-Übergang des zuvor hinzugefügten Elements unterbrochen und stattdessen ein „ displaced “-Übergang für das Element gestartet. Aufgrund der Unterbrechung wurden die Animationen „ opacity “ und „ scale “ nicht vollständig ausgeführt, was dazu führt, dass Elemente mit einer Deckkraft und einem Maßstab unter 1,0 erzeugt werden.

Um dies zu beheben, sollte der Übergang „ displaced “ zusätzlich sicherstellen, dass die Eigenschaften des Elements auf die im Übergang „ add “ festgelegten Endwerte gesetzt werden, wodurch diese Werte bei jeder Verschiebung des Elements effektiv zurückgesetzt werden. In diesem Fall bedeutet dies, die Deckkraft und den Maßstab des Elements auf 1,0 zu setzen:

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

Wenn nun der Übergang „ add “ eines Elements unterbrochen wird, werden dessen Deckkraft und Skalierung beim Verschieben auf 1,0 animiert, wodurch die zuvor aufgetretenen fehlerhaften visuellen Effekte vermieden werden:

Das gleiche Prinzip gilt für jede Kombination von Ansichtsübergängen. Ein hinzugefügtes Element kann verschoben werden, bevor sein Hinzufügungsübergang abgeschlossen ist, oder ein verschobenes Element kann entfernt werden, bevor sein Verschiebungsübergang abgeschlossen ist, und so weiter; daher lautet die Faustregel, dass jeder Übergang denselben Satz von Eigenschaften behandeln sollte.

Einschränkungen bezüglich „ScriptAction“

Wenn ein Ansichtsübergang initialisiert wird, werden alle Eigenschaftsbindungen, die sich auf die angehängte Eigenschaft „ViewTransition“ beziehen, zur Vorbereitung des Übergangs ausgewertet. Aufgrund der internen Struktur eines Ansichtsübergangs sind die Attribute der angehängten Eigenschaft „ViewTransition“ für das betreffende Element nur zum Zeitpunkt der Initialisierung des Übergangs gültig und möglicherweise nicht mehr gültig, wenn der Übergang tatsächlich ausgeführt wird.

Daher sollte eine „ ScriptAction “ innerhalb einer Ansichtsübergangsfunktion nicht auf die angehängte Eigenschaft „ViewTransition“ verweisen, da sie zum Zeitpunkt des tatsächlichen Aufrufs von „ ScriptAction “ möglicherweise nicht auf die erwarteten Werte verweist. Betrachten Sie das folgende Beispiel:

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

Wenn die Leertaste gedrückt wird, werden drei Elemente vom Index 5 zum Index 1 verschoben. Für jedes verschobene Element animiert die „ moveTransition “-Sequenz vermutlich zunächst die Farbe des Elements auf „yellow“, animiert es dann an seine Endposition und ändert die Farbe des Elements anschließend mithilfe eines „ ScriptAction “ wieder auf „lightsteelblue“ zurück. Bei der Ausführung führt der Übergang jedoch nicht zum beabsichtigten Ergebnis:

Nur das zuletzt verschobene Element erhält wieder die Farbe „lightsteelblue“; die anderen bleiben gelb. Dies liegt daran, dass die ` ScriptAction ` erst ausgeführt wird, nachdem der Übergang bereits initialisiert wurde. Zu diesem Zeitpunkt hat sich der Wert von `ViewTransition.item` bereits geändert und verweist nun auf ein anderes Element; das Element, auf das sich das Skript beziehen wollte, ist nicht dasjenige, das zum Zeitpunkt des tatsächlichen Aufrufs von ` ScriptAction ` von `ViewTransition.item` gehalten wird.

Um dieses Problem in diesem Fall zu vermeiden, könnte die Ansicht die Eigenschaft stattdessen mithilfe eines ` PropertyAction ` setzen:

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

Bei der Initialisierung des Übergangs wird die „ PropertyAction “-Eigenschaft „ target “ auf das jeweilige „ViewTransition.item“ des Übergangs gesetzt und später wie erwartet mit dem richtigen Zielelement ausgeführt.

Dokumentation zu angehängten Eigenschaften

ViewTransition.destination : point [read-only attached]

Diese angehängte Eigenschaft enthält die endgültige Zielposition des übergeführten Elements innerhalb der Ansicht.

Der Wert dieser Eigenschaft ist ein „ point “ mit den Eigenschaften „ x “ und „ y “.

ViewTransition.index : int [read-only attached]

Diese angehängte Eigenschaft enthält den Index des Elements, für das gerade ein Übergang stattfindet.

Beachten Sie, dass bei einer Verschiebung des Elements diese Eigenschaft den Index angibt, zu dem das Element verschoben wird, und nicht den Ausgangsindex.

ViewTransition.item : item [read-only attached]

Diese angehängte Eigenschaft enthält das Element, für das der Übergang stattfindet.

ViewTransition.targetIndexes : list [read-only attached]

Diese angehängte Eigenschaft enthält eine Liste der Indizes der Elemente in der Ansicht, die Gegenstand der jeweiligen Operation sind.

Die Ziele sind die Elemente, die Gegenstand der Operation sind. Bei einer Hinzufügungsoperation sind dies die Elemente, die hinzugefügt werden; bei einer Löschoperation sind dies die Elemente, die gelöscht werden; bei einer Verschiebungsoperation sind dies die Elemente, die verschoben werden.

Wurde der Übergang beispielsweise durch eine Einfügeoperation ausgelöst, bei der zwei Elemente an den Indizes 1 und 2 hinzugefügt wurden, hätte diese „targetIndexes“-Liste den Wert [1,2].

Siehe auch „ QtQuick::ViewTransition::targetItems “.

ViewTransition.targetItems : list [read-only attached]

Diese angehängte Eigenschaft enthält die Liste der Elemente in der Ansicht, die Gegenstand der jeweiligen Operation sind.

Die Ziele sind die Elemente, auf die sich die Operation bezieht. Bei einer Einfügeoperation sind dies die Elemente, die hinzugefügt werden; bei einer Löschoperation sind dies die Elemente, die entfernt werden; bei einer Verschiebeoperation sind dies die Elemente, die verschoben werden.

Wurde der Übergang beispielsweise durch eine Einfügeoperation ausgelöst, bei der zwei Elemente an den Indizes 1 und 2 hinzugefügt wurden, würde diese „targetItems“-Liste diese beiden Elemente enthalten.

Siehe auch „ QtQuick::ViewTransition::targetIndexes “.