Qt for Android 清单文件配置

Android 清单文件是任何 Android 应用都必不可少的 XML 文件。它包含应用所使用的各种设置和功能的配置信息，以及应用本身的详细信息，例如包名、应用名称、版本等。权限和硬件特性也可以通过清单文件进行设置。

Qt for Android 维护了一个AndroidManifest.xml 文件，其中包含默认配置，包括构建系统所使用的功能、权限以及其他配置，这些对于在 Android 上构建和运行 Qt 应用是必需的。

Qt 项目到清单配置

Qt 定义了一些元数据，这些元数据由构建系统传递给androiddeployqt，后者会自动在清单文件中填入正确的值，而无需在清单文件中显式设置。此类元数据的值采用"-- %%INSERT_VALUE%% --" 的形式，例如：

<manifest ...
    android:versionCode="-- %%INSERT_VERSION_CODE%% --"
    ...
</manifest>

该字段将填充来自（例如）CMake 中设置的版本代码。

Qt 默认配置

Qt 默认会设置以下清单配置：

部分	选项	说明
<manifest>	package	设置包名。默认值为`org.qtproject.example.app_name` 。警告：此字段已弃用，并已移至`build.gradle` 。它将在未来的版本中被移除。
	android:installLocation	设置应用的安装位置，即内部存储或外部存储。默认值为`auto` 。
	android:versionCode	设置内部版本代码。该值由`ANDROID_VERSION_CODE` （qmake）和`QT_ANDROID_VERSION_CODE` （CMake）生成。默认值为`1` 。
	android:versionName	设置公开的版本名称。该值由`ANDROID_VERSION_NAME` （qmake）和`QT_ANDROID_VERSION_NAME` （CMake）生成。默认值为`1.0` 。
	<supports-screens>	设置应用支持的屏幕尺寸，默认值为`anyDensity` 、`largeScreens` 、`normalScreens` 和`smallScreens` 。
<application>	android:name	应用程序类名。默认值为`org.qtproject.qt.android.bindings.QtApplication` 。
	android:label	应用程序名称标签。默认值为 Qt 项目的目标名称。可通过QT_ANDROID_APP_NAME 进行设置。
	android:icon	应用程序图标，作为对可绘制资源或 MIPMAP 资源的引用。除非通过QT_ANDROID_APP_ICON设置，或在`AndroidManifest.xml` 中手动设置，否则此标签不会被使用。
	android:hardwareAccelerated	设置硬件加速首选项。默认值为`true` 。
<activity>	android:name	活动类名称。默认值为`org.qtproject.qt.android.bindings.QtActivity` 。
	android:configChanges	列出该 Activity 处理的配置变更。默认值为`orientation` 、`uiMode` 、`screenLayout` 、`screenSize` 、`smallestScreenSize` 、`layoutDirection` 、`locale` 、`fontScale` 、`keyboard` 、`keyboardHidden` 、`navigation` 、`mcc` 、`mnc` 、`density` 。
	android:launchMode	用于启动 Activity 的方法。默认值为`singleTop` 。
	android:screenOrientation	活动在设备上的显示方向。默认值为`unspecified` 。
	<intent-filter>	指定活动可响应的 intent 类型。默认值为 `<action android:name="android.intent.action.MAIN"/> <category android:name="android.intent.category.LAUNCHER"/>`
	android:exported	设置该活动是否可由其他应用程序的组件启动。默认值为`true` 。

Qt 特定元数据

除了 Qt 设置的默认清单配置外，Qt 还定义了一些仅适用于 Qt 应用程序的元数据。此类元数据通常位于 `<activity> ` 部分，格式如下：

<meta-data
    android:name="meta-data-name"
    android:value="meta-data-value" />

以下是 Qt 定义的此类元数据列表：

元数据名称	描述
android.app.lib_name	该 Activity 所使用的原生 C++ 库的文件名。注意：此属性为必填项，不应删除。默认值为 Qt 项目的目标名称。
android.app.extract_android_style	用于提取原生 Android 样式信息的方法。有关详细信息，请参阅“样式提取”。默认值为`minimal` 。
android.app.background_running	用于设置应用是否在后台保持任务运行。将其设置为`true` 等同于将环境变量`QT_BLOCK_EVENT_LOOPS_WHEN_SUSPENDED` 设置为`0` 。默认值为`false` 。警告：如果应用程序在发送QGuiApplication::applicationStateChanged() 信号且状态为Qt::ApplicationSuspended 时尝试进行绘制，将此项设置为`true` 可能会导致意外崩溃。
android.app.arguments	设置要传递给应用`"arg1 arg2"` 的参数列表。该列表由`ANDROID_APPLICATION_ARGUMENTS` （qmake）和`QT_ANDROID_APPLICATION_ARGUMENTS` （CMake）填充。未设置默认值。
android.app.splash_screen_drawable_portrait	设置专用于纵向模式的启动画面可绘制资源。例如：`android:resource="@drawable/splash_portrait"` 。未设置默认值。
android.app.splash_screen_drawable_landscape	设置横向模式专属的启动画面可绘制资源。例如：`android:resource="@drawable/splash_landscape"` 。未设置默认值。
android.app.splash_screen_drawable	设置应用启动时的 splash 屏幕可绘制资源。注意：系统会优先检查针对特定方向的启动画面；若未设置，则使用此项。例如：`android:resource="@drawable/splash"` 。未设置默认值。
android.app.splash_screen_sticky	设置启动画面是否在被应用显式隐藏之前一直保持可见。有关更多信息，请参阅QAndroidApplication::hideSplashScreen()。
android.app.trace_location	指定设备上应用程序可保存跟踪文件的位置。例如：/storage/emulated/0/Android/data/<app_package_name>/files/。使用通用跟踪格式（CTF）跟踪后端时需要此设置。注意：应用程序需要该位置的存储权限。默认值：未设置。

应用程序特定元数据

某些元数据属性适用于整个应用程序，应放置在<application> 部分下：

元数据名称	描述
android.app.system_libs_prefix	指定用于库加载查找的自定义系统库路径。当使用安装在应用程序默认本机（JNI）库目录之外的 Qt 库时，此设置必不可少。默认值为`/system/lib/` 。

服务中的元数据

某些元数据属性也可用于服务中。主要包括：

Qt 权限与功能

不同的 Qt 模块可能需要某些 Android 权限或功能才能正常运行，例如，QtMultimedia 中的相机权限。androiddeployqt 工具会在构建过程中负责将此类要求纳入 Android 清单文件。Qt 会在清单文件中定义以下内容，这些内容随后会被实际值替换：

<manifest ...
    <!-- %%INSERT_PERMISSIONS -->
    <!-- %%INSERT_FEATURES -->
    ...
</manifest>

注意：如果 从项目清单文件中删除了这些行，Qt 将无法包含正确的权限。因此，某些功能可能无法正常工作。

自定义权限

从 Qt 6.8.1 开始，可以覆盖 Qt 模块设置的默认权限。如果您需要定义与某个 Qt 模块相同的权限，但希望添加额外或不同的属性，此功能将非常有用。

有两种方法可以实现这一点。第一种方法是在应用程序的CMakeLists.txt 中使用qt_add_android_permissionCMake 函数。通过这种方式定义的权限优先于 Qt 模块定义的相同权限，从而避免了重复。

第二种方法是在 Android 清单文件中手动定义这些权限。以这种方式定义的权限优先于由 Qt 模块设置的权限，或优先于使用qt_add_android_permission 设置的权限。

样式提取

Qt XML 采用不同的方法来确定Qt Widgets 和Qt Quick Controls 的样式：

full：使用Qt Widgets 或Qt Quick Controls 1 时。

注意：此方法 已过时，因为它使用了一些 Android 非 SDK 接口，而 Google 从 Android 9.0（API 28）开始限制了这些接口。您应使用其他方法之一。
default 或minimal ：当使用Qt Quick Controls 2 且未使用Qt Widgets 或Qt Quick Controls 1 时。此方法比使用默认或完整选项更快。
none：不进行样式提取。

6.2 版本发布前的 Qt Manifest

Qt 6.2 之前的版本曾包含一组由 Qt 定义的额外元数据。这些属性用于管理依赖关系，其中部分曾被已停用的Ministro 服务所使用。在 Qt 6.2 中，应将其移除。以下是这些属性的列表：

android.app.qt_sources_resource_id
android.app.repository
android.app.bundled_libs_resource_id
android.app.bundle_local_qt_libs
android.app.use_local_qt_libs
android.app.libs_prefix
android.app.load_local_libs_resource_id
android.app.load_local_jars
android.app.static_init_classes
android.app.qt_libs_resource_id
android.app.ministro_not_found_msg
android.app.ministro_所需_消息
android.app.fatal_error_msg

有关 Android 清单的更多信息，请参阅《Android 应用清单》。

为 Android 添加 OpenSSL 支持 Android 服务

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.