LottieAnimation QML Type

一款适用于 Qt 的 Lottie 播放器。更多内容...

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

属性

• autoPlay : bool
• currentFrame : int (since 6.12)
• direction : enumeration
• endFrame : int
• frameRate : int
• loops : int
• quality : enumeration
• source : url
• startFrame : int
• status : enumeration

信号

• finished()

方法

• double getDuration(bool inFrames)
• void gotoAndPlay(int frame)
• bool gotoAndPlay(string frameMarker)
• void gotoAndStop(int frame)
• bool gotoAndStop(string frameMarker)
• void pause()
• void play()
• void start()
• void stop()
• void togglePause()

详细说明

LottieAnimation 类型用于显示 Lottie 格式的文件。

LottieAnimation 用于加载和渲染从 Adobe After Effects 导出的 Lottie 文件。目前仅支持 Lottie 完整规范中的一部分。最显著的差异包括：

• 仅支持“形状”图层
• 仅支持时间轴的整数帧模式（实际帧号和时间将四舍五入至最接近的整数）
• 不支持表达式

有关差异的完整列表，请参阅“限制”部分。

使用示例

以下示例展示了 LottieAnimation 类型的简单用法

LottieAnimation {
    loops: 2
    quality: LottieAnimation.MediumQuality
    source: "animation.json"
    autoPlay: false
    onStatusChanged: {
        if (status === LottieAnimation.Ready) {
            // any acvities needed before
            // playing starts go here
            gotoAndPlay(startFrame);
        }
    }
    onFinished: {
        console.log("Finished playing")
    }
}

渲染性能

在内部，渲染的帧数据会被缓存以提升性能。您可以通过设置 QLOTTIE_RENDER_CACHE_SIZE 环境变量（默认值为 2）来控制内存使用量。

您可以通过启用以下两个日志类别来监控渲染性能：

• qt.lottieqt.lottie.render - 提供有关动画渲染过程的信息
• qt.lottieqt.lottie.render.thread - 提供渲染过程的进展信息。

具体而言，您可以监控帧缓存是否持续满载，或者渲染过程是否需要等待帧准备就绪。第一种情况表明动画过于复杂，渲染无法跟上进度。请尝试简化动画，或优化 QML 场景。

属性文档

autoPlay : bool

用于指定动画文件加载完成后，播放器是否会自动开始播放动画。

默认值为true 。

currentFrame : int [read-only, since 6.12]

当前显示的动画帧编号。

该属性自 Qt 6.12 起引入。

direction : enumeration

该属性保存渲染方向。

endFrame : int [read-only]

动画结束时的帧号。该值在动画加载完毕且准备就绪后可用。

frameRate : int

该属性保存 Lottie 动画的帧率值。

frameRate 该值会在资源加载完成后发生变化。在此之前，更改帧率不会产生效果，因为资源中定义的值会覆盖该值。若要更改帧率，可以这样写：

LottieAnimation {
    source: "animation.json"
    onStatusChanged: {
        if (status === LottieAnimation.Ready)
            frameRate = 60;
    }

loops : int

该属性用于指定播放器将重复的循环次数。值LottieAnimation.Infinite 表示播放器将连续重复该动画。

默认值为1 。

quality : enumeration

指定 Lottie 播放器的渲染质量。如果选择“LowQuality ”，渲染将进行到帧缓冲区对象中；而选择其他选项时，渲染将进行到QImage 上（该对象随后会渲染到屏幕上）。

source : url

LottieAnimation 播放的 Lottie 资源的来源。

LottieAnimation 可处理 Qt 支持的任何 URL 方案。URL 可以是绝对路径，也可以是相对于组件 URL 的相对路径。

设置 source 属性将异步开始加载动画。若要监控加载进度，请连接到status 的 change 信号。

startFrame : int [read-only]

动画起始帧号。该值在动画加载完毕且准备好播放后方可获取。

status : enumeration

该属性保存了LottieAnimation 元素的当前状态。

例如，您可以实现onStatusChanged 信号处理程序来监控动画的加载进度，具体如下：

LottieAnimation {
    source: "animation.json"
    autoPlay: false
    onStatusChanged: {
        if (status === LottieAnimation.Ready)
            start();
    }

信号文档

finished()

当播放器完成播放时，会发出此信号。如果处于循环播放状态，则在最后一个循环结束时发出此信号。

方法文档

double getDuration(bool inFrames)

返回当前正在播放的资源的时长。

如果给定的inFrames 为true ，则返回值以帧数为单位表示时长。否则，返回以秒为单位的时长。

void gotoAndPlay(int frame)

播放来自指定frame 的资源。

bool gotoAndPlay(string frameMarker)

从包含具有指定frameMarker 标记的帧开始播放该资源。如果找到了frameMarker，则返回true ；否则返回false 。

void gotoAndStop(int frame)

将播放头移动到指定的frame 处并停止。

bool gotoAndStop(string frameMarker)

将播放头移动到指定的标记处并停止。如果检测到frameMarker ，则返回true ；否则返回false 。

void pause()

暂停播放。

void play()

从当前位置开始或继续播放。

void start()

从头开始播放动画。

void stop()

停止播放并返回startFrame 。

void togglePause()

在“播放”和“暂停”状态之间切换播放器的状态。