FrameAnimation QML Type
Activa un controlador cada vez que se actualiza un fotograma de animación. Más información...
| Import Statement: | import QtQuick |
| Since: | Qt 6.4 |
Propiedades
- currentFrame : int
- elapsedTime : real
- frameTime : real
- paused : bool
- running : bool
- smoothFrameTime : real
Señales
Métodos
Descripción detallada
Se puede utilizar FrameAnimation para activar una acción cada vez que las animaciones hayan avanzado y se haya renderizado un fotograma de animación. Consulta la documentación sobre el grafo de escena para obtener información detallada sobre los bucles de renderizado básicos y en subprocesos.
Para animaciones generales, es preferible utilizar « NumberAnimation » y otros elementos de « Animation », ya que estos ofrecen una forma declarativa de describir las animaciones.
Por otro lado, FrameAnimation debe utilizarse para animaciones imperativas personalizadas y en casos de uso como estos:
- Cuando necesites ejecutar código en cada actualización de fotograma. O, por ejemplo, en cada dos fotogramas, quizá utilizando renderizado progresivo.
- Cuando la velocidad o el objetivo cambian durante la animación, las animaciones normales de QML pueden resultar demasiado limitadas.
- Cuando se necesita una mayor precisión en el tiempo de actualización de los fotogramas, por ejemplo, para un contador de fps.
A diferencia de Timer, que permite establecer el tiempo de « interval », FrameAnimation se ejecuta siempre en sincronización con las actualizaciones de la animación. Si has utilizado Timer con un intervalo corto para animaciones personalizadas como las que se muestran a continuación, te recomendamos que consideres cambiar a FrameAnimation para obtener animaciones más fluidas.
// BAD
Timer {
interval: 16
repeat: true
running: true
onTriggered: {
// Animate something
}
}
// GOOD
FrameAnimation {
running: true
onTriggered: {
// Animate something
}
}Documentación de propiedades
currentFrame : int [read-only]
Esta propiedad contiene el número de actualizaciones de fotogramas desde el inicio. Cuando se reinicia la animación de fotogramas, «currentFrame» comienza desde « 0 ».
El siguiente ejemplo muestra cómo reaccionar ante las actualizaciones de fotogramas.
FrameAnimation {
running: true
onTriggered: {
// Run code on every frame update.
}
}Esta propiedad también se puede utilizar para renderizar solo cada n.º fotograma. Imagina un uso avanzado en el que la interfaz de usuario contiene dos elementos pesados y, para alcanzar una frecuencia de fotogramas global fluida de 60 fps, decides renderizar estos elementos pesados a 30 fps, el primero en cada fotograma par y el segundo en cada fotograma impar:
FrameAnimation {
running: true
onTriggered: {
if (currentFrame % 2 == 0)
updateUIElement1();
else
updateUIElement2();
}
}Por defecto, ` frame ` es 0.
elapsedTime : real [read-only]
Esta propiedad contiene el tiempo (en segundos) transcurrido desde el inicio anterior.
Por defecto, « elapsedTime » es 0.
frameTime : real [read-only]
Esta propiedad contiene el tiempo (en segundos) transcurrido desde la última actualización del fotograma.
El siguiente ejemplo muestra cómo utilizar `frameTime` para animar un elemento con velocidad variable, adaptándose a las frecuencias de actualización de la pantalla y a posibles caídas de fps.
Rectangle {
id: rect
property real speed: 90
width: 100
height: 100
color: "red"
anchors.centerIn: parent
}
FrameAnimation {
id: frameAnimation
running: true
onTriggered: {
// Rotate the item speed-degrees / second.
rect.rotation += rect.speed * frameTime
}
}Por defecto, ` frameTime ` es 0.
paused : bool
Si se establece en «true», se detiene la animación de fotogramas; en caso contrario, se reanuda.
paused El valor por defecto es «false».
Véase también pause() y resume().
running : bool
Si se establece en «true», inicia la animación de fotogramas; en caso contrario, la detiene.
running El valor por defecto es «false».
Véase también stop(), start() y restart().
smoothFrameTime : real [read-only]
Esta propiedad contiene el tiempo suavizado (en segundos) transcurrido desde la última actualización del fotograma.
El siguiente ejemplo muestra cómo utilizar `smoothFrameTime` para mostrar los fps medios.
Text {
text: "fps: " + frameAnimation.fps.toFixed(0)
}
FrameAnimation {
id: frameAnimation
property real fps: smoothFrameTime > 0 ? (1.0 / smoothFrameTime) : 0
running: true
}Por defecto, ` smoothFrameTime ` es 0.
Documentación de Signal
triggered()
Esta señal se emite cuando el FrameAnimation ha avanzado a una nueva trama.
Nota: El controlador correspondiente es onTriggered.
Documentación del método
void pause()
Detiene la animación de fotogramas.
Si la animación de fotogramas ya está en pausa o no se encuentra en el estado « running », llamar a este método no tendrá ningún efecto. La propiedad « paused » pasará a ser «true» tras llamar a « pause() ».
void reset()
Restablece las propiedades de animación de los fotogramas.
Al llamar a este método, se restablecen las propiedades « frame » y « elapsedTime » a sus valores iniciales (0). Este método no afecta a las propiedades « running » ni « paused » y puede invocarse tanto si estas son «true» como «false».
La diferencia entre llamar a reset() y a restart() es que reset() siempre inicializará las propiedades, mientras que restart() solo las inicializa en la siguiente actualización de fotograma, lo que no ocurre, por ejemplo, si restart() va seguido inmediatamente de pause().
void restart()
Reinicia la animación de fotogramas.
Si el « FrameAnimation » no se está ejecutando, se iniciará; en caso contrario, se detendrá, se restablecerá a su estado inicial y se iniciará. La propiedad « running » será «true» tras una llamada a « restart() ».
void resume()
Reanuda una animación de fotogramas que se encuentra en pausa.
Si la animación de fotogramas no está en pausa o no se encuentra en el estado « running », llamar a este método no tendrá ningún efecto. La propiedad « paused » pasará a ser «false» tras llamar a « resume() ».
void start()
Inicia la animación de fotogramas.
Si la animación por fotogramas ya se está ejecutando, llamar a este método no tiene ningún efecto. La propiedad ` running ` pasará a ser `true` tras llamar a ` start()`.
void stop()
Detiene la animación de fotogramas.
Si la animación por fotogramas no se está ejecutando, llamar a este método no tiene ningún efecto. Las propiedades « running » y « paused » serán «false» tras llamar a « stop() ».
© 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.