AnimatedImage QML Type

播放以一系列图像形式存储的动画。更多...

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

枚举

• FinishBehavior (since 6.12)

属性

• currentFrame : int
• finishBehavior : enumeration (since 6.12)
• frameCount : int
• loops : int (since 6.12)
• paused : bool
• playing : bool
• source : url
• sourceSize : size
• speed : real (since QtQuick 2.11)

信号

• finished() (since 6.12)

详细说明

AnimatedImage 类型继承了Image 类型的功能，提供了一种播放以图像形式存储的动画的方法，这些动画包含一系列帧，例如存储在 GIF 文件中的动画。

可通过currentFrame 和frameCount 属性获取当前帧及动画总时长信息。您可以通过更改playing 和paused 属性的值来开始、暂停和停止动画。

支持的格式完整列表可通过QMovie::supportedFormats() 获取。

可通过loops 属性控制动画的播放次数。默认情况下，动画将无限循环播放。当动画播放完指定次数的循环后，将触发finished 信号。

使用示例

以下 QML 代码演示了如何显示动画图像并获取其状态信息，例如当前帧和总帧数。最终效果是一个动画图像，其下方带有简单的进度指示器。

注意：当动画图像被缓存时，动画的每一帧都会被缓存。

若要播放较长或较大的动画并希望节省内存，请将 cache 设置为 false。

如果图像数据来自顺序设备（例如套接字），则只有将 cache 设置为 true 时，AnimatedImage 才能循环播放。

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"
    }
}

另请参阅 BorderImage 和Image 。

枚举文档

[since 6.12] FinishBehavior

此枚举描述了动画自行结束时的行为。

该枚举在 Qt 6.12 中引入。

属性文档

currentFrame 是当前可见的帧。通过监听该属性的变化，您可以让其他项目与图像同步进行动画效果。

frameCount 是动画中的帧数。对于某些动画格式，frameCount 属性未定义，其值为零。

finishBehavior : enumeration [since 6.12]

该属性控制动画自行结束时的行为。默认值为FinishBehavior{FinishAtInitialFrame}。

该属性于 Qt 6.12 中引入。

另请参阅 FinishBehavior 。

loops : int [since 6.12]

该属性用于指定动画的播放次数。

当动画播放达到此次数后，动画将自动停止，并触发finished 信号。

如果将此属性设置为AnimatedImage.Infinite （默认值），动画将不会自动停止播放。

将loops 设置为0 意味着动画将不会播放。

负值无效。

该属性于 Qt 6.12 中引入。

paused : bool

该属性用于指示动画图像是否处于暂停状态。

默认情况下，该属性值为 false。若要暂停动画，请将其设置为 true。

playing : bool

该属性用于指示动画图像是否正在播放。

默认情况下，该属性值为 true，这意味着动画将立即开始播放。

注意：该属性会受到AnimatedImage 实际播放状态变化的影响。如果使用了非动画图像，则需要手动将playing 设置为true ，以便后续图像能够播放动画。

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

source : url

该属性存储指向源图像的 URL。

AnimatedImage 可处理 Qt 支持的任何图像格式，并可从 Qt 支持的任何 URL 方案加载。但它与QQuickImageProvider 不兼容。

sourceSize : size

该属性存储全帧图像的缩放后宽度和高度。

与用于调整图像绘制比例的 `width ` 和 `height ` 属性不同，该属性用于设置缓存帧所存储的最大像素数，从而确保大型动画不会占用超过必要的内存。

如果原始尺寸大于 `sourceSize`，则图像会被缩小。

通过将此属性设置为undefined ，可以恢复图像的原始大小。

另请参阅 Image::sourceSize 。

speed : real [since QtQuick 2.11]

该属性用于设置动画的速度。

速度以原始动画图像速度的百分比为单位。默认速度为 1.0（原始速度）。

该属性于 QtQuick 2.11 版本中引入。

信号文档

[since 6.12] finished()

当动画播放次数达到loops 指定的次数时，会发出此信号。

当playing 被手动设置为false 时，以及当动画的loops 属性被设置为AnimatedImage.Infinite 时，该信号不会被触发。

该信号于 Qt 6.12 中引入。