帧动画 QML 类型

在每次动画帧更新时触发处理程序。更多信息...

导入语句	import QtQuick
从	Qt 6.4

所有成员的列表，包括继承的成员

属性

currentFrame : int
elapsedTime : qreal
frameTime : qreal
paused : bool
running : bool
smoothFrameTime : qreal

信号

triggered()

方法

pause()
reset()
restart()
resume()
start()
stop()

详细说明

帧动画可用于在动画进度推进且已渲染动画帧时触发生动作。请参阅有关场景图的文档以获取有关线程化和基本渲染循环的详细信息。

对于一般动画，建议使用 NumberAnimation 和其他 Animation 元素，因为这些提供了描述动画的声明式方法。

另一方面， FrameAnimation 应用于自定义命令式动画和以下用例

当您需要在每次帧更新时运行一些代码。例如，每帧，也许使用渐进式渲染。
当动画速度/目标在动画期间发生变化时，正常的 QML 动画可能过于限制。
当需要更精确的帧更新时间时，例如用于 fps 计数器。

与允许设置 interval 时间的代码 Timer 相比，FrameAnimation 总是与动画更新同步运行。如果您已使用代码 Timer 与一个短间隔用于以下的自定义动画，请考虑改用 FrameAnimation 以获得更平滑的动画。

// BAD
Timer {
    interval: 16
    repeat: true
    running: true
    onTriggered: {
        // Animate something
    }
}

// GOOD
FrameAnimation {
    running: true
    onTriggered: {
        // Animate something
    }
}

属性文档

currentFrame : int [只读]

此属性存储从开始到现在的顿更新次数。当帧动画重新启动时，currentFrame 从 0 开始。

以下示例显示了如何对帧更新做出反应。

FrameAnimation {
    running: true
    onTriggered: {
        // Run code on every frame update.
    }
}

此属性也可以用于仅渲染每 nth 帧。考虑一个高级用法，其中 UI 包含两个重量级元素，为了达到整体的 60fps 帧率，你决定以 30fps 渲染这些重量级元素，第一个在偶数帧上，第二个在奇数帧上

FrameAnimation {
    running: true
    onTriggered: {
        if (currentFrame % 2 == 0)
            updateUIElement1();
        else
            updateUIElement2();
   }
}

默认情况下，frame 为 0。

elapsedTime : qreal [只读]

此属性保存自上次开始以来的时间（以秒为单位）。

默认情况下，elapsedTime 为 0。

frameTime : qreal [只读]

此属性保存自上次帧更新以来的时间（以秒为单位）。

以下示例显示了如何使用 frameTime 对项进行变速动画，以适应屏幕刷新率和可能的 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
    }
}

默认情况下，frameTime 为 0。

paused : bool

如果设置为 true，则暂停帧动画；否则继续。

paused 默认为 false。

另请参阅pause() 和 resume()。

running : bool

如果设置为 true，则开始帧动画；否则停止它。

running 默认为 false。

另请参阅stop()，start() 和 restart()。

smoothFrameTime : qreal [只读]

此属性保存自上次帧更新以来的平滑时间（以秒为单位）。

以下示例显示了如何使用 smoothFrameTime 显示平均 fps。

Text {
    text: "fps: " + frameAnimation.fps.toFixed(0)
}

FrameAnimation {
    id: frameAnimation
    property real fps: smoothFrameTime > 0 ? (1.0 / smoothFrameTime) : 0
    running: true
}

默认情况下，smoothFrameTime 为 0。

信号文档

triggered()

当 FrameAnimation 进度到新帧时发出此信号。

注意：相应的事件处理程序是 onTriggered。

方法文档

pause()

暂停帧动画

如果帧动画已经暂停或未 running，则调用此方法没有效果。调用 pause() 后，paused 属性将为 true。

reset()

重置帧动画属性

调用此方法将 frame 和 elapsedTime 重置为其初始值（0）。此方法对 running 或 paused 属性没有影响，并且可以在它们为 true 或 false 时调用。

调用 reset() 和 restart() 之间的区别在于 reset() 总是初始化属性，而 restart() 仅在下一个帧更新时初始化它们，这不会发生，例如如果立即调用 restart() 后跟 pause()。

restart()

重新启动帧动画

如果 FrameAnimation 没有运行，则它会启动，否则它会停止，重置到初始状态并启动。调用 restart() 后，running 属性将为 true。

resume()

恢复暂停的帧动画

如果帧动画没有暂停或不 running，则调用此方法没有效果。调用 resume() 后，paused 属性将为 false。

start()

开始帧动画

如果帧动画已经正在运行，则调用此方法没有效果。调用 start() 后，running 属性将为 true。

stop()

停止帧动画

如果帧动画没有运行，调用此方法不会有任何效果。在调用 stop() 方法后，running 和 paused 属性都将为 false。