En esta página

ViewTransition QML Type (Uncreatable)

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

Import Statement: import QtQuick

Nota: Se trata de un tipo no creable. No se puede instanciar en QML.

Propiedades asociadas

Descripción detallada

Con ListView y GridView, es posible especificar las transiciones que deben aplicarse cada vez que los elementos de la vista cambien como resultado de modificaciones en el modelo de la vista. Ambos cuentan con las siguientes propiedades, que pueden configurarse para que se ejecuten las transiciones adecuadas en función de las distintas operaciones:

  • populate - la transición que se aplicará a los elementos creados inicialmente para la vista, o cuando el modelo cambie
  • add - la transición que se aplicará a los elementos que se añadan a la vista una vez creada
  • remove - la transición que se aplicará a los elementos que se eliminen de la vista
  • move - la transición que se aplicará a los elementos que se desplacen dentro de la vista (es decir, como resultado de una operación de desplazamiento en el modelo)
  • displaced - la transición genérica que se aplicará a cualquier elemento que sea desplazado por una operación de adición, desplazamiento o eliminación
  • addDisplaced, removeDisplaced y moveDisplaced - las transiciones que se aplicarán cuando los elementos sean desplazados por operaciones de adición, desplazamiento o eliminación, respectivamente (estas anulan la transición genérica de desplazamiento si se especifican)

Para los tipos de posicionador Row, Column, Grid y Flow, que operan con colecciones de elementos secundarios en lugar de con 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 que cambien de padre dentro de este, o a los elementos que se hayan convertido en visible
  • move - la transición que se aplicará a los elementos que se hayan desplazado dentro del posicionador, incluso cuando se vean desplazados debido a la adición o eliminación de otros elementos, o cuando los elementos se reorganicen de cualquier otra forma dentro del posicionador, o cuando los elementos se reposicionen 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 sobre los elementos que se encuentran en transición y la operación que la ha desencadenado. 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á en proceso de transición
  • ViewTransition.index: el índice de este elemento
  • ViewTransition.destination: el punto (x, y) al que se desplaza este elemento para la operación de vista correspondiente

Además, ViewTransition proporciona propiedades específicas de los elementos que son el destino de la operación que ha desencadenado la transición:

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

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

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

A continuación se ofrece una introducción a las transiciones de vista y a las formas en que la propiedad adjunta ViewTransition puede utilizarse para ampliar 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 aparece 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 })
}

Al pulsar la tecla de espacio, lo que añade un elemento al modelo, el nuevo elemento aparecerá con un efecto de fundido y aumentará de tamaño a lo largo de 400 milisegundos a medida que se añade a la vista. Además, cualquier elemento que resulte desplazado por la incorporación de un nuevo elemento se animará hasta su nueva posición en la vista a lo largo de 400 milisegundos, tal y como especifica la transición « displaced ».

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

Obsérvese que los objetos « NumberAnimation » anteriores no necesitan especificar un « target » para animar el elemento correspondiente. Asimismo, el « NumberAnimation » del « 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 del elemento y de la posición final del elemento si estas propiedades no se definen explícitamente.

En su forma más sencilla, una transición de vista puede limitarse a animar un elemento hasta su nueva posición tras una operación de vista, tal y 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 utilizar 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 se ha indicado, las distintas propiedades de ViewTransition proporcionan detalles específicos del elemento concreto que está experimentando la transición, así como de la operación que la ha desencadenado. En la animación anterior, se insertan cinco elementos sucesivamente en el índice 0. Cuando tiene lugar la quinta y última inserción, al añadir 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 por 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 hacia abajo («Elemento 0»), los valores de la propiedad ViewTransition proporcionados a esta transición serían los siguientes:

PropiedadValorExplicación
ViewTransition.itemInstancia del delegado «Elemento 0»El propio objeto « Rectangle » de «Elemento 0»
ViewTransition.indexint valor 4El índice del «Elemento 0» dentro del modelo tras la operación de adición
ViewTransition.destinationpoint valor (0, 120)La posición a la que se desplaza el «Elemento 0»
ViewTransition.targetIndexesint matriz, que solo contiene el número entero «0» (cero)El índice del «Elemento 4», el nuevo elemento añadido a la vista
ViewTransition.targetItems, contiene únicamente la instancia del delegado «Elemento 4»El objeto «Item 4» de tipo Rectangle: el nuevo elemento añadido a la vista

Las listas ViewTransition.targetIndexes y ViewTransition.targetItems proporcionan los elementos y los índices de todas las instancias de delegado que son el destino 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 eliminación, se trata de todos los elementos eliminados de la vista, y así sucesivamente. (Ten en cuenta que estas listas solo contendrán referencias a elementos que se hayan creado dentro de la vista o a sus elementos almacenados en caché; no se podrá acceder a los destinos que no se encuentren dentro del área visible de la vista o dentro de la caché de elementos).

Así pues, mientras que los valores de ViewTransition.item, ViewTransition.index y ViewTransition.destination varían para cada transición individual que se ejecuta, los valores de ViewTransition.targetIndexes y ViewTransition.targetItems son los mismos para todas las transiciones add y displaced que se activan mediante una operación de adición concreta.

Retraso de animaciones en función del índice

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

Esto se puede lograr 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, lo que produce un sutil efecto de ondas cuando los elementos son desplazados por la adición, de la siguiente manera:

Animación de elementos a posiciones intermedias

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

A continuación se muestra una modificación de la transición « displaced » del ejemplo anterior. Añade un objeto ` 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 que cada elemento se anime hasta una posición intermedia respecto a su punto de partida para la transición, antes de animarse hasta 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 (20, 50) respecto a su posición inicial y, a continuación, a su posición final correcta en la vista:

Dado que la animación numérica final ( NumberAnimation ) no especifica un valor de « to », la vista establece implícitamente este valor en la posición final del elemento en la vista, por lo que esta última animación desplazará dicho elemento al lugar correcto. Si la transición requiere la posición final del elemento para algún cálculo, se puede acceder a ella a través de `ViewTransition.destination`.

En lugar de utilizar varias NumberAnimations, se puede emplear una PathAnimation para animar un elemento a lo largo de una trayectoria curva. Por ejemplo, la transición add del ejemplo anterior podría ampliarse 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 una trayectoria. Ten en cuenta que cada trayectoria se especifica en relación con el punto de destino final de cada elemento, de modo que los elementos insertados en índices diferentes comienzan sus trayectorias desde posiciones diferentes:

Gestión de animaciones interrumpidas

Una transición de vista puede interrumpirse en cualquier momento si es necesario aplicar otra transición de vista 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 de «add»; a continuación, el elemento B se inserta en el índice 0 de forma rápida y sucesiva antes de que haya finalizado la transición del elemento A. Dado que el elemento B se inserta antes que el elemento A, desplazará a este último, lo que provocará que la vista interrumpa la transición «add» del elemento A a mitad de camino y, en su lugar, inicie una transición «displaced» en el elemento A.

En el caso de 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 modifica otras propiedades, esta interrupción puede provocar efectos secundarios no deseados. Consideremos el primer ejemplo de esta página, que se repite a continuación para mayor 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 la transición anterior, este es el resultado:

Cada elemento recién añadido se somete a una transición « add », pero antes de que la transición pueda finalizar, se añade otro elemento, desplazando al elemento añadido anteriormente. Debido a esto, la transición « add » del elemento añadido anteriormente se interrumpe y, en su lugar, se inicia una transición « displaced » en dicho elemento. Debido a la interrupción, las animaciones opacity y scale no se han completado, lo que da lugar a elementos con una opacidad y una escala inferiores a 1,0.

Para solucionar esto, la transición displaced debería garantizar además que las propiedades del elemento se establezcan en los valores finales especificados en la transición add, restableciendo efectivamente estos valores cada vez que se desplaza un elemento. En este caso, esto 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 hasta 1,0 al desplazarse, lo que evita los efectos visuales erróneos que se producían antes:

El mismo principio se aplica a cualquier combinación de transiciones de vista. Un elemento añadido puede moverse antes de que finalice su transición de «add», o un elemento movido puede eliminarse antes de que finalice su transición de «moved», y así sucesivamente; por lo tanto, la regla general es que cada transición debe gestionar el mismo conjunto de propiedades.

Restricciones relativas a ScriptAction

Cuando se inicializa una transición de vista, se evalúan todos los enlaces de propiedades que hacen referencia a la propiedad adjunta ViewTransition como preparación para la transición. Debido a la naturaleza de la estructura interna de una transición de vista, los atributos de la propiedad adjunta `ViewTransition` solo son válidos para el elemento en cuestión cuando se inicializa la transición, y pueden no serlo cuando la transición se ejecuta realmente.

Por lo tanto, una acción de script ( ScriptAction ) dentro de una transición de vista no debe hacer referencia a la propiedad adjunta ViewTransition, ya que es posible que no haga referencia a los valores esperados en el momento en que se invoque realmente la acción de script ( ScriptAction ). Consideremos 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)
}

Al pulsar la tecla de espacio, tres elementos se desplazan del índice 5 al índice 1. Para cada elemento movido, se supone que la secuencia « moveTransition » anima el color del elemento a «amarillo», luego lo anima hasta su posición final y, a continuación, vuelve a cambiar el color del elemento a «lightsteelblue» mediante un método ` ScriptAction`. Sin embargo, al ejecutarse, la transición no produce el resultado previsto:

Solo el último elemento desplazado recupera el color «lightsteelblue»; los demás permanecen amarillos. Esto se debe a que el método 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 contiene ViewTransition.item en el momento en que se invoca realmente el método ScriptAction.

En este caso, para evitar este problema, la vista podría establecer la propiedad utilizando un ` 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 método PropertyAction target se establecerá en el ViewTransition.item correspondiente a la transición y, posteriormente, se ejecutará con el elemento de destino correcto, tal y como se espera.

Documentación de la propiedad adjunta

ViewTransition.destination : point [read-only attached]

Esta propiedad adjunta contiene la posición de destino final del elemento en transición dentro de la vista.

El valor de esta propiedad es un objeto de tipo « point » con las propiedades « x » y « y ».

ViewTransition.index : int [read-only attached]

Esta propiedad adjunta contiene el índice del elemento que está en proceso de transición.

Ten en cuenta que, si el elemento se está moviendo, esta propiedad contiene el índice al que se está moviendo el elemento, no el de origen.

ViewTransition.item : item [read-only attached]

Esta propiedad asociada contiene el elemento que está en proceso de transición.

Advertencia: este elemento no debe conservarse ni consultarse fuera de la transición, ya que puede dejar de ser válido a medida que cambia la vista.

ViewTransition.targetIndexes : list [read-only attached]

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

Los elementos de destino son aquellos sobre los que se realiza la operación. En el caso de una operación de inserción, son los elementos que se añaden; en el caso de una operación de eliminación, son los elementos que se eliminan; y en el caso de una operación de desplazamiento, son los elementos que se desplazan.

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

Nota: La lista `targetIndexes` solo contiene los índices de los elementos que se encuentran realmente en la vista, o que estarán en la vista una vez que finalice la operación correspondiente.

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

ViewTransition.targetItems : list [read-only attached]

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

Los elementos de destino son aquellos sobre los que se realiza la operación. En el caso de una operación de inserción, se trata de los elementos que se añaden; en el de una eliminación, de los que se eliminan; y en el de un desplazamiento, de los que se mueven.

Por ejemplo, si la transición se activó mediante una operación de inserción que añadió dos elementos en los índices 1 y 2, esta lista targetItems contendría dichos dos elementos.

Nota: La lista `targetItems` solo contiene elementos que se encuentran realmente en la vista, o que estarán en ella una vez que se complete la operación correspondiente.

Advertencia: Los objetos de esta lista no deben conservarse ni consultarse fuera de la transición, ya que los elementos pueden dejar de ser válidos. Los `targetItems` solo son válidos cuando se crea inicialmente la transición; esto también significa que no deben ser utilizados por los objetos ` ScriptAction ` de la transición, que no se evalúan hasta que se ejecuta la transición.

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

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.