Qt for Android Manifest 文件配置

Android Manifest 是任何 Android 应用程序都必须使用的 XML 文件。它包含应用程序使用的不同设置和功能的应用程序配置，以及应用程序本身的详细信息，如软件包名称、应用程序名称、版本等。权限和硬件功能也可以从清单中设置。

Qt for Android 维护着一个具有默认配置的AndroidManifest.xml 版本，其中包括在 Android 上构建和运行 Qt 应用程序所需的功能、权限和构建系统使用的其他配置。

Qt 项目到 Manifest 的配置

Qt 定义了一些元数据，这些元数据会从构建系统传递给androiddeployqt，后者会用正确的值填充清单，而无需在清单文件中明确设置这些值。例如，这些元数据会以"-- %%INSERT_VALUE%% --" 的形式赋值：

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

例如，该值将由CMake 中设置的版本代码填充。

Qt 默认配置

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

部分	选项	说明
<manifest> 清单	软件包	设置软件包名称。默认值为`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	应用程序图标，作为对 drawable 或 mipmap 资源的引用。除非使用QT_ANDROID_APP_ICON或在`AndroidManifest.xml` 中手动设置，否则不会使用此标记。
	android:hardwareAccelerated	设置硬件加速首选项。默认值为`true` 。
	android:requestLegacyExternalStorage	是否使用 Android 权限存储。默认值是`true` 。
	android:allowBackup	是否允许应用程序参与备份和还原基础架构。如果设置为`false` ，应用程序将不会执行备份或还原。默认值为`true` 。
	android:fullBackupOnly	是否在可用的设备上使用自动备份。默认值为`false` 。
<活动	android:name	活动类名称。默认值是`org.qtproject.qt.android.bindings.QtActivity` 。
	android:configChanges	列出活动要处理的配置更改。默认值为`orientation`,`uiMode`,`screenLayout`,`screenSize`,`smallestScreenSize`,`layoutDirection`,`locale`,`fontScale`,`keyboard`,`keyboardHidden`,`navigation`,`mcc`,`mnc`,`density` 。
	android:launchMode	用于启动活动的方法。默认值是`singleTop` 。
	android:screenOrientation	活动在设备上的显示方向。默认值是`unspecified` 。
	<intent-filter> （意图筛选器	指定活动可以响应的意图类型。默认值为 <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	活动使用的本地 C++ 库的文件名。注意：此属性为强制属性，不应删除。默认值是 Qt 项目的目标名称。
android.app.extract_android_style	用于提取本地 Android 风格信息的方法。更多信息，请参阅样式提取。默认值为`minimal` 。
android.app.background_running	设置应用程序是否在后台持续运行任务。将其设置为`true` 相当于将环境变量`QT_BLOCK_EVENT_LOOPS_WHEN_SUSPENDED` 设置为`0` 。默认值为`false` 。警告：将此值设为`true` 可能会导致意外崩溃，如果应用程序在发送QGuiApplication::applicationStateChanged() 信号后试图以Qt::ApplicationSuspended 状态绘图。
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	为应用程序开始时的闪屏设置可绘制内容。注意：首先检查特定方向的闪屏，如果未设置，则使用此值。例如：`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 使用不同的方法来确定Qt Widgets 和Qt Quick Controls 的样式：

default 或 : 当使用或 1.full Qt Widgets Qt Quick Controls

注意： 该方法使用了一些 Android 非 SDK 接口，这些接口从 Android 9.0（API 28）开始被 Google 限制和移除。因此，不建议在 Android 9.0 或更高版本中使用此方法。
minimal当使用Qt Quick Controls 2 而不使用Qt Widgets 或Qt Quick Controls 1 时，建议您使用"..."。这比使用默认或完整选项更快。
none：无样式提取。

6.2 版之前的 Qt Manifest

早于 6.2 版本的 Qt 曾经有一组由 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_needed_msg
android.app.fatal_error_msg

有关 Android Manifest 的更多信息，请参阅Android 应用程序 Manifest。

为 Android Android 服务添加 OpenSSL 支持

© 2025 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.