En esta página

Introducción a Qt para Android

Este tutorial describe cómo utilizar Qt Creator para desarrollar una aplicación « Qt Quick » para dispositivos Android.

Desarrollarás una aplicación « Qt Quick » que acelera una imagen SVG (Scalable Vector Graphics) en función de los valores cambiantes del acelerómetro.

Ejemplo de «Accelerate Bubble»

Configurar el entorno de desarrollo

Para empezar a utilizar Qt para Android:

  1. Descarga e instala Qt. Para ello, sigue las instrucciones de la página «Obtener e instalar Qt ».
  2. Instala todas las herramientas necesarias y configura el entorno de desarrollo tal y como se explica en «Requisitos previos de Qt para Android».

Crea el proyecto

  1. Abre Qt Creator. Ve a « File » > « New Project » > « Application (Qt) » > Qt Quick Application.

    Cuadro de diálogo «Nuevo proyecto»

  2. Selecciona « Choose... » para abrir el cuadro de diálogo « Project Location ».
  3. En « Name », introduce un nombre para la aplicación.

    Cuadro de diálogo «Ubicación del proyecto»

  4. En « Create in », introduce la ruta de acceso a los archivos del proyecto. Puedes mover las carpetas del proyecto más adelante sin problemas.
  5. Selecciona « Next » (o « Continue » en macOS) para abrir el cuadro de diálogo « Define Project Details ».

    Cuadro de diálogo «Definir detalles del proyecto»

  6. Selecciona « Next » (o « Continue » en macOS) para abrir el cuadro de diálogo « Kit Selection ».
  7. Selecciona los kits correspondientes a las plataformas para las que deseas compilar la aplicación.

    Selección de kits para el proyecto

    Nota: La lista muestra los kits que se especifican en « Preferences » > « Kits ». Para obtener más información, consulta «Añadir kits » y «Gestionar kits».

  8. Selecciona « Next » (o « Continue » en macOS) para abrir el cuadro de diálogo « Project Management ».
  9. Revisa la configuración del proyecto y selecciona « Finish » (o « Done » en macOS) para crear el proyecto.

    Cuadro de diálogo «Gestión de proyectos»

Añade imágenes como recursos

La vista principal de la aplicación muestra una imagen SVG en forma de burbuja que se desplaza por la pantalla al inclinar el dispositivo.

Para que la imagen aparezca al ejecutar la aplicación, debes especificarla como recurso en el argumento « RESOURCES » del método « qt_add_qml_module() » del archivo « CMakeLists.txt » que el asistente ha creado para ti:

qt_add_qml_module(appaccelbubble
    URI accelbubble
    QML_FILES Main.qml
    RESOURCES Bluebubble.svg
)

Crear la vista principal de Accelbubble

  1. En la vista « Projects », selecciona « Main.qml ». En el archivo « Main.qml », sustituye el contenido por el siguiente código:
    import QtQuick
    import QtQuick.Controls.Material
    
    ApplicationWindow {
        id: mainWindow
        width: 320
        height: 480
        visible: true
        title: qsTr("Accelerate Bubble")
        Image {
            id: bubble
            source: "Bluebubble.svg"
            smooth: true
        }
    
    }

    Este código modifica las propiedades predeterminadas de « Window » y añade la imagen que acabas de añadir a la vista. Puedes utilizar cualquier otra imagen o componente en su lugar.

  2. Añade propiedades personalizadas para colocar la imagen en función del ancho y la altura de la ventana principal:
    import QtQuick
    import QtQuick.Controls.Material
    
    ApplicationWindow {
        id: mainWindow
        width: 320
        height: 480
        visible: true
        title: qsTr("Accelerate Bubble")
        Image {
            id: bubble
            source: "Bluebubble.svg"
            smooth: true
            property real centerX: mainWindow.contentItem.width / 2
            property real centerY: mainWindow.contentItem.height / 2
            property real bubbleCenter: bubble.width / 2
            x: centerX - bubbleCenter
            y: centerY - bubbleCenter
        }
    
    }
  3. Añade la siguiente instrucción de importación:
    import QtSensors

    Es necesaria porque queremos mover la burbuja en función de los valores del sensor del acelerómetro.

  4. Añade el componente « Accelerometer » con las propiedades necesarias:
    import QtQuick
    import QtQuick.Controls.Material
    import QtSensors
    ApplicationWindow {
        id: mainWindow
        ...
        Accelerometer {
            id: accel
            dataRate: 100
            active: true
        }
        ...
  5. Añade las siguientes funciones JavaScript que calculan la posición x e y de la burbuja en función de los valores actuales del acelerómetro:
    import QtQuick
    import QtQuick.Controls.Material
    import QtSensors
    ApplicationWindow {
        id: mainWindow
        ...
        Accelerometer {
            id: accel
        ...
        }
        function calcPitch(x,y,z) {
            return -Math.atan2(y, Math.hypot(x, z)) * mainWindow.radians_to_degrees;
        }
        function calcRoll(x,y,z) {
            return -Math.atan2(x, Math.hypot(y, z)) * mainWindow.radians_to_degrees;
        }
        ...
  6. Añade el siguiente código JavaScript para la señal « onReadingChanged » del componente «Accelerometer», de modo que la burbuja se mueva cuando cambien los valores del acelerómetro:
        Accelerometer {
            id: accel
            dataRate: 100
            active: true
            onReadingChanged: {
                var newX = (bubble.x + calcRoll(accel.reading.x, accel.reading.y, accel.reading.z) * .1)
                var newY = (bubble.y - calcPitch(accel.reading.x, accel.reading.y, accel.reading.z) * .1)
    
                if (isNaN(newX) || isNaN(newY))
                    return;
    
                if (newX < 0)
                    newX = 0
    
                if (newX > mainWindow.contentItem.width - bubble.width)
                    newX = mainWindow.contentItem.width - bubble.width
    
                if (newY < 0)
                    newY = 0
    
                if (newY > mainWindow.contentItem.height - bubble.height)
                    newY = mainWindow.contentItem.height - bubble.height
    
                bubble.x = newX
                bubble.y = newY
            }
        }

    Debes asegurarte de que la posición de la burbuja se mantenga siempre dentro de los límites de la pantalla. Si el acelerómetro devuelve un valor que no es un número (NaN), dicho valor se ignora y la posición de la burbuja no se actualiza.

  7. Añade un comportamiento « SmoothedAnimation » a las propiedades « x » y « y » de la burbuja para que su movimiento resulte más fluido.
        Image {
            id: bubble
            source: "Bluebubble.svg"
            smooth: true
        ...
            Behavior on y {
                SmoothedAnimation {
                    easing.type: Easing.Linear
                    duration: 100
                }
            }
            Behavior on x {
                SmoothedAnimation {
                    easing.type: Easing.Linear
                    duration: 100
                }
            }
        ...

Bloquear la orientación del dispositivo

De forma predeterminada, la pantalla gira cuando la orientación del dispositivo cambia entre vertical y horizontal. Esta aplicación se ve mejor si bloqueas la orientación de la pantalla en modo vertical.

En Android, la orientación de la pantalla se configura en el archivo « AndroidManifest.xml », que se genera en « Qt Creator ». Para bloquear la orientación en modo vertical:

  1. Ve a Tools > Android > Manifest XML Source. Qt Creator crea el archivo en un directorio «android» dentro del directorio de tu proyecto y lo abre en el editor de manifiestos.
  2. En el editor de manifiestos, selecciona « XML Source » y establece el atributo « android:screenOrientation » del elemento « activity » en « portrait ».
    <?xml version='1.0'?>
    <manifest ...>
        <supports-screens.../>
        <!--%%INSERT_PERMISSIONS-->
        <!--%%INSERT_FEATURES-->
        <application ...>
            <activity ... android:screenOrientation="portrait">
        ...

    Para obtener más información, consulta Editar archivos de manifiesto de Android.

Añadir dependencias

La aplicación utiliza los módulos « Qt Sensors » y « Qt SVG », por lo que debes añadirlos como dependencias en el archivo « CMakeLists.txt ». Para añadir las dependencias:

  1. Añade los componentes Sensors y Svg a la función find_package. Esto indica a CMake que busque la instalación de Qt e importe los módulos:
    find_package(Qt6 REQUIRED COMPONENTS Quick Sensors Svg)
  2. Añade los objetivos importados a la función target_link_libraries:
    target_link_libraries(appaccelbubble
        PRIVATE Qt6::Quick Qt6::Sensors Qt6::Svg)

    Esto indica a CMake que el ejecutable ` accelbubble ` utiliza los módulos. A continuación, CMake pasa los argumentos necesarios al enlazador, así como los directorios de inclusión y las definiciones de compilador adecuadas al compilador de C++.

  3. Para aplicar los cambios de configuración, ve a « Build » y selecciona « Run CMake ».

Para obtener más información sobre el archivo « CMakeLists.txt », consulta «Introducción a CMake».

Nota: Si no ha instalado todos los módulos de Qt que figuran en find_package(), Qt Creator le preguntará si desea instalarlos con Qt Online Installer.

Ejecuta la aplicación

Ahora puede implementar la aplicación en un dispositivo Android real o virtual.

Si utilizas un dispositivo real:

  1. Activa la depuración USB en el dispositivo Android.
  2. Conecta el dispositivo al ordenador de desarrollo.

Si tienes varios dispositivos conectados, « Qt Creator » te permite seleccionar el dispositivo en el que quieres ejecutar la aplicación.

Elige el dispositivo en el que quieres ejecutar la aplicación

Para ejecutar la aplicación en el dispositivo, pulsa Ctrl+R (Cmd+R).

Una vez que la aplicación se haya iniciado en el dispositivo, puedes inclinarlo para ver cómo se mueve la burbuja por la pantalla. La burbuja se mueve en la dirección de la inclinación, y la velocidad del movimiento depende del ángulo de inclinación. La burbuja se mueve más rápido cuanto más inclinas el dispositivo.

Véase también Qt Academy: Primeros pasos con Qt para Android, Cómo: Diseñar interfaces de usuario par Qt Quick, Diseño de interfaces de usuario par Qt Quick y Diseño de interfaces de usuario para Qt Quick.

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