En esta página

Primeros pasos con QML

Creación de un documento QML

Un documento QML define una jerarquía de objetos con un diseño estructurado y de fácil lectura. Cada documento QML consta de dos partes: una sección de importaciones y una sección de declaración de objetos. Los tipos y la funcionalidad más habituales en las interfaces de usuario se proporcionan en la importación QtQuick.

Importación y uso del módulo QtQuick

Para utilizar el Qt Quick módulo, un documento QML debe importarlo. La sintaxis de importación es la siguiente:

import QtQuick

¡Los tipos y las funcionalidades que Qt Quick ahora se pueden utilizar en el documento QML.

Definición de una jerarquía de objetos

La declaración de objetos en un documento QML define lo que se mostrará en la escena visual. Qt Quick proporciona los componentes básicos para todas las interfaces de usuario, como los objetos para mostrar imágenes y texto y para gestionar las entradas del usuario.

Una declaración de objeto sencilla podría ser una ventana de color con algo de texto centrado en ella:

Window {
    width: 640
    height: 480
    visible: true
    color: "red"

    Text {
        anchors.centerIn: parent
        text: "Hello, World!"
    }
}

Esto define una jerarquía de objetos con un objeto raíz ` Window ` que tiene un objeto hijo ` Text `. La propiedad ` parent ` del objeto ` Text ` se establece automáticamente en ` Window`, y de forma similar, QML añade el objeto ` Text ` a la propiedad ` children ` del objeto ` Window `.

Poniéndolo todo junto

Los tipos « Window » y « Text » utilizados en el ejemplo anterior se proporcionan mediante la importación « QtQuick ». Al combinar la importación y la declaración del objeto, obtenemos un documento QML completo:

import QtQuick

Window {
    width: 640
    height: 480
    visible: true
    color: "red"

    Text {
        anchors.centerIn: parent
        text: "Hello, World!"
    }
}

Si guardamos ese documento como «HelloWorld.qml», podemos cargarlo y visualizarlo.

Creación y ejecución de proyectos QML

Para mostrar la escena gráfica definida por el documento QML, se puede cargar con Qt Creator. Para crear un nuevo proyecto QML en Qt Creator:

  1. Selecciona « File » > « New Project » > Qt Quick Application desde Qt Creator.
  2. Introduce un nombre para tu proyecto y selecciona una ubicación para guardarlo.
  3. Selecciona la versión adecuada de Qt y, si lo deseas, configura los ajustes de control de versiones para el proyecto.
  4. Revisa el resumen de la configuración de tu proyecto y continúa para completar la compilación del proyecto.

Una vez finalizada, « Qt Creator » generará los archivos necesarios y abrirá el proyecto para su desarrollo. Al pulsar el botón verde «Run» se ejecuta la aplicación. Deberías ver el texto «Hello, World!» en el centro de un rectángulo rojo.

Para obtener más información sobre cómo crear y ejecutar proyectos en « Qt Creator », visita las siguientes páginas:

Creación de aplicaciones QML con controles

Aunque Qt Quick proporciona elementos gráficos básicos, Qt Quick Controls ofrece tipos QML ya preparados para su uso en una aplicación.

Insertar el tipo « ApplicationWindow » es un buen punto de partida para crear aplicaciones. La interfaz de usuario de una aplicación tiene este diseño básico:

Diseño de la ventana de la aplicación con barra de menús, barra de herramientas, área de contenido y barra de estado

Dentro de cada área, se pueden añadir y conectar diferentes controles para formar una aplicación. Por ejemplo, el siguiente fragmento de código muestra una aplicación básica que ilustra el uso del espacio disponible:

//import related modules
import QtQuick
import QtQuick.Controls

//window containing the application
ApplicationWindow {
    width: 640
    height: 480
    visible: true
    //title of the application
    title: qsTr("Hello World")

    //menu containing two menu items
    header: MenuBar {
        Menu {
            title: qsTr("&File")
            Action {
                text: qsTr("&Open...")
                onTriggered: console.log("Open action triggered")
            }
            MenuSeparator { }
            Action {
                text: qsTr("&Exit")
                onTriggered: Qt.quit()
            }
        }
    }

    //Content Area

    //a button in the middle of the content area
    Button {
        text: qsTr("Hello World")
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.verticalCenter: parent.verticalCenter
    }
}

La aplicación tiene dos elementos de menú y un botón en el centro. Al hacer clic en el elemento de menú « Exit », se cierra la aplicación.

También hay diferentes métodos de navegación y distintos controles, como botones y controles deslizantes. Los siguientes ejemplos están disponibles en Qt Creator y muestran diferentes controles y diseños.

No dudes en copiar y pegar los fragmentos de código en esta sencilla aplicación «Hello World» para ver cómo funciona QML.

Gestión de la entrada del usuario

Una de las grandes ventajas de utilizar QML para definir una interfaz de usuario es que permite al diseñador de la interfaz definir cómo debe reaccionar la aplicación ante los eventos mediante sencillas expresiones de JavaScript. En QML, nos referimos a esos eventos como señales, y estas señales son gestionadas por controladores de señales.

Por ejemplo, fíjate en el siguiente ejemplo:

import QtQuick

Window {
    id: root
    width: 200
    height: 100
    color: isRed ? "red" : "blue"
    visible: true

    property bool isRed: true  // Track the color state

    Text {
        anchors.centerIn: parent
        text: "Hello, World!"
    }

    TapHandler {
        onTapped: root.isRed = !root.isRed  // Toggle state
    }
}

Este ejemplo se puede guardar como «ClickableHelloWorld.qml» y ejecutarse con qml, la herramienta «QML Runtime ». Cada vez que el usuario haga clic en cualquier parte de la ventana, el rectángulo cambiará de rojo a azul. Al volver a tocarlo, volverá a ponerse rojo.

Nota: TapHandler también emite la señal «tapped» para eventos táctiles, por lo que este código también funcionará en un dispositivo móvil.

La entrada del usuario mediante el teclado se puede gestionar de forma similar con una sencilla expresión:

import QtQuick

Window {
    id: root
    width: 200
    height: 100
    color: "red"
    visible: true

    Text {
        id: myText
        anchors.centerIn: parent
        text: toggle ? "Hello, World!" : "Goodbye, World!"
        focus: true
        property bool toggle: true
        Keys.onReturnPressed: (event)=>{
            myText.toggle = !myText.toggle;
            event.accepted = true;
        }
    }
}

Ahora, cada vez que pulses la tecla Intro, el texto alternará entre «Hello, World» y «Goodbye, World».

Enlaces de propiedades

Los objetos y sus propiedades constituyen la base de una interfaz gráfica definida en un documento QML. El lenguaje QML permite vincular propiedades entre sí de diversas formas, lo que hace posible crear interfaces de usuario muy dinámicas.

En el siguiente ejemplo, la geometría de cada elemento secundario Rectangle está vinculada a la del elemento principal Window. Si la geometría del objeto principal Window cambiara, la geometría de cada elemento secundario Rectangle se actualizaría automáticamente gracias a los enlaces de propiedades.

import QtQuick

Window {
    id: root
    width: 200
    height: 100
    color: "red"
    visible: true


    Rectangle {
        width: root.width / 2
        height: root.height
        color: "blue"
    }

    Rectangle {
        width: root.width / 2
        height: root.height
        x: root.width / 2
        color: "green"
    }
}

Animaciones

Las propiedades también se pueden actualizar dinámicamente mediante animaciones. La importación QtQuick proporciona varios tipos de animación que se pueden utilizar para animar los cambios en el valor de una propiedad. En el siguiente ejemplo, se anima una propiedad que luego se muestra en un área Text:

import QtQuick

Window {
    id: root
    width: 200
    height: 100
    color: "red"
    visible: true

    property int animatedValue

    SequentialAnimation on animatedValue {
        loops: Animation.Infinite
        PropertyAnimation {
            to: 150
            duration: 1000
        }
        PropertyAnimation {
            to: 0
            duration: 1000
        }
    }

    Text {
        anchors.centerIn: parent
        text: root.animatedValue
    }
}

El valor que se muestra variará periódicamente entre 0 y 150.

Definición de tipos QML personalizados para su reutilización

Uno de los conceptos más importantes en QML es el de la reutilización de tipos. Es probable que una aplicación cuente con múltiples tipos visuales que sean similares entre sí (por ejemplo, varios botones), y QML permite definir este tipo de elementos como tipos personalizados reutilizables, con el fin de minimizar la duplicación de código y maximizar la legibilidad.

Por ejemplo, imagina que el desarrollador define un nuevo tipo « MessageLabel » en el archivo « MessageLabel.qml »:

// MessageLabel.qml
import QtQuick

Rectangle {
    height: 50
    property string message: "debug message"
    property var msgType: ["debug", "warning" , "critical"]
    color: "black"

    Column {
        anchors.fill: parent
        padding: 5.0
        spacing: 2
        Text {
            text: msgType.toString().toUpperCase() + ":"
            font.bold: msgType == "critical"
            font.family: "Terminal Regular"
            color: msgType === "warning" || msgType === "critical" ? "red" : "yellow"
            ColorAnimation on color {
                running: msgType == "critical"
                from: "red"
                to: "black"
                duration: 1000
                loops: msgType == "critical" ? Animation.Infinite : 1
            }
        }
        Text {
            text: message
            color: msgType === "warning" || msgType === "critical" ? "red" : "yellow"
            font.family: "Terminal Regular"
        }
    }

}

Ese tipo puede reutilizarse ahora varias veces en la aplicación, de la siguiente manera:

// application.qml
import QtQuick
Window {
    id: root
    width: 180
    height: 180
    visible: true
    Column {
        anchors.fill: parent
        padding: 1.5
        topPadding: 10.0
        bottomPadding: 10.0
        spacing: 5
        MessageLabel{
            width: root.width - 2
            msgType: "debug"
        }
        MessageLabel {
            width: root.width - 2
            message: "This is a warning!"
            msgType: "warning"
        }
        MessageLabel {
            width: root.width - 2
            message: "A critical warning!"
            msgType: "critical"
        }
    }
}

De esta forma, los tipos modulares de la interfaz de usuario se ensamblan y reutilizan dentro de una aplicación.

Consulta «Atributos de objetos QML» para obtener más detalles sobre cómo desarrollar tus propios componentes reutilizables.

Próximos pasos

Ahora que has visto QML en acción, estás listo para dar el siguiente paso. La página siguiente te guiará en tu viaje con QML.

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