En esta página

AnimatedImage QML Type

Reproduce animaciones almacenadas como una serie de imágenes. Más...

Import Statement: import QtQuick
Inherits:

Image

Enumeraciones

Características

Señales

Descripción detallada

El tipo AnimatedImage amplía las características del tipo Image, lo que permite reproducir animaciones almacenadas como imágenes que contienen una serie de fotogramas, como las que se guardan en archivos GIF.

Se puede obtener información sobre el fotograma actual y la duración total de la animación mediante las propiedades ` currentFrame ` y ` frameCount `. Se puede iniciar, pausar y detener la animación cambiando los valores de las propiedades ` playing ` y ` paused `.

La lista completa de formatos compatibles se puede obtener con QMovie::supportedFormats().

El número de veces que se reproduce la animación se puede controlar mediante la propiedad loops. De forma predeterminada, la animación se reproduce en bucle indefinidamente. La señal finished se emite cuando la animación termina de reproducirse el número de bucles especificado.

Ejemplo de uso

El siguiente código QML muestra cómo mostrar una imagen animada y obtener información sobre su estado, como el fotograma actual y el número total de fotogramas. El resultado es una imagen animada con un sencillo indicador de progreso debajo.

Nota: Cuando se almacenan en caché las imágenes animadas, se almacenará en caché cada fotograma de la animación.

Establece `cache` en `false` si vas a reproducir una animación larga o de gran tamaño y deseas ahorrar memoria.

Si los datos de la imagen proceden de un dispositivo secuencial (por ejemplo, un socket), AnimatedImage solo puede reproducirse en bucle si «cache» se establece en «true».


import QtQuick

Rectangle {
    width: animation.width; height: animation.height + 8

    AnimatedImage { id: animation; source: "animation.gif" }

    Rectangle {
        property int frames: animation.frameCount

        width: 4; height: 8
        x: (animation.width - width) * animation.currentFrame / frames
        y: animation.height
        color: "red"
    }
}

Véase también BorderImage y Image.

Documentación sobre enumeraciones

[since 6.12] FinishBehavior

Esta enumeración describe el comportamiento que se produce cuando la animación finaliza por sí sola.

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

Esta enumeración se introdujo en Qt 6.12.

Documentación de la propiedad

currentFrame : int

frameCount : int [read-only]

currentFrame es el fotograma que está visible en ese momento. Al supervisar los cambios en esta propiedad, puedes animar otros elementos al mismo tiempo que la imagen.

frameCount es el número de fotogramas de la animación. En algunos formatos de animación, frameCount es desconocido y tiene un valor de cero.

finishBehavior : enumeration [since 6.12]

Esta propiedad determina el comportamiento cuando la animación finaliza por sí sola. El valor por defecto es FinishBehavior.{FinishAtInitialFrame}.

Esta propiedad se introdujo en Qt 6.12.

Véase también FinishBehavior.

loops : int [since 6.12]

Esta propiedad indica el número de veces que se reproducirá la animación.

Tras reproducir la animación este número de veces, la animación se detendrá automáticamente y se emitirá la señal « finished ».

Si se establece en « AnimatedImage.Infinite » (valor predeterminado), la animación no dejará de reproducirse por sí sola.

Si se establece « loops » en « 0 », la animación no se reproducirá.

Los valores negativos no son válidos.

Esta propiedad se introdujo en Qt 6.12.

paused : bool

Esta propiedad indica si la imagen animada está en pausa.

Por defecto, esta propiedad tiene el valor «false». Establece su valor en «true» cuando quieras pausar la animación.

playing : bool

Esta propiedad indica si la imagen animada se está reproduciendo.

Por defecto, esta propiedad es «true», lo que significa que la animación comenzará a reproducirse inmediatamente.

Nota: esta propiedad se ve afectada por los cambios en el estado de reproducción real de AnimatedImage. Si se utilizan imágenes no animadas, será necesario establecer manualmente playing en true para que las imágenes siguientes se animen.

AnimatedImage {
    onStatusChanged: playing = (status == AnimatedImage.Ready)
}

source : url

Esta propiedad contiene la URL que hace referencia a la imagen original.

AnimatedImage Admite cualquier formato de imagen compatible con Qt, cargada desde cualquier esquema de URL compatible con Qt. Sin embargo, no es compatible con QQuickImageProvider.

sourceSize : size

Esta propiedad contiene el ancho y la altura, ya escalados, de la imagen a pantalla completa.

A diferencia de las propiedades « width » y « height », que escalan el dibujo de la imagen, esta propiedad establece el número máximo de píxeles almacenados para los fotogramas almacenados en caché, de modo que las animaciones de gran tamaño no utilicen más memoria de la necesaria.

Si el tamaño original es mayor que sourceSize, la imagen se reduce.

El tamaño natural de la imagen se puede restaurar estableciendo esta propiedad en ` undefined`.

Nota: Cambiar esta propiedad de forma dinámica provoca que se vuelva a cargar la fuente de la imagen, posiblemente incluso desde la red, si no se encuentra en la caché del disco.

Véase también Image::sourceSize.

speed : real [since QtQuick 2.11]

Esta propiedad determina la velocidad de la animación.

La velocidad se mide en porcentaje de la velocidad original de la imagen animada. La velocidad por defecto es 1,0 (velocidad original).

Esta propiedad se introdujo en QtQuick 2.11.

Documentación de señales

[since 6.12] finished()

Esta señal se emite cuando la animación ha terminado de reproducirse el número de veces especificado por « loops ».

No se emite cuando playing se establece manualmente en false, ni en el caso de animaciones cuya propiedad loops esté establecida en AnimatedImage.Infinite.

Nota: El controlador correspondiente es onFinished.

Esta señal se introdujo en Qt 6.12.

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