En esta página

AnimatedSprite QML Type

Dibuja una animación de sprite. Más...

Import Statement: import QtQuick
Inherits:

Item

Propiedades

Señales

Métodos

Descripción detallada

AnimatedSprite permite renderizar y controlar animaciones que se presentan como varios fotogramas en un mismo archivo de imagen. Puedes reproducirlas a una velocidad fija, a la frecuencia de fotogramas de tu pantalla, o avanzar manualmente y controlar el progreso.

Consideremos la siguiente hoja de sprites:

Hoja de sprites con cuatro fotogramas en los que aparecen puntos azules de forma progresiva

Se puede dividir en cuatro fotogramas:

Hoja de sprites dividida en cuatro fotogramas con bordes visibles

Para reproducir cada uno de estos fotogramas a una velocidad de 500 milisegundos por fotograma, se puede utilizar el siguiente código:

CódigoResultado
AnimatedSprite {
    source: "loading.png"
    frameWidth: 64
    frameHeight: 64
    frameCount: 4
    frameDuration: 500
}

Por defecto, los fotogramas se interpolan (se fusionan) para que la animación parezca más fluida. Para desactivar esta opción, establece ` interpolate ` en ` false`:

CódigoResultado
AnimatedSprite {
    source: "loading.png"
    frameWidth: 64
    frameHeight: 64
    frameCount: 4
    frameDuration: 500
    interpolate: false
}

Animación de carga que se reproduce sin interpolación de fotogramas

Para controlar cómo responde AnimatedSprite al cambio de escala, utiliza la propiedad « smooth ».

Ten en cuenta que, a diferencia de ` SpriteSequence`, el tipo `AnimatedSprite` no utiliza ` Sprite ` para definir varias animaciones, sino que encapsula una única animación.

Véase también Animaciones de sprites.

Documentación de la propiedad

currentFrame : int

Cuando la reproducción está en pausa, se puede avanzar manualmente hasta el fotograma actual configurando esta propiedad o llamando a la función ` advance()`.

finishBehavior : enumeration

El comportamiento cuando la animación finaliza por sí sola.

ConstanteDescripción
FinishAtInitialFrameCuando la animación termina, vuelve al fotograma inicial. Este es el comportamiento predeterminado.
FinishAtFinalFrameCuando la animación termina, permanece en el fotograma final.

frameCount : int

Número de fotogramas en este vídeo: AnimatedSprite.

frameDuration : int

Duración de cada fotograma de la animación en milisegundos. Los valores menores o iguales a 0 no son válidos.

Si « frameRate » es válido, se utilizará para calcular la duración de los fotogramas. De no ser así, y si «frameDuration» es válido, se utilizará « frameDuration ».

Al modificar este parámetro, se reiniciará la animación.

frameHeight : int

Altura de un fotograma individual en este AnimatedSprite.

Se puede omitir si es el único sprite del archivo.

frameRate : real

Número de fotogramas por segundo que se mostrarán en la animación. Los valores inferiores o iguales a 0 no son válidos.

Si frameRate es válido, se utilizará para calcular la duración de los fotogramas. De no ser así, y si frameDuration es válido, se utilizará frameDuration.

Al modificar este parámetro, se reiniciará la animación.

frameSync : bool

Si true, la animación no tendrá duración. En su lugar, la animación avanzará un fotograma cada vez que se muestre un fotograma en pantalla. De este modo, se sincroniza con la frecuencia de actualización, en lugar de con el tiempo transcurrido.

Si frameSync se establece en true, anula tanto frameRate como frameDuration.

El valor por defecto es ` false`.

Al cambiar este parámetro, la animación se reiniciará.

frameWidth : int

Ancho de un fotograma individual en este AnimatedSprite.

Se puede omitir si es el único sprite del archivo.

frameX : int

La coordenada X en el archivo de imagen del primer fotograma de AnimatedSprite.

Se puede omitir si el primer fotograma comienza en la esquina superior izquierda del archivo.

frameY : int

La coordenada Y en el archivo de imagen del primer fotograma de AnimatedSprite.

Se puede omitir si el primer fotograma comienza en la esquina superior izquierda del archivo.

interpolate : bool

Si el valor es «true», se realizará una interpolación entre los fotogramas del sprite para que la animación resulte más fluida.

El valor por defecto es «true».

loops : int

Tras reproducir la animación este número de veces, la animación se detendrá automáticamente. Los valores negativos no son válidos.

Si se establece en « AnimatedSprite.Infinite », la animación no se detendrá por sí sola.

El valor por defecto es AnimatedSprite.Infinite

paused : bool

Cuando está en pausa, se puede avanzar manualmente hasta el fotograma actual.

El valor por defecto es « false ».

reverse : bool

Si true, la animación se reproducirá al revés.

El valor por defecto es false.

running : bool

Si el sprite está animado o no.

El valor por defecto es «true».

source : url

La fuente de la imagen para la animación.

Si no se especifican frameHeight y frameWidth, se supone que se trata de una única fila larga de fotogramas cuadrados. De lo contrario, puede tratarse de varias filas contiguas o de fotogramas rectangulares; cuando se agote una fila, se utilizará la siguiente.

Si se especifican frameX y frameY, la fila de fotogramas se tomará con esas coordenadas x/y como esquina superior izquierda.

Documentación de Signal

finished()

Esta señal se emite cuando el sprite ha terminado de animarse.

No se emite cuando la opción «running» está establecida en « false », ni en el caso de los sprites cuya propiedad « loops » esté establecida en « AnimatedSprite.Infinite ».

Nota: El controlador correspondiente es « onFinished ».

Documentación del método

void advance(int frames = 1)

Avanza la animación del sprite un número determinado de « frames ».

void pause()

Detiene la animación del sprite. Esto no tiene ningún efecto si ` paused ` es ` true`.

Véase también resume().

void restart()

Detiene y, a continuación, inicia la animación del sprite.

void resume()

Reanuda la animación del sprite si paused es true; en caso contrario, no hace nada.

Véase también pause().

void start()

Inicia la animación del sprite. Si la animación ya se está ejecutando, llamar a este método no tiene ningún efecto.

Véase también stop().

void stop()

Detiene la animación del sprite. Si la animación no se está ejecutando, llamar a este método no tiene ningún efecto.

Véase también ` start()`.

© 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.