ViewTransition QML Type (Uncreatable)

ビュー内の遷移中の項目を指定します。詳細...

注：これは作成不可能な型です。QML ではインスタンス化できません。

• 継承されたメンバを含むすべてのメンバの一覧

関連プロパティ

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

詳細な説明

ListView およびGridView を使用すると、ビューのモデルが変更された結果としてビュー内の項目が変更された際に適用される遷移を指定することができます。これらには、さまざまな操作に対して実行される適切な遷移を設定できる以下のプロパティがあります：

• populate - ビューの初期作成時、またはモデルの変更時にアイテムに適用する遷移
• add - ビューの作成後にビューに追加されたアイテムに適用するトランジション
• remove - ビューから削除されたアイテムに適用する遷移
• move - ビュー内で移動された項目（つまり、モデルでの移動操作の結果として）に適用する遷移
• displaced - 追加、移動、または削除操作によって位置が変更されたすべてのアイテムに適用される汎用遷移
• addDisplaced、removeDisplaced およびmoveDisplaced - それぞれ追加、移動、削除操作によってアイテムが置き換えられた際に適用される遷移（これらは、指定されている場合、汎用の「displaced」遷移を上書きする）

データモデルではなく子項目のコレクションを扱うRow 、Column 、Grid 、およびFlow の各ポジショナータイプについては、代わりに以下のプロパティが使用されます：

• populate - ポジショナーの作成時に、そのポジショナーに追加されたアイテムに適用される遷移
• add - ポジショナーに追加されたり、ポジショナーを親として再設定されたりしたアイテム、あるいはvisible
• move - ポジショナー内で移動したアイテムに適用されるトランジション。これには、他のアイテムの追加や削除によって位置がずれた場合、ポジショナー内でその他の方法で再配置された場合、またはポジショナー内の他のアイテムのサイズ変更によって位置が変更された場合が含まれます

ビュー遷移は、ViewTransition 添付プロパティにアクセスでき、これにより、遷移中のアイテムの詳細や、遷移をトリガーした操作に関する情報を取得できます。ビュー遷移はアイテムごとに 1 回実行されるため、これらの詳細情報を使用して、個々のアイテムごとに遷移をカスタマイズすることができます。

ViewTransition アタッチドプロパティは、遷移が適用されるアイテムに固有の以下のプロパティを提供します。

• ViewTransition.item - 遷移中のアイテム
• ViewTransition.index - この項目のインデックス
• ViewTransition.destination - 該当するビュー操作において、このアイテムが移動する (x, y) 座標

さらに、ViewTransition には、遷移をトリガーした操作のターゲットとなるアイテムに固有のプロパティも用意されています：

• ViewTransition.targetIndexes — ターゲット項目のインデックス
• ViewTransition.targetItems - ターゲットとなるアイテム自体

（なお、Row 、Column 、Grid 、Flow といったポジショナータイプの場合、move 遷移では、ポジショナーへのアイテムの追加によって遷移がトリガーされた場合にのみ、これら2つの追加情報が提供されます。）

ビュー遷移は、上記の属性のいずれにも言及せずに記述することができます。これらの属性は、ビュー遷移をカスタマイズする際に役立つ追加情報を提供するに過ぎません。

以下では、ビュー遷移の概要と、ViewTransition アタッチドプロパティを使用してビュー遷移を拡張する方法について紹介します。

ビュー遷移：簡単な例

以下に、ビュー遷移の使用に関する基本的な例を示します。以下のビューでは、add プロパティおよびdisplaced プロパティに対する遷移が指定されており、これらはビューにアイテムが追加された際に実行されます：

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

スペースキーが押されると、モデルに項目が追加され、新しい項目はビューに追加される際に、400ミリ秒かけてフェードインし、拡大します。 また、新しい項目の追加によって位置がずれた項目は、「displaced 」トランジションで指定されている通り、400ミリ秒かけてビュー内の新しい位置へアニメーションで移動します。

インデックス0の位置に5つのアイテムが連続して挿入された場合、次のような効果になります：

上記のNumberAnimation オブジェクトでは、該当するアイテムをアニメーションさせるためにtarget を指定する必要がないことに注意してください。また、addTransition 内のNumberAnimation では、アイテムをビュー内の正しい位置に移動させるためにto 値を指定する必要もありません。これは、これらのプロパティが明示的に定義されていない場合、ビューが暗黙的にtarget およびto の値を、正しいアイテムおよび最終的なアイテム位置の値に設定するためです。

最も単純な場合、ビュー遷移は、前述のdisplaced 遷移のように、ビュー操作後にアイテムを新しい位置へアニメーションで移動させるだけの場合もあれば、前述のadd 遷移のように、アイテムのプロパティをアニメーションさせる場合もあります。さらに、ビュー遷移では、ViewTransitionアタッチドプロパティを利用して、アイテムごとにアニメーションの挙動をカスタマイズすることもできます。以下に、その実現方法の例をいくつか示します。

ViewTransition アタッチド プロパティの使用

前述の通り、ViewTransitionの各種プロパティは、遷移の対象となる個々のアイテムや、遷移をトリガーした操作に固有の詳細情報を提供します。 上記のアニメーションでは、5つのアイテムがインデックス0の位置に順次挿入されています。5回目となる最後の挿入が行われ、「Item 4」がビューに追加されると、add トランジションが1回（挿入されたアイテムに対して）、displaced トランジションが4回（ビュー内の既存の4つのアイテムそれぞれに対して1回ずつ）実行されます。

この時点で、下方に移動したアイテム（「Item 0」）に対して実行されたdisplaced 遷移を調べると、この遷移に指定されたViewTransitionプロパティの値は次のようになります：

ViewTransition.targetIndexes および ViewTransition.targetItems リストは、関連する操作の対象となるすべてのデリゲートインスタンスの項目とインデックスを提供します。追加操作の場合、これらはビューに追加されるすべての項目であり、削除操作の場合はビューから削除されるすべての項目となります。 （これらのリストには、ビュー内またはそのアイテムキャッシュ内で作成されたアイテムへの参照のみが含まれることに注意してください。ビューの可視領域外やアイテムキャッシュ内にないターゲットにはアクセスできません。）

したがって、ViewTransition.item、ViewTransition.index、およびViewTransition.destinationの値は、実行される個々の遷移ごとに異なりますが、ViewTransition.targetIndexes およびViewTransition.targetItems の値は、特定の追加操作によってトリガーされるすべてのadd およびdisplaced 遷移で共通となります。

インデックスに基づくアニメーションの遅延

各ビュー遷移は、その遷移の影響を受けるアイテムごとに1回実行されるため、ViewTransitionのプロパティを遷移内で使用して、各アイテムの遷移に対するカスタム動作を定義できます。たとえば、前の例のListView では、この情報を使用して、移動したアイテムの動きに波紋のような効果を与えることができます。

これを実現するには、displaced の遷移を修正し、各移動対象アイテムのインデックス（ViewTransition.indexで提供）と最初に削除されたアイテムのインデックス（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 }
        }
    }

各移動対象アイテムのアニメーションはさらに100ミリ秒遅延され、addによってアイテムが移動される際に、次のような微妙な波紋のような効果が生まれます：

アイテムを中間位置までアニメーションさせる

ViewTransition.item プロパティは、遷移が適用されているアイテムへの参照を提供します。これを使用すると、アイテムの属性やカスタムproperty 値などにアクセスできます。

以下は、前の例にあるdisplaced トランジションを修正したものです。ParallelAnimation を追加し、その中にNumberAnimation オブジェクトをネストさせています。これらの オブジェクトはViewTransition.itemを参照し、各アイテムのトランジション開始時のx およびy 値にアクセスします。これにより、各アイテムは、ビュー内の最終位置へアニメーションする前に、トランジションの開始点に対する相対的な中間位置までアニメーションすることが可能になります：

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

これにより、位置がずれたアイテムは、まず開始位置を基準として (20, 50) の位置に移動し、その後、ビュー内の最終的な正しい位置に移動します：

最後のNumberAnimation ではto の値が指定されていないため、ビューはこの値を暗黙的にビュー内でのアイテムの最終位置に設定します。したがって、この最後のアニメーションによってアイテムは正しい位置に移動します。トランジションで何らかの計算のためにアイテムの最終位置が必要な場合は、ViewTransition.destinationを通じてその値にアクセスできます。

複数の`NumberAnimation`を使用する代わりに、`PathAnimation `を使用して、アイテムを曲線パスに沿ってアニメーションさせることもできます。たとえば、前の例にある`add `トランジションに、次のように`PathAnimation `を追加することで、新しく追加されたアイテムをパスに沿ってアニメーションさせることができます：

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

これにより、新しく追加されたアイテムがパスに沿ってアニメーションされます。各パスは各アイテムの最終到達点を基準として指定されるため、異なるインデックスに挿入されたアイテムは、それぞれ異なる位置からパスを開始することに注意してください：

アニメーションの中断への対応

元の遷移が進行中に別のビュー遷移を適用する必要が生じた場合、ビュー遷移はいつでも中断される可能性があります。例えば、アイテム A がインデックス 0 に挿入され、「add」遷移が行われている最中に、アイテム A の遷移が完了する前に、アイテム B がすぐに続いてインデックス 0 に挿入されたとします。 アイテムBはアイテムAよりも先に挿入されるため、アイテムAを置き換えることになり、その結果、ビューはアイテムAの「add」遷移を途中で中断し、代わりにアイテムAに対して「displaced」遷移を開始することになります。

アイテムを最終位置まで移動させるだけの単純なアニメーションの場合、この中断について特に考慮する必要はないでしょう。しかし、遷移によって他のプロパティが変更される場合、この中断は望ましくない副作用を引き起こす可能性があります。便宜上、このページの最初の例を以下に再掲しますので、参考にしてください：

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

以前の遷移が完了するのを待たずに、複数のアイテムが立て続けに追加されると、次のような結果になります：

新しく追加された各アイテムは「add 」トランジションを実行しますが、そのトランジションが完了する前に別のアイテムが追加され、以前に追加されたアイテムが置き換えられてしまいます。このため、以前に追加されたアイテムの「add 」トランジションは中断され、代わりにそのアイテムに対して「displaced 」トランジションが開始されます。 この中断により、opacity およびscale のアニメーションが完了していないため、不透明度（opacity）とスケール（scale）が1.0未満のアイテムが生成されてしまいます。

これを修正するには、displaced トランジションにおいて、add トランジションで指定された終了値に項目のプロパティが確実に設定されるようにする必要があります。つまり、項目が移動されるたびにこれらの値をリセットするのです。この場合、項目の不透明度とスケールを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 }
    }

これで、アイテムのadd トランジションが中断された場合、そのアイテムが移動した際に不透明度とスケールが1.0へとアニメーションされ、以前のような誤った視覚効果が回避されます：

この原則は、ビューの遷移のあらゆる組み合わせにも当てはまります。追加されたアイテムは、その「追加」遷移が完了する前に移動される可能性があり、移動されたアイテムは、その「移動」遷移が完了する前に削除される可能性などがあります。したがって、経験則として、すべての遷移は同じプロパティのセットを扱うべきです。

ScriptActionに関する制限事項

ビュー遷移が初期化されると、ViewTransition アタッチド プロパティを参照するプロパティ バインディングは、遷移の準備として評価されます。 ビュー遷移の内部構造の性質上、ViewTransition アタッチドプロパティの属性は、遷移が初期化された時点でその関連アイテムに対してのみ有効であり、遷移が実際に実行される時点では無効になっている可能性があります。

したがって、ビュー遷移内のScriptAction は、ScriptAction が実際に呼び出される時点で期待される値を参照していない可能性があるため、ViewTransitionアタッチドプロパティを参照してはなりません。次の例を考えてみましょう。

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

スペースキーが押されると、3つのアイテムがインデックス5からインデックス1へ移動します。 移動される各アイテムについて、moveTransition シーケンスは、おそらくそのアイテムの色を「yellow」にアニメーションで変更し、次に最終位置へアニメーションで移動させ、その後ScriptAction を使用してアイテムの色を「lightsteelblue」に戻すはずです。しかし、実行してみると、この遷移は意図した結果を生み出しません：

最後に移動されたアイテムのみが「lightsteelblue」の色に戻り、他のアイテムは黄色のままです。 これは、ScriptAction がトランジションの初期化が完了した後に実行されるためです。その時点では、ViewTransition.itemの値は別のアイテムを指すよう変更されています。つまり、スクリプトが参照しようとしていたアイテムは、ScriptAction が実際に呼び出された時点でViewTransition.itemが保持しているアイテムとは異なるのです。

この場合、この問題を回避するために、ビューは代わりに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" }
        }
    }

トランジションが初期化される際、PropertyAction `target ` は、そのトランジションに対応する `ViewTransition.item` に設定され、その後、期待どおりに正しいアイテムをターゲットとして実行されます。

添付プロパティのドキュメント

ViewTransition.destination : point [read-only attached]

この添付プロパティには、ビュー内での遷移対象項目の最終的な位置情報が格納されます。

このプロパティの値は、`x ` および `y ` プロパティを持つ `point ` です。

ViewTransition.index : int [read-only attached]

この添付プロパティには、遷移中の項目のインデックスが格納されます。

なお、アイテムが移動中の場合、このプロパティには、アイテムが移動元のインデックスではなく、移動先のインデックスが格納される点に注意してください。

ViewTransition.item : item [read-only attached]

この添付プロパティには、遷移中のアイテムが格納されます。

ViewTransition.targetIndexes : list [read-only attached]

この関連プロパティには、関連する操作の対象となるビュー内の項目のインデックスのリストが格納されています。

ターゲットとは、その操作の対象となるアイテムのことです。追加操作の場合は追加されるアイテム、削除操作の場合は削除されるアイテム、移動操作の場合は移動されるアイテムがターゲットとなります。

たとえば、インデックス 1 および 2 に 2 つの項目を追加する挿入操作によって遷移がトリガーされた場合、この targetIndexes リストの値は [1,2] となります。

QtQuick::ViewTransition::targetItemsも参照してください 。

ViewTransition.targetItems : list [read-only attached]

この添付プロパティには、関連する操作の対象となるビュー内の項目のリストが格納されます。

ターゲットとは、操作の対象となるアイテムのことです。追加操作の場合は追加されるアイテム、削除操作の場合は削除されるアイテム、移動操作の場合は移動されるアイテムとなります。

たとえば、インデックス 1 および 2 に 2 つの項目を追加する挿入操作によって遷移がトリガーされた場合、この targetItems リストにはこれら 2 つの項目が含まれます。

「QtQuick::ViewTransition::targetIndexes」も参照してください 。