Qt 6.11 QML安卓项目如何实现刘海屏Edge-to-Edge模式？

问题场景 #

在Windows 10上开发Qt 6.11 Qt Quick安卓项目，目标设备为三星Galaxy A51。手动在系统设置-显示-刘海屏模式中开启可正常工作，但无法通过代码激活该模式，需编程实现Edge-to-Edge全屏模式。

修改方案 #

1. 调整AndroidManifest.xml配置 #

添加Qt全屏适配元数据，优化Activity窗口属性：

<?xml version="1.0"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="org.qtproject.example.appRoboX"
    android:installLocation="auto"
    android:versionCode="1"
    android:versionName="1.0">

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-feature android:name="android.hardware.camera" android:required="true" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

    <uses-permission android:name="android.permission.ACCESS_SURFACE_FLINGER" />
    <uses-feature android:name="android.hardware.opengl" android:required="true" />
    <supports-screens
        android:anyDensity="true"
        android:largeScreens="true"
        android:normalScreens="true"
        android:smallScreens="true" />

    <application
        android:name="org.qtproject.qt.android.bindings.QtApplication"
        android:hardwareAccelerated="true"
        android:label="RoboX"
        android:allowBackup="true"
        android:resizeableActivity="true"
        android:theme="@style/AppTheme"
        android:icon="@mipmap/ic_launcher">

        <uses-native-library android:name="libOpenCL.so"/>

        <activity
            android:name="org.qtproject.example.appRoboX.QtActivity"
            android:configChanges="orientation|uiMode|screenLayout|screenSize|smallestScreenSize|layoutDirection|locale|fontScale|keyboard|keyboardHidden|navigation|mcc|mnc|density"
            android:label="RoboX"
            android:launchMode="singleTop"
            android:screenOrientation="landscape"
            android:exported="true"
            android:theme="@style/AppTheme"
            android:windowSoftInputMode="adjustResize">

            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>

            <meta-data
                android:name="android.app.lib_name"
                android:value="appRoboX" />
            <meta-data android:name="android.app.fullscreen" android:value="true"/>
        </activity>
    </application>
</manifest>

2. 更新QtActivity.java代码 #

改用AndroidX API适配全屏和刘海屏，调整配置顺序：

package org.qtproject.example.appRoboX;

import android.os.Bundle;
import android.util.Log;
import android.view.Window;
import android.view.WindowManager;
import android.os.Build;
import androidx.core.view.WindowCompat;
import androidx.core.view.WindowInsetsCompat;
import androidx.core.view.WindowInsetsControllerCompat;

public class QtActivity extends org.qtproject.qt.android.bindings.QtActivity {
    private static final String TAG = "QtActivity";

    @Override
    public void onCreate(Bundle savedInstanceState) {
        configureWindow();
        super.onCreate(savedInstanceState);
        Log.d(TAG, "QtActivity onCreate");
    }

    private void configureWindow() {
        Window window = getWindow();
        if (window == null) return;

        // 启用Edge-to-Edge模式
        WindowCompat.setDecorFitsSystemWindows(window, false);
        WindowInsetsControllerCompat controller = WindowCompat.getInsetsController(window, window.getDecorView());
        if (controller != null) {
            controller.hide(WindowInsetsCompat.Type.statusBars() | WindowInsetsCompat.Type.navigationBars());
            controller.setSystemBarsBehavior(WindowInsetsControllerCompat.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE);
        }

        // 刘海屏适配
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
            WindowManager.LayoutParams params = window.getAttributes();
            params.layoutInDisplayCutoutMode = WindowManager.LayoutParams.LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES;
            window.setAttributes(params);
        }

        window.clearFlags(WindowManager.LayoutParams.FLAG_TRANSLUCENT_STATUS | WindowManager.LayoutParams.FLAG_TRANSLUCENT_NAVIGATION);
        window.addFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN);
    }
}

3. 修改Style.xml主题配置 #

使用Material主题提升兼容性：

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <style name="AppTheme" parent="Theme.MaterialComponents.DayNight.NoActionBar">
        <item name="android:windowLayoutInDisplayCutoutMode">shortEdges</item>
        <item name="android:windowNoTitle">true</item>
        <item name="android:windowFullscreen">true</item>
        <item name="android:windowBackground">@android:color/black</item>
    </style>
</resources>

4. 优化Main.qml配置 #

简化全屏设置逻辑：

ApplicationWindow {
    id: mainWindow
    visible: true
    width: Screen.width
    height: Screen.height
    visibility: Window.FullScreen
    flags: Qt.FramelessWindowHint
    color: "black"

    Component.onCompleted: {
        if (Qt.platform.os === "android") {
            mainWindow.visibility = Window.FullScreen
        }
    }
}

关键说明 #

• 三星Galaxy A51运行Android 10（API 29），需确保代码适配该版本及以上的全屏API
• 使用AndroidX的WindowCompat替代旧的SystemUiVisibility，兼容性更强
• 先配置窗口属性再调用super.onCreate，确保设置在Activity初始化时生效

内容的提问来源于stack exchange，提问作者al072