ViewTransition QML Type

Especifica los elementos en transición en una vista. Más...

• Lista de todos los miembros, incluidos los heredados

Propiedades adjuntas

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

Descripción detallada

Con ListView y GridView, es posible especificar transiciones que deben aplicarse siempre que los elementos de la vista cambien como resultado de modificaciones en el modelo de la vista. Ambas tienen las siguientes propiedades que pueden establecerse a las transiciones apropiadas que deben ejecutarse para diversas operaciones:

• populate - la transición que se aplicará a los elementos creados inicialmente para la vista, o cuando cambie el modelo
• add - la transición que se aplicará a los elementos que se añadan a la vista después de haberla creado
• remove - la transición que se aplica a los elementos que se eliminan de la vista
• move - la transición que se aplicará a los elementos que se muevan dentro de la vista (es decir, como resultado de una operación de movimiento en el modelo)
• displaced - la transición genérica que se aplicará a los elementos desplazados por una operación de adición, desplazamiento o eliminación.
• addDisplaced removeDisplaced y - las transiciones que se aplicarán cuando los elementos sean desplazados por operaciones de añadir, mover o eliminar, respectivamente (éstas anulan la transición genérica desplazada si se especifica). moveDisplaced

Para los tipos de posicionador Row, Column, Grid y Flow, que operan con colecciones de elementos hijo en lugar de modelos de datos, se utilizan en su lugar las siguientes propiedades:

• populate - la transición que se aplicará a los elementos que se hayan añadido al posicionador en el momento de su creación
• add - la transición que se aplicará a los elementos que se añadan al posicionador o se reasignen a él, o a los elementos que se hayan convertido en posicionadores. visible
• move - La transición que se aplica a los elementos que se han movido dentro del posicionador, incluyendo cuando se desplazan debido a la adición o eliminación de otros elementos, o cuando los elementos se reorganizan dentro del posicionador, o cuando los elementos se reposicionan debido al cambio de tamaño de otros elementos en el posicionador.

Las transiciones de vista tienen acceso a una propiedad adjunta ViewTransition que proporciona detalles de los elementos que están bajo transición y la operación que desencadenó la transición. Dado que las transiciones de vista se ejecutan una vez por elemento, estos detalles pueden utilizarse para personalizar cada transición para cada elemento individual.

La propiedad adjunta ViewTransition proporciona las siguientes propiedades específicas del elemento al que se aplica la transición:

• ViewTransition.item - el elemento que está bajo transición
• ViewTransition.index - el índice de este elemento
• ViewTransition.destination - el punto (x,y) al que se mueve este elemento para la operación de vista correspondiente

Además, ViewTransition proporciona propiedades específicas para los elementos que son el objetivo de la operación que desencadenó la transición:

• ViewTransition.targetIndexes - los índices de los elementos de destino
• ViewTransition.targetItems - los propios elementos de destino

(Tenga en cuenta que para los tipos de posicionador Row, Column, Grid y Flow, la transición move sólo proporciona estos dos detalles adicionales cuando la transición se desencadena por la adición de elementos a un posicionador).

Las transiciones de vista pueden escribirse sin hacer referencia a ninguno de los atributos enumerados anteriormente. Estos atributos simplemente proporcionan detalles adicionales que son útiles para personalizar las transiciones de vista.

A continuación se presenta una introducción a las transiciones de vista y las formas en que la propiedad adjunta ViewTransition puede utilizarse para aumentar las transiciones de vista.

Transiciones de vista: un ejemplo sencillo

A continuación se muestra un ejemplo básico del uso de las transiciones de vista. La vista que se muestra a continuación especifica transiciones para las propiedades add y displaced, que se ejecutarán cuando se añadan elementos a la vista:

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

Cuando se pulsa la tecla espacio, añadiendo un elemento al modelo, el nuevo elemento se desvanecerá y aumentará de escala a lo largo de 400 milisegundos mientras se añade a la vista. Además, cualquier elemento desplazado por la adición de un nuevo elemento se animará hasta su nueva posición en la vista a lo largo de 400 milisegundos, según especifique la transición displaced.

Si se insertaran cinco elementos sucesivamente en el índice 0, el efecto sería el siguiente:

Observe que los objetos NumberAnimation anteriores no necesitan especificar un target para animar el elemento correspondiente. Además, el NumberAnimation en el addTransition no necesita especificar el valor to para mover el elemento a su posición correcta en la vista. Esto se debe a que la vista establece implícitamente los valores target y to con los valores correctos de posición del elemento y del elemento final si estas propiedades no se definen explícitamente.

En su forma más simple, una transición de vista puede simplemente animar un elemento a su nueva posición tras una operación de la vista, como hace la transición displaced anterior, o animar algunas propiedades del elemento, como en la transición add anterior. Además, una transición de vista puede hacer uso de la propiedad adjunta ViewTransition para personalizar el comportamiento de la animación para diferentes elementos. A continuación se muestran algunos ejemplos de cómo se puede lograr esto.

Uso de la propiedad adjunta ViewTransition

Como ya se ha indicado, las distintas propiedades ViewTransition proporcionan detalles específicos del elemento individual que está siendo objeto de transición, así como de la operación que ha desencadenado la transición. En la animación anterior, se insertan sucesivamente cinco elementos en el índice 0. Cuando se produce la quinta y última inserción, añadiendo el "Elemento 4" a la vista, la transición add se ejecuta una vez (para el elemento insertado) y la transición displaced se ejecuta cuatro veces (una vez para cada uno de los cuatro elementos existentes en la vista).

En este punto, si examináramos la transición displaced que se ejecutó para el elemento desplazado inferior ("Elemento 0"), los valores de la propiedad ViewTransition proporcionados a esta transición serían los siguientes:

Las listas ViewTransition.targetIndexes y ViewTransition.targetItems proporcionan los elementos e índices de todas las instancias delegadas que son los objetivos de la operación correspondiente. En el caso de una operación de adición, se trata de todos los elementos que se añaden a la vista; en el caso de una operación de eliminación, se trata de todos los elementos que se eliminan de la vista, y así sucesivamente. (Ten en cuenta que estas listas sólo contendrán referencias a elementos que se hayan creado dentro de la vista o sus elementos en caché; los objetivos que no se encuentren dentro del área visible de la vista o dentro de la caché de elementos no serán accesibles).

Así, mientras que los valores ViewTransition.item, ViewTransition.index y ViewTransition.destination varían para cada transición individual que se ejecuta, los valores ViewTransition.targetIndexes y ViewTransition.targetItems son los mismos para cada transición add y displaced que se desencadena por una operación add concreta.

Retraso de animaciones en función del índice

Dado que cada transición de vista se ejecuta una vez para cada elemento afectado por la transición, las propiedades ViewTransition pueden utilizarse dentro de una transición para definir un comportamiento personalizado para la transición de cada elemento. Por ejemplo, el ListView del ejemplo anterior podría utilizar esta información para crear un efecto de tipo ondulación en el movimiento de los elementos desplazados.

Esto se puede conseguir modificando la transición displaced para que retrase la animación de cada elemento desplazado en función de la diferencia entre su índice (proporcionado por ViewTransition.index) y el primer índice eliminado (proporcionado por 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 }
        }
    }

Cada elemento desplazado retrasa su animación 100 milisegundos adicionales, produciendo un sutil efecto de ondulación cuando los elementos son desplazados por la adición, de esta forma:

Animación de elementos a posiciones intermedias

La propiedad ViewTransition.item proporciona una referencia al elemento al que se está aplicando la transición. Puede utilizarse para acceder a cualquiera de los atributos del elemento, valores personalizados de property, etc.

A continuación se muestra una modificación de la transición displaced del ejemplo anterior. Añade un ParallelAnimation con objetos NumberAnimation anidados que hacen referencia a ViewTransition.item para acceder a los valores x y y de cada elemento al inicio de sus transiciones. Esto permite a cada elemento animarse a una posición intermedia relativa a su punto de inicio de la transición, antes de animarse a su posición final en la vista:

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

Ahora, un elemento desplazado se moverá primero a una posición de (20, 50) relativa a su posición inicial, y después a su posición final correcta en la vista:

Dado que el NumberAnimation final no especifica un valor to, la vista implícitamente establece este valor a la posición final del elemento en la vista, y así esta última animación moverá este elemento al lugar correcto. Si la transición requiere la posición final del ítem para algún cálculo, ésta es accesible a través de ViewTransition.destination.

En lugar de utilizar múltiples NumberAnimations, puedes utilizar PathAnimation para animar un elemento sobre una trayectoria curva. Por ejemplo, la transición add del ejemplo anterior podría aumentarse con una PathAnimation de la siguiente manera: para animar los elementos recién añadidos a lo largo de una trayectoria:

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

Esto anima los elementos recién añadidos a lo largo de un camino. Tenga en cuenta que cada ruta se especifica en relación con el punto de destino final de cada elemento, de modo que los elementos insertados en diferentes índices comienzan sus rutas desde diferentes posiciones:

Manejo de animaciones interrumpidas

Una transición de vista puede interrumpirse en cualquier momento si es necesario aplicar una transición de vista diferente mientras la transición original está en curso. Por ejemplo, supongamos que el elemento A se inserta en el índice 0 y se somete a una transición "añadir"; a continuación, el elemento B se inserta en el índice 0 en rápida sucesión antes de que la transición del elemento A haya finalizado. Como el elemento B se inserta antes que el elemento A, desplazará al elemento A, haciendo que la vista interrumpa la transición "añadir" del elemento A a mitad de camino y comience una transición "desplazada" en el elemento A en su lugar.

Para animaciones sencillas que simplemente animan el movimiento de un elemento hasta su destino final, es poco probable que esta interrupción requiera una consideración adicional. Sin embargo, si una transición cambia otras propiedades, esta interrupción puede causar efectos secundarios no deseados. Considere el primer ejemplo de esta página, repetido a continuación por comodidad:

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 se añaden varios elementos en rápida sucesión, sin esperar a que finalice una transición anterior, éste es el resultado:

Cada nuevo elemento añadido se somete a una transición add, pero antes de que la transición pueda terminar, se añade otro elemento, desplazando al elemento añadido anteriormente. Debido a esto, la transición add en el elemento previamente añadido se interrumpe y en su lugar se inicia una transición displaced en el elemento. Debido a la interrupción, las animaciones opacity y scale no se han completado, produciendo así elementos con opacidad y escala por debajo de 1.0.

Para solucionar este problema, la transición displaced debe garantizar adicionalmente que las propiedades del elemento se establecen en los valores finales especificados en la transición add, restableciendo efectivamente estos valores cada vez que se desplaza un elemento. En este caso, significa establecer la opacidad y la escala del elemento en 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 }
    }

Ahora, cuando se interrumpe la transición add de un elemento, su opacidad y escala se animan a 1,0 al desplazarse, evitando los efectos visuales erróneos de antes:

El mismo principio se aplica a cualquier combinación de transiciones de vista. Un elemento añadido puede ser desplazado antes de que termine su transición de añadir, o un elemento desplazado puede ser eliminado antes de que termine su transición de desplazar, y así sucesivamente; por lo tanto, la regla general es que cada transición debe manejar el mismo conjunto de propiedades.

Restricciones relativas a ScriptAction

Cuando se inicializa una transición de vista, todos los enlaces de propiedades que hacen referencia a la propiedad adjunta ViewTransition se evalúan para preparar la transición. Debido a la naturaleza de la construcción interna de una transición de vista, los atributos de la propiedad adjunta ViewTransition sólo son válidos para el elemento relevante cuando se inicializa la transición, y pueden no ser válidos cuando la transición se ejecuta realmente.

Por lo tanto, un ScriptAction dentro de una transición de vista no debe hacer referencia a la propiedad adjunta ViewTransition, ya que puede no referirse a los valores esperados en el momento en que se invoque realmente el ScriptAction. Considere el siguiente ejemplo:

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

Cuando se pulsa la tecla espacio, se mueven tres elementos del índice 5 al índice 1. Para cada elemento movido, la secuencia moveTransition presumiblemente anima el color del elemento a "amarillo", luego lo anima a su posición final, luego cambia el color del elemento de nuevo a "azul acero claro" usando un ScriptAction. Sin embargo, cuando se ejecuta, la transición no produce el resultado esperado:

Sólo el último elemento movido recupera el color "azul acero claro"; los demás siguen siendo amarillos. Esto se debe a que ScriptAction no se ejecuta hasta que la transición ya se ha inicializado, momento en el que el valor de ViewTransition.item ha cambiado para referirse a un elemento diferente; el elemento al que el script pretendía referirse no es el que ViewTransition.item tiene en el momento en el que se invoca ScriptAction.

En este caso, para evitar este problema, la vista podría establecer la propiedad utilizando 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" }
        }
    }

Cuando se inicialice la transición, el PropertyAction target se establecerá en el ViewTransition.item respectivo para la transición y se ejecutará más tarde con el item objetivo correcto como se esperaba.

Documentación de la propiedad adjunta

ViewTransition.destination : point [read-only]

Esta propiedad adjunta contiene la posición final de destino para el elemento transicionado dentro de la vista.

El valor de esta propiedad es un point con las propiedades x y y.

ViewTransition.index : int [read-only]

Esta propiedad adjunta contiene el índice del elemento al que se está realizando la transición.

Tenga en cuenta que si el elemento se está moviendo, esta propiedad contiene el índice al que se mueve el elemento, no desde el que se mueve.

ViewTransition.item : item [read-only]

Esta propiedad adjunta contiene el elemento que está siendo objeto de transición.

ViewTransition.targetIndexes : list [read-only]

Esta propiedad adjunta contiene una lista de los índices de los elementos de la vista que son el objetivo de la operación correspondiente.

Los destinos son los elementos objeto de la operación. En el caso de una operación de adición, son los elementos que se añaden; en el caso de una operación de eliminación, son los elementos que se eliminan; en el caso de una operación de movimiento, son los elementos que se mueven.

Por ejemplo, si la transición se desencadena por una operación de inserción que añade dos elementos en los índices 1 y 2, esta lista targetIndexes tendría el valor [1,2].

Véase también QtQuick::ViewTransition::targetItems.

ViewTransition.targetItems : list [read-only]

Esta propiedad adjunta contiene la lista de elementos de la vista que son el objetivo de la operación correspondiente.

Los destinos son los elementos objeto de la operación. Para una operación de adición, son los elementos que se añaden; para una eliminación, son los elementos que se eliminan; para un movimiento, son los elementos que se mueven.

Por ejemplo, si la transición se desencadena por una operación de inserción que añade dos elementos en los índices 1 y 2, la lista targetItems contendrá estos dos elementos.

Véase también QtQuick::ViewTransition::targetIndexes.