En esta página

Notas sobre la plataforma Android

Esta página contiene información específica sobre la compilación y ejecución de aplicaciones Qt en Android. Consulta «Versiones de Android compatibles» para saber qué versiones de Android y niveles de API son compatibles.

Consideraciones especiales sobre complementos e importaciones

Si una aplicación utiliza complementos que dependen de otros módulos, estos módulos deben figurar en la lista de dependencias de la aplicación. Para obtener más información, consulta «Detección de dependencias».

Qt GUI Dependencia

Dado que las aplicaciones de Android suelen incluir elementos de interfaz gráfica de usuario (GUI), el complemento Qt para Android está diseñado principalmente para proporcionar una GUI, por lo que implementa las diversas abstracciones de QPA. Como resultado, se espera que la implementación de una aplicación Qt para Android implique una dependencia de Qt GUI. Además, cabe destacar que Qt Creator solo admite compilaciones e implementaciones con Gradle, lo que significa que las ejecuciones desde la línea de comandos o el shell no son compatibles de forma predeterminada.

Tecla «Atrás» y gesto de «Atrás»

En Android, el gesto de «Atrás» (Android 13+) y la pulsación de la tecla «Atrás» del sistema constituyen una solicitud de navegación, no el cierre de una ventana. Si no hay ningún elemento que gestione la pulsación de «Atrás», esta envía la aplicación a segundo plano. La aplicación conserva su estado y se reanuda donde se quedó, en lugar de cerrarse.

Desde Qt 6.12, al pulsar la tecla «Atrás» la aplicación pasa a segundo plano mediante ` Activity.moveTaskToBack() ` y ya no genera un evento de cierre. Esto significa que las señales ` QWidget::closeEvent() ` y ` Window.onClosing ` no se activan cuando el usuario pulsa la tecla «Atrás». Si tu aplicación depende de estas señales para interceptar la pulsación de la tecla «Atrás», debe adoptar el enfoque de ` Shortcut ` que se muestra a continuación.

Para navegar dentro de la aplicación, por ejemplo, al abrir una página desde un StackView, gestiona la tecla «Atrás» y acepta el evento. Al aceptar el evento, se evita que Qt envíe la aplicación al segundo plano. La forma recomendada es un atajo a nivel de ventana vinculado a la secuencia de teclas Back, que se activa independientemente del elemento que tenga el foco activo:

Shortcut {
    sequences: ["Back"]
    enabled: Qt.platform.os === "android" && stack.depth > 1
    onActivated: stack.pop()
}

En Android, utiliza la secuencia « "Back" » en lugar de « StandardKey.Back ». La tecla estándar también está vinculada a « Backspace » y « Alt+Left », que activaría un teclado físico.

En la raíz de la pila, enabled se convierte en false, por lo que la pulsación del botón «Atrás» no tiene efecto y Qt envía la aplicación al segundo plano. Para advertir primero de los cambios no guardados, activa el atajo mientras haya cambios pendientes y muestra un mensaje de onActivated. Una vez gestionados los cambios, el atajo se desactiva y la siguiente pulsación del botón «Atrás» envía la aplicación al segundo plano.

Un elemento con el foco también puede gestionar Qt::Key_Back a través de Keys.onBackPressed, pero solo mientras mantenga el foco activo. Una interfaz táctil a menudo no deja ningún elemento con el foco, por lo que la pulsación del botón «Atrás» nunca llega a él. El atajo a nivel de ventana funciona independientemente del foco, por lo que es la opción más segura.

Consideraciones especiales sobre OpenGL

Los dispositivos modernos suelen ser compatibles con OpenGL ES 3.0 o 3.1, además de con la versión 2.0. Para obtener un contexto OpenGL adecuado, configura la versión solicitada mediante QSurfaceFormat::setVersion().

Nota: El uso de las funciones de OpenGL ES 3.x provocará que la aplicación deje de funcionar en dispositivos más antiguos que solo admiten la versión 2.0.

Problemas conocidos

Qt Creator Problemas de depuración

Consulta «Qt Creator: Problemas conocidos » para obtener más información.

Texto predictivo

Debido a un error en algunos dispositivos, al desactivar el texto predictivo con ` ImhNoPredictiveText`, esta propiedad se ignora y el texto predictivo sigue activado. Para solucionar esto, establece la variable de entorno ` QT_ANDROID_ENABLE_WORKAROUND_TO_DISABLE_PREDICTIVE_TEXT ` en ` 1`. Sin embargo, un efecto secundario es que esta variable de entorno puede causar problemas con otros teclados, como Gboard. Si utilizas un idioma como el japonés, con Gboard solo se muestra un teclado QWERTY. Esta variable de entorno se consulta cada vez que se muestra el teclado, por lo que es posible activar y desactivar la solución alternativa según sea necesario.

Almacenamiento en caché de glifos de texto

Debido a un error en algunos controladores de OpenGL, el mecanismo que utiliza Qt para almacenar en caché los glifos de texto no funciona como se espera en todos los dispositivos Android, lo que provoca que el texto aparezca distorsionado. Para solucionar esto, se ha implementado una solución alternativa, pero puede aumentar el consumo de memoria y también afectar al rendimiento de la representación del texto. Ahora, esta solución alternativa se utiliza de forma predeterminada en todos los dispositivos.

Puedes desactivar la solución alternativa estableciendo la variable de entorno ` QT_ANDROID_DISABLE_GLYPH_CACHE_WORKAROUND ` en 1 o `true`. Sin embargo, solo debes hacerlo tras comprobar que el texto se muestra correctamente en todos los dispositivos de destino.

Limitaciones

Es posible que algunos de los módulos o herramientas de Qt tengan funciones que no sean compatibles con Android o que presenten limitaciones. Consulta la documentación específica de cada módulo para conocer las limitaciones de cada plataforma.

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