ViewTransition QML Type

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

• 継承されたメンバを含む全メンバのリスト

付属プロパティ

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

詳細説明

ListView とGridView を使用すると、ビューのモデルが変更された結果、ビュー内のアイテムが変更されるたびに適用されるトランジションを指定することができます。どちらも以下のプロパティを持ち、様々な操作に対して適切な遷移を設定することができます：

• populate - ビューに対して最初に作成されたアイテム、またはモデルが変更されたときに適用されるトランジション。
• add - ビュー作成後にビューに追加されたアイテムに適用される遷移
• remove - ビューから削除されたアイテムに適用されるトランジション
• move - ビュー内で移動されたアイテムに適用されるトランジション（モデル内の移動操作の結果など）
• displaced - 追加、移動、削除操作によって置き換えられたアイテムに適用される一般的なトランジション。
• addDisplaced removeDisplaced および - 追加、移動、または削除操作によってアイテムが置き換えられたときに適用されるトランジション。moveDisplaced

データモデルではなく子アイテムのコレクションを操作するRow 、Column 、Grid 、Flow ポジショナタイプでは、代わりに以下のプロパティが使用されます：

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

ビュー遷移は、遷移中のアイテムと遷移をトリガーした操作の詳細を提供する ViewTransition アタッチプロパティにアクセスできます。ビュー遷移は、アイテムごとに 1 回実行されるため、これらの詳細を使用して、個々のアイテムの各遷移をカスタマイズすることができます。

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

• ViewTransition.item - 遷移先のアイテム。
• ViewTransition.index - このアイテムのインデックス。
• ViewTransition.destination - 関連するビュー操作において、このアイテムが移動する(x,y)点。

さらに、ViewTransitionは、遷移をトリガーした操作のターゲットであるアイテム固有のプロパティを提供します：

• ViewTransitiontargetIndexes.- ターゲットアイテムのインデックス
• ViewTransitiontargetItems.- ターゲット アイテム自体

(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 Attachedプロパティの使用

前述のように、様々な ViewTransition プロパティは、トランジションをトリガーした操作と同様に、トランジションされる個々のアイテムに固有の詳細を提供します。上のアニメーションでは、インデックス 0 に 5 つのアイテムが連続して挿入されています。最後の5番目の挿入が行われ、ビューに「アイテム4」が追加されると、add トランジションが1回（挿入されたアイテムに対して）実行され、displaced トランジションが4回（ビュー内の既存の4つのアイテムに対してそれぞれ1回）実行されます。

この時点で、一番下に配置されたアイテム（「Item 0」）に対して実行されたdisplaced トランジションを調べると、このトランジションに提供される ViewTransition プロパティ値は次のようになります：

ViewTransition. "targetIndexes 、"ViewTransition. "targetItems リストは、関連する操作のターゲットであるすべてのデリゲートインスタンスのアイテムとインデックスを提供します。add操作の場合、これらはビューに追加されるすべてのアイテムです。remove操作の場合、これらはビューから削除されるすべてのアイテムです。(これらのリストには、ビュー内に作成されたアイテムやキャッシュされたアイテムへの参照のみが含まれます。ビューの可視領域内やアイテムキャッシュ内にないターゲットにはアクセスできません)。

そのため、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 }
        }
    }

このように、アイテムが追加によって移動すると、微妙な波紋のような効果が得られます：

中間位置へのアイテムのアニメーション

ViewTransition.itemプロパティは、トランジションが適用されているアイテムへの参照を与えます。このプロパティを使用して、アイテムのアトリビュートやカスタムproperty 値などにアクセスできます。

以下は、前の例のdisplaced トランジションを変更したものです。ViewTransition.itemを参照するネストされたNumberAnimation オブジェクトを持つParallelAnimation を追加し、トランジションの開始時に各アイテムの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 に挿入され、「追加」トランジションが実行されたとします。アイテム 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 のアニメーションは完了しておらず、不透明度とスケールが 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 は、ViewTransition のアタッチド プロパティを参照すべきではありません。ScriptAction が実際に呼び出される時点で期待される値を参照しない可能性があるからです。次の例を考えてみましょう：

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 シーケンスは、アイテムの色を「黄色」にアニメートし、次に最終位置までアニメートし、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 に設定され、後で期待通りに正しいアイテムターゲットで実行されます。

付属プロパティの説明