QML AnimatedImage 动画图像组件示例合集

1. 引言

在应用程序开发中，动画图像（如 GIF）的展示是一个常见需求。无论是加载动画、表情包展示，还是动态图标，AnimatedImage 组件都能提供便捷的解决方案。QML 的 AnimatedImage 组件继承自 Image，专门用于播放动画图像格式（如 GIF、MNG 等），并提供丰富的控制属性。

本文基于历史示例【QML AnimatedImage组件详解】进行优化和扩写，由于代码篇幅较长，文章中只显示关键部分，完整代码见下载链接。

2. 演示效果

项目中的 Main.qml 文件使用 Flow 布局展示了四种不同的 AnimatedImage 实现方案：

1. 播放 GIF：展示 AnimatedImage 最基本的用法，自动播放 GIF 动画
2. 播放/暂停控制：通过按钮控制动画的播放和暂停状态
3. 帧进度指示器：实时显示当前帧和总帧数，带进度条可视化
4. 播放速度控制：使用滑块动态调整动画播放速度

3. 代码说明

3.1 播放 GIF 基础用法

文件：Demo_BasicAnimatedImage.qml

运行效果：

基础用法展示了 AnimatedImage 最核心的功能：加载并播放 GIF 动画。

关键代码：

BaseRect { ColumnLayout { anchors.fill: parent anchors.margins: 15 spacing: 15 Text { text: "1. 播放GIF" font.pointSize: 13 font.bold: true } AnimatedImage { id: anim source: "qrc:/images/image2.gif" playing: true fillMode: Image.PreserveAspectFit Layout.fillWidth: true Layout.fillHeight: true } } }

代码说明：

这是最简单的 AnimatedImage 使用方式，只需设置source属性指定 GIF 文件路径即可自动播放。

要点：

• source属性指定动画图像的来源，支持本地文件、资源文件和网络 URL
• playing属性默认为true，动画加载后自动播放
• fillMode: Image.PreserveAspectFit保持图像比例缩放，避免变形
• AnimatedImage 继承自 Image，支持 Image 的所有属性（如 fillMode、sourceSize 等）

3.2 播放/暂停控制

文件：Demo_PlayPauseControl.qml

运行效果：

播放控制展示了如何通过按钮控制动画的播放、暂停和重置。

关键代码：

BaseRect { ColumnLayout { anchors.fill: parent anchors.margins: 15 spacing: 15 Text { text: "2. 播放/暂停控制" font.pointSize: 13 font.bold: true } AnimatedImage { id: anim source: "qrc:/images/image2.gif" paused: !playButton.checked Layout.fillWidth: true Layout.fillHeight: true fillMode: Image.PreserveAspectFit } RowLayout { Layout.fillWidth: true spacing: 10 Button { id: playButton checkable: true checked: true text: checked ? "暂停" : "播放" Layout.fillWidth: true } Button { text: "重置" Layout.fillWidth: true onClicked: { anim.currentFrame = 0 playButton.checked = true } } } } }

代码说明：

通过paused属性控制动画的暂停状态，通过currentFrame属性实现重置功能。

要点：

• paused属性控制动画是否暂停，true表示暂停，false表示播放
• playing属性表示动画是否正在播放（只读）
• currentFrame属性可读写，设置为 0 可重置动画到第一帧
• 使用checkable按钮实现播放/暂停的切换效果
• 这种用法适合需要用户手动控制动画播放的场景

3.3 帧进度指示器

文件：Demo_FrameProgress.qml

运行效果：

帧进度指示器展示了如何实时监控动画的播放进度。

关键代码：

BaseRect { property int frames: animation.frameCount ColumnLayout { anchors.fill: parent anchors.margins: 15 spacing: 10 Text { text: "3. 帧进度指示器" font.pointSize: 13 font.bold: true } AnimatedImage { id: animation source: "qrc:/images/image1.gif" Layout.fillWidth: true Layout.preferredHeight: 150 fillMode: Image.PreserveAspectFit } Rectangle { width: animation.width height: 8 radius: 4 color: "#E0E0E0" Layout.fillWidth: true Rectangle { width: parent.width * animation.currentFrame / frames height: parent.height radius: parent.radius color: "#2196F3" } } Text { text: "当前帧: " + animation.currentFrame + " / " + frames font.pointSize: 11 color: "#333" Layout.alignment: Qt.AlignHCenter } } }

代码说明：

通过currentFrame和frameCount属性实时获取播放进度，并用进度条可视化展示。

要点：

• currentFrame属性返回当前播放的帧索引（从 0 开始）
• frameCount属性返回动画的总帧数（只读）
• 进度条宽度 = 总宽度 × (当前帧 / 总帧数)
• 这种用法适合需要显示加载进度或动画进度的场景
• 注意：frameCount只有在图像完全加载后才有效

3.4 播放速度控制

文件：Demo_PlaybackSpeed.qml

运行效果：

播放速度控制展示了如何动态调整动画的播放速度。

关键代码：

BaseRect { ColumnLayout { anchors.fill: parent anchors.margins: 15 spacing: 15 Text { text: "4. 播放速度控制" font.pointSize: 13 font.bold: true } AnimatedImage { id: anim source: "qrc:/images/image1.gif" speed: speedSlider.value Layout.fillWidth: true Layout.fillHeight: true fillMode: Image.PreserveAspectFit } RowLayout { Layout.fillWidth: true spacing: 10 Text { text: "速度:" font.pointSize: 11 } Slider { id: speedSlider from: 0.1 to: 3.0 value: 1.0 stepSize: 0.1 Layout.fillWidth: true } Text { text: speedSlider.value.toFixed(1) + "x" font.pointSize: 11 color: "#2196F3" Layout.preferredWidth: 40 } } } }

代码说明：

通过speed属性控制动画播放速度，值为 1.0 表示正常速度。

要点：

• speed属性控制播放速度，默认值为 1.0（正常速度）
• speed < 1.0表示慢放，如 0.5x 为半速播放
• speed > 1.0表示快进，如 2.0x 为两倍速播放
• 结合 Slider 组件可实现平滑的速度调节
• 这种用法适合需要调节动画播放节奏的场景

4. 技术要点

4.1 AnimatedImage 属性一览

核心属性：

4.2 常用方法

AnimatedImage { id: anim source: "animation.gif" // 暂停动画 paused = true // 恢复播放 paused = false // 重置到第一帧 currentFrame = 0 // 跳转到指定帧 currentFrame = 10 // 设置播放速度 speed = 2.0 // 两倍速 }

4.3 支持的图像格式

AnimatedImage 支持以下动画图像格式：

注意：具体支持的格式取决于 Qt 的图像插件配置。

4.4 性能优化建议

1. 资源管理：对于大型 GIF，考虑使用sourceSize限制解码后的图像尺寸
2. 按需加载：不在可视区域时设置paused: true暂停播放
3. 内存控制：避免同时播放过多动画图像
4. 格式选择：WebP 格式通常比 GIF 更小、解码更快

4.5 AnimatedImage vs Image vs Movie

5. 工程下载

下载链接：QML AnimatedImage 动画图像组件示例合集