En esta página

Configuración del archivo de manifiesto de Qt para Android

El manifiesto de Android es un archivo XML imprescindible para cualquier aplicación de Android. Contiene la configuración de la aplicación en relación con los distintos ajustes y funciones que utiliza, así como detalles sobre la propia aplicación, como el nombre del paquete, el nombre de la aplicación, la versión, etc. Desde el manifiesto también se pueden configurar los permisos y las características de hardware.

Qt para Android mantiene una versión de AndroidManifest.xml con una configuración predeterminada que incluye características, permisos y otros ajustes utilizados por el sistema de compilación, necesarios para compilar y ejecutar aplicaciones Qt en Android.

Configuración del proyecto Qt en el manifiesto

Qt define algunos metadatos que se pasan desde los sistemas de compilación a ` androiddeployqt`, el cual rellena el manifiesto con los valores correctos sin necesidad de especificarlos explícitamente en el archivo de manifiesto. A dichos metadatos se les asigna un valor con el formato "-- %%INSERT_VALUE%% --", por ejemplo:

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

Este campo se rellenaría con el código de versión establecido, por ejemplo, en CMake.

Configuración predeterminada de Qt

Qt establece la siguiente configuración del manifiesto de forma predeterminada:

SecciónOpciónDescripción
<manifest>paqueteEstablece el nombre del paquete. El valor por defecto es org.qtproject.example.app_name.

Advertencia: Este campo está obsoleto y se ha trasladado a build.gradle. Se eliminará en una próxima versión.

android:installLocationEstablece la ubicación de instalación de la aplicación, ya sea en el almacenamiento interno o externo. El valor por defecto es auto.
android:versionCodeEstablece el código de versión interno. Se rellena a partir de ANDROID_VERSION_CODE (qmake) y QT_ANDROID_VERSION_CODE (CMake). El valor por defecto es 1.
android:versionNameEstablece el nombre público de la versión. Se rellena a partir de ANDROID_VERSION_NAME (qmake) y QT_ANDROID_VERSION_NAME (CMake). El valor por defecto es 1.0.
<supports-screens>Establece los tamaños de pantalla que admite la aplicación; los valores por defecto son anyDensity, largeScreens, normalScreens y smallScreens.
<application>android:nameEl nombre de la clase de la aplicación. El valor por defecto es org.qtproject.qt.android.bindings.QtApplication.
android:labelEtiqueta del nombre de la aplicación. El valor por defecto es el nombre del objetivo del proyecto Qt. Se puede configurar mediante QT_ANDROID_APP_NAME.
android:iconEl icono de la aplicación como referencia a un recurso «drawable» o «mipmap». Esta etiqueta no se utiliza a menos que se configure mediante QT_ANDROID_APP_ICON o se establezca manualmente en el archivo AndroidManifest.xml.
android:hardwareAcceleratedEstablece la preferencia de aceleración por hardware. El valor por defecto es « true ».
<activity>android:nameEl nombre de la clase de la actividad. El valor por defecto es org.qtproject.qt.android.bindings.QtActivity.
android:configChangesEnumera los cambios de configuración que gestiona la actividad. El valor por defecto es orientation, uiMode, screenLayout, screenSize, smallestScreenSize, layoutDirection, locale, fontScale, keyboard, keyboardHidden, navigation, mcc, mnc, density.
android:launchModeEl método utilizado para iniciar la actividad. El valor por defecto es « singleTop ».
android:screenOrientationLa orientación de la pantalla de la actividad en el dispositivo. El valor por defecto es unspecified.
<intent-filter>Especifica los tipos de intenciones a los que la actividad puede responder. El valor por defecto es
<action android:name="android.intent.action.MAIN"/>
<category android:name="android.intent.category.LAUNCHER"/>
android:exportedEstablece si la actividad puede ser iniciada por componentes de otras aplicaciones. El valor por defecto es true.

Metadatos específicos de Qt

Además de la configuración predeterminada del manifiesto que establece Qt, Qt define algunos metadatos que solo son válidos para aplicaciones Qt. Dichos metadatos suelen encontrarse en la sección « <activity> » con el siguiente formato:

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

A continuación se muestra una lista de dichos metadatos definidos por Qt:

Nombre del metadatoDescripción
android.app.lib_name El nombre del archivo de la biblioteca nativa de C++ que utiliza la actividad.

Nota: Este atributo es obligatorio y no debe eliminarse. El valor por defecto es el nombre del objetivo del proyecto Qt.

android.app.extract_android_styleEl método utilizado para extraer la información nativa de Android Style. Para obtener más información, consulta «Extracción de estilos». El valor por defecto es minimal.
android.app.background_running Establece si la aplicación mantiene tareas en ejecución en segundo plano. Establecer este valor en true equivale a establecer la variable de entorno QT_BLOCK_EVENT_LOOPS_WHEN_SUSPENDED en 0. El valor por defecto es false.

Advertencia: Establecer este valor en « true » puede provocar un fallo inesperado si la aplicación intenta dibujar después de que se envíe la señal « QGuiApplication::applicationStateChanged()» con el estado « Qt::ApplicationSuspended ».

android.app.arguments Establece una lista de argumentos que se pasarán a la aplicación "arg1 arg2". Se rellena a partir de ANDROID_APPLICATION_ARGUMENTS (qmake) y QT_ANDROID_APPLICATION_ARGUMENTS (CMake). No se ha establecido ningún valor por defecto.
android.app.splash_screen_drawable_portraitEstablece un elemento dibujable para una pantalla de inicio específica para el modo vertical. Por ejemplo: android:resource="@drawable/splash_portrait". No se ha establecido ningún valor por defecto.
android.app.splash_screen_drawable_landscapeEstablece un elemento dibujable para una pantalla de inicio específica para el modo horizontal. Por ejemplo: android:resource="@drawable/splash_landscape". No se ha establecido ningún valor por defecto.
android.app.splash_screen_drawableEstablece un elemento dibujable para la pantalla de inicio al iniciar la aplicación.

Nota: Primero se comprueban las pantallas de inicio específicaspara cada orientación ; si no se han establecido, se utiliza este valor en su lugar. Por ejemplo: android:resource="@drawable/splash". El valor por defecto no está establecido.

android.app.splash_screen_stickyEstablece si la pantalla de inicio permanece visible hasta que la aplicación la oculte explícitamente. Para obtener más información, consulta QAndroidApplication::hideSplashScreen().
android.app.trace_locationEspecifica una ubicación en el dispositivo donde la aplicación puede guardar archivos de rastreo. Por ejemplo: /storage/emulated/0/Android/data/<app_package_name>/files/. Esto es necesario cuando se utiliza el backend de rastreo Common Trace Format (CTF).

Nota: La aplicación necesita permiso de almacenamiento para esa ubicación. Por defecto: sin establecer.

Metadatos específicos de la aplicación

Algunos atributos de metadatos son válidos para toda la aplicación y deben incluirse en la sección « <application> »:

Nombre del metadatoDescripción
android.app.system_libs_prefix Especifica una ruta personalizada a las bibliotecas del sistema que se utilizará para la búsqueda de bibliotecas al cargarlas. Esto es necesario cuando se utilizan bibliotecas Qt instaladas fuera del directorio predeterminado de bibliotecas nativas (JNI) de una aplicación. El valor por defecto es /system/lib/.

Metadatos en los servicios

Algunos atributos de metadatos también se pueden utilizar en los servicios. Los principales son:

Permisos y funciones de Qt

Es posible que algunos módulos de Qt requieran determinados permisos o funciones de Android para funcionar correctamente; por ejemplo, el permiso de cámara en QtMultimedia. La herramienta androiddeployqt se encarga de incluir dichos requisitos en el manifiesto de Android durante la compilación. Qt define las siguientes líneas en el manifiesto, que posteriormente se sustituyen por los valores reales:

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

Nota: Si se eliminan esas líneas del manifiesto del proyecto, Qt no podrá incluir los permisos correctos. Por lo tanto, es posible que algunas funcionalidades no funcionen correctamente.

Personalización de permisos

Desde Qt 6.8.1, es posible anular los permisos predeterminados establecidos por los módulos de Qt. Esto resulta útil si necesitas definir los mismos permisos que utiliza un módulo de Qt, pero con atributos adicionales o diferentes.

Hay dos formas de hacerlo. La primera consiste en utilizar la función de CMake ` qt_add_android_permission ` en el archivo ` CMakeLists.txt` de la aplicación. Los permisos definidos de esta manera tienen prioridad sobre los mismos permisos definidos por los módulos de Qt, lo que evita la duplicación.

La segunda forma consiste en definir manualmente estos permisos en el archivo de manifiesto de Android. Los permisos definidos de esta manera tienen prioridad sobre los establecidos por los módulos de Qt o mediante ` qt_add_android_permission`.

Extracción de estilos

Qt utiliza diferentes métodos para determinar cómo deben aplicarse los estilos a los controles Qt Widgets y Qt Quick:

  • full: al utilizar controles Qt Widgets o Qt Quick 1.

    Nota: Este método ha quedado obsoleto, ya que utiliza algunas interfaces de Android que no forman parte del SDK y que Google restringió a partir de Android 9.0 (API 28). Se recomienda utilizar uno de los otros métodos.

  • default o minimal: cuando se utilicen controles Qt Quick 2 y no se utilicen controles Qt Widgets o Qt Quick 1. Esto es más rápido que utilizar las opciones «por defecto» o «completa».
  • none: sin extracción de estilos.

Manifiesto de Qt anterior a la versión 6.2

Las versiones de Qt anteriores a la 6.2 solían tener un conjunto adicional de metadatos definidos por Qt. Estos atributos se utilizaban para gestionar dependencias y algunos eran utilizados por el servicio Ministro, ya descontinuado. Con Qt 6.2, deben eliminarse. A continuación se muestra una lista de estos atributos:

  • 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.mensaje_de_ministro_no_encontrado
  • android.app.mensaje de «se necesita ministro»
  • android.app.mensaje_de_error_grave

Para obtener más información sobre el manifiesto de Android, consulta «Manifiesto de aplicaciones de 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.