如何为QML Android应用添加GIF动画启动页？

阿华AIGC实验室

2026-5-15

给QML Android应用添加GIF启动页（基于android-gif-drawable）

我明白你头疼的点——旧Android设备首次安装QML应用耗时太长，想加个GIF启动页还摸不着头绪，尤其是不会Java和XML的情况下。别慌，我给你一套完整的Hello World级别的步骤，跟着做就能搞定：

步骤1：添加android-gif-drawable依赖

打开你的QML项目对应的Android模块中的Module级build.gradle（不是Project级的），在dependencies块里添加一行：

implementation 'pl.droidsonroids.gif:android-gif-drawable:1.2.28'

（注：可以用最新版本号，去maven仓库搜一下就能找到）

步骤2：修改AndroidManifest.xml

找到项目里的AndroidManifest.xml，把默认的启动Activity替换成我们要写的闪屏页Activity：

<!-- 新增闪屏页Activity作为启动页 -->
<activity
    android:name=".SplashActivity"
    android:theme="@style/Theme.AppCompat.Light.NoActionBar">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

<!-- 原来的QtActivity保留，但去掉启动标记 -->
<activity android:name="org.qtproject.qt5.android.bindings.QtActivity"
    android:configChanges="orientation|uiMode|screenLayout|screenSize|smallestScreenSize|layoutDirection|locale|fontScale|keyboard|keyboardHidden|navigation|mcc|mnc|density"
    android:label="@string/app_name"
    android:screenOrientation="unspecified">
</activity>

步骤3：创建闪屏页布局XML

在res/layout目录下新建一个splash_layout.xml文件，内容如下：

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <!-- 加载GIF的控件 -->
    <pl.droidsonroids.gif.GifImageView
        android:id="@+id/gifImageView"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:src="@drawable/splash_gif" <!-- 替换成你的GIF文件名 -->
        android:scaleType="centerCrop"/>
</RelativeLayout>

记得把你的GIF文件放到res/drawable目录里，文件名改成 splash_gif.gif（或者和上面android:src里的名字一致，不要有大写和特殊字符）。

步骤4：编写闪屏页Java代码

在src/main/java/你的包名/目录下新建SplashActivity.java文件（包名要和Manifest里的一致，比如Qt Creator生成的包名一般是org.qtproject.example.你的项目名）：

package org.qtproject.example.yourapp; // 替换成你自己的包名

import android.content.Intent;
import android.os.Bundle;
import android.os.Handler;
import androidx.appcompat.app.AppCompatActivity;
import pl.droidsonroids.gif.GifImageView;

public class SplashActivity extends AppCompatActivity {
    // 方法1：固定延迟3秒后跳转（适合循环GIF）
    private static final int SPLASH_DELAY = 3000;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.splash_layout);

        // 固定延迟跳转逻辑
        new Handler().postDelayed(() -> {
            // 跳转到Qt的主Activity
            Intent intent = new Intent(SplashActivity.this, QtActivity.class);
            startActivity(intent);
            finish(); // 关闭闪屏页，防止返回键回到这里
        }, SPLASH_DELAY);

        // 方法2：监听GIF播放完毕再跳转（适合非循环GIF，注释掉上面的延迟代码，打开下面的代码）
        /*
        GifImageView gifImageView = findViewById(R.id.gifImageView);
        gifImageView.addAnimationListener(new pl.droidsonroids.gif.GifAnimationListener() {
            @Override
            public void onAnimationCompleted(int loopNumber) {
                Intent intent = new Intent(SplashActivity.this, QtActivity.class);
                startActivity(intent);
                finish();
            }

            @Override
            public void onAnimationStarted() {}
            @Override
            public void onAnimationReset() {}
        });
        */
    }
}