FrameAnimation QML Type

在每个动画帧更新时触发一个处理程序。更多...

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

属性

• currentFrame : int
• elapsedTime : real
• frameTime : real
• paused : bool
• running : bool
• smoothFrameTime : real

信号

• triggered()

方法

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

详细说明

FrameAnimation 可用于在动画进展且渲染出一个动画帧时触发操作。有关线程化渲染循环和基本渲染循环的详细信息，请参阅关于场景图的文档。

对于常规动画，建议优先使用NumberAnimation 及其他Animation 元素，因为它们提供了描述动画的声明式方法。

另一方面，FrameAnimation 应用于自定义命令式动画，以及以下使用场景：

• 当您需要在每个帧更新时执行某些代码时。例如，每隔一帧执行一次，可能采用渐进式渲染。
• 当动画过程中速度或目标值发生变化时，普通的 QML 动画可能过于受限。
• 当需要更精确的帧更新时间时，例如用于帧率计数器。

与允许设置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 [read-only]

该属性保存自开始以来的帧更新次数。当帧动画重新开始时，currentFrame 将从0 开始。

以下示例演示了如何响应帧更新。

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

该属性还可用于仅渲染每第 n 帧。假设一种高级用法：当 UI 中包含两个资源消耗较大的元素时，为了实现整体 60fps 的流畅帧率，您可以决定以 30fps 的频率渲染这些元素，其中第一个元素在每个偶数帧渲染，第二个元素在每个奇数帧渲染：

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

默认情况下，frame 的值为 0。

elapsedTime : real [read-only]

该属性存储自上次启动以来的时间（以秒为单位）。

默认情况下，elapsedTime 的值为0。

frameTime : real [read-only]

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

以下示例演示了如何使用 frameTime 来以可变速度对项目进行动画处理，并根据屏幕刷新率和可能出现的帧率下降进行调整。

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 : real [read-only]

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

以下示例演示了如何使用 `smoothFrameTime` 来显示平均帧率。

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 进入新帧时，会发出此信号。

方法文档

void pause()

暂停帧动画。

如果帧动画已暂停或未处于running 状态，调用此方法将无效果。调用pause() 后，paused 属性将设为true。

void reset()

重置帧动画属性。

调用此方法将frame 和elapsedTime 重置为初始值（0）。此方法对running 或paused 属性没有影响，无论这些属性的值为true还是false，均可调用该方法。

调用reset() 和restart() 的区别在于：reset() 会立即初始化这些属性，而restart() 仅在下一个帧更新时才进行初始化——例如，如果restart() 之后紧接着是pause() ，则不会发生帧更新。

void restart()

重新启动帧动画。

如果FrameAnimation 未运行，则将其启动；否则，将先停止该动画，重置为初始状态，然后重新启动。调用restart() 后，running 属性将变为true。

void resume()

恢复已暂停的帧动画。

如果帧动画未暂停或未处于running 状态，调用此方法将无效果。调用resume() 后，paused 属性将变为false。

void start()

启动帧动画。

如果帧动画已经在运行，调用此方法将不起作用。调用start() 之后，running 属性将变为 true。

void stop()

停止帧动画。

如果帧动画未运行，调用此方法将无效果。调用stop() 之后，running 和paused 属性均将设为 false。