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 - 각각 추가, 이동 또는 제거 작업으로 인해 항목이 재배치될 때 적용되는 전환(지정된 경우, 이 전환들은 일반적인 재배치 전환을 재정의함)

데이터 모델이 아닌 자식 항목의 모음을 다루는 Row, Column, Grid 및 Flow 포지셔너 유형의 경우, 대신 다음 속성이 사용됩니다:

• populate - 포지셔너 생성 시점에 포지셔너에 추가된 항목에 적용할 전환
• add - 포지셔너에 추가되거나 부모가 변경된 항목, 또는 포지셔너 내에서 이동하게 된 항목에 적용할 전환 visible
• move - 포지셔너 내에서 이동한 항목에 적용할 전환 효과(다른 항목의 추가 또는 제거로 인해 위치가 변경된 경우, 포지셔너 내에서 항목이 재배치된 경우, 또는 포지셔너 내 다른 항목의 크기 조정으로 인해 항목의 위치가 변경된 경우 포함)

뷰 전환은 전환 중인 항목과 전환을 트리거한 작업에 대한 세부 정보를 제공하는 ViewTransition 부착 속성에 액세스할 수 있습니다. 뷰 전환은 항목당 한 번씩 실행되므로, 이러한 세부 정보를 사용하여 개별 항목마다 각 전환을 사용자 지정할 수 있습니다.

ViewTransition 부착 속성은 전환이 적용되는 항목에 특화된 다음과 같은 속성을 제공합니다.

• ViewTransition.item - 전환 중인 항목
• ViewTransition.index - 이 항목의 인덱스
• ViewTransition.destination - 해당 뷰 작업에 따라 이 항목이 이동하는 (x, y) 좌표

또한, ViewTransition은 전환을 유발한 작업의 대상이 되는 항목에 특화된 속성을 제공합니다:

• ViewTransition.targetIndexes - 대상 항목들의 인덱스
• ViewTransition.targetItems - 대상 항목 자체

( Row, Column, Grid 및 Flow 포지셔너 유형의 경우, move 전환은 포지셔너에 항목이 추가되어 전환이 트리거될 때만 이 두 가지 추가 세부 정보를 제공한다는 점에 유의하십시오.)

뷰 전환은 위에 나열된 속성을 전혀 참조하지 않고도 작성할 수 있습니다. 이러한 속성은 뷰 전환을 사용자 지정하는 데 유용한 추가 정보만을 제공합니다.

다음은 뷰 전환에 대한 소개와, 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에 차례로 삽입됩니다. 다섯 번째이자 마지막 삽입이 이루어져 “항목 4”가 뷰에 추가되면, “ add ” 전환은 (삽입된 항목에 대해) 한 번 실행되고, “ displaced ” 전환은 (뷰에 존재하는 4개의 기존 항목 각각에 대해) 네 번 실행됩니다.

이 시점에서, 가장 아래쪽으로 밀려난 항목(“항목 0”)에 대해 실행된 displaced 전환을 살펴보면, 이 전환에 제공된 ViewTransition 속성 값은 다음과 같습니다:

ViewTransition.targetIndexes 및 ViewTransition.targetItems 목록은 관련 작업의 대상이 되는 모든 델리게이트 인스턴스의 항목과 인덱스를 제공합니다. 추가 작업의 경우, 이들은 뷰에 추가된 모든 항목이며, 제거 작업의 경우, 이들은 뷰에서 제거된 모든 항목입니다. (이 목록에는 뷰 내에서 생성된 항목이나 캐시된 항목에 대한 참조만 포함된다는 점에 유의하십시오. 뷰의 가시 영역이나 항목 캐시 내에 없는 대상은 접근할 수 없습니다.)

따라서 ViewTransition.item, ViewTransition.index 및 ViewTransition.destination 값은 실행되는 개별 전환마다 달라지지만, ViewTransition.targetIndexes 와 ViewTransition.targetItems 값은 특정 추가 작업에 의해 트리거되는 모든 add 및 displaced 전환에서 동일합니다.

인덱스에 따른 애니메이션 지연

각 뷰 전환은 전환의 영향을 받는 항목마다 한 번씩 실행되므로, ViewTransition 속성을 사용하여 전환 내에서 각 항목의 전환에 대한 사용자 정의 동작을 정의할 수 있습니다. 예를 들어, 앞선 예제의 ListView 은 이 정보를 활용하여 이동된 항목의 움직임에 리플(ripple) 효과를 적용할 수 있습니다.

이는 ` 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 ` 전환을 수정한 것입니다. 이 예제에서는 `ViewTransition.item`을 참조하여 각 항목의 ` x ` 및 ` y ` 값에 접근하는 중첩된 ` NumberAnimation ` 객체를 가진 ` ParallelAnimation `을 추가했습니다. 이를 통해 각 항목은 뷰 내의 최종 위치로 애니메이션이 진행되기 전에, 전환의 시작점을 기준으로 한 중간 위치로 먼저 이동할 수 있습니다:

    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 애니메이션이 완료되지 않아, 불투명도와 크기가 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)
}

스페이스 키를 누르면 세 개의 항목이 인덱스 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]

이 첨부 속성은 뷰 내에서 전환된 항목의 최종 위치 정보를 저장합니다.

이 속성의 값은 ` point `이며, ` x ` 및 ` y ` 속성을 갖습니다.

ViewTransition.index : int [read-only attached]

이 첨부 속성은 전환 중인 항목의 인덱스를 저장합니다.

항목이 이동 중인 경우, 이 속성은 항목이 출발하는 위치가 아닌 이동하는 목적지의 인덱스를 저장한다는 점에 유의하십시오.

ViewTransition.item : item [read-only attached]

이 첨부 속성에는 전환 중인 항목이 저장됩니다.

ViewTransition.targetIndexes : list [read-only attached]

이 첨부 속성에는 해당 작업의 대상이 되는 뷰 내 항목들의 인덱스 목록이 저장됩니다.

대상 항목은 해당 작업의 대상이 되는 항목들입니다. 추가 작업의 경우, 이는 추가되는 항목들이며, 제거 작업의 경우 제거되는 항목들이고, 이동 작업의 경우 이동되는 항목들입니다.

예를 들어, 인덱스 1과 2에 두 개의 항목을 추가하는 삽입 작업에 의해 전환이 트리거된 경우, 이 targetIndexes 목록의 값은 [1,2]가 됩니다.

QtQuick::ViewTransition::targetItems도 참조하십시오 .

ViewTransition.targetItems : list [read-only attached]

이 첨부 속성은 해당 작업의 대상이 되는 뷰 내 항목 목록을 포함합니다.

대상 항목이란 해당 작업의 대상이 되는 항목을 말합니다. 추가 작업의 경우 추가되는 항목이 대상이며, 제거 작업의 경우 제거되는 항목이 대상이고, 이동 작업의 경우 이동되는 항목이 대상입니다.

예를 들어, 인덱스 1과 2에 두 개의 항목을 추가하는 삽입 작업에 의해 전환이 트리거된 경우, 이 targetItems 목록에는 이 두 항목이 포함됩니다.

QtQuick::ViewTransition::targetIndexes도 참조하십시오 .