Conceptos básicos de la sintaxis de QML
QML es un lenguaje multiparadigma que permite definir objetos en función de sus atributos y de cómo se relacionan y responden a los cambios en otros objetos. A diferencia del código puramente imperativo, en el que los cambios en los atributos y el comportamiento se expresan mediante una serie de sentencias que se procesan paso a paso, la sintaxis declarativa de QML integra los cambios de atributos y comportamiento directamente en las definiciones de cada objeto. Estas definiciones de atributos pueden incluir código imperativo, en los casos en que se requiera un comportamiento complejo y personalizado de la aplicación.
El motor suele cargar el código fuente de QML a través de documentos QML, que son documentos independientes de código QML. Estos pueden utilizarse para definir tipos de objetos QML que, a su vez, pueden reutilizarse en toda la aplicación. Ten en cuenta que los nombres de los tipos deben comenzar con una letra mayúscula para poder declararse como tipos de objetos QML en un archivo QML.
Instrucciones de importación
Un documento QML puede contener una o varias importaciones al principio del archivo. Una importación puede ser cualquiera de las siguientes:
- un módulo QML
- un directorio relativo que contenga definiciones de tipos en forma de documentos QML
- un archivo JavaScript
Las importaciones de archivos JavaScript deben especificarse de forma cualificada al importarlas, para que se pueda acceder a las propiedades y métodos que proporcionan.
La forma genérica de las distintas importaciones es la siguiente:
import <ModuleIdentifier> [<Version.Number>] [as <Qualifier>]import "<Directory>"import "<JavaScriptFile>" [as <ScriptIdentifier>]
Ejemplos:
import QtQuick 2.0import QtQuick.LocalStorage 2.0 as Databaseimport "../privateComponents"import "somefile.js" as Script
Consulta la documentación «Sintaxis de QML: sentencias de importación» para obtener información detallada sobre las importaciones en QML.
Declaraciones de objetos
Desde el punto de vista sintáctico, un bloque de código QML define un árbol de objetos QML que se van a crear. Los objetos se definen mediante declaraciones de objetos que describen el tipo de objeto que se va a crear, así como los atributos que se le van a asignar. Cada objeto también puede declarar objetos secundarios mediante declaraciones de objetos anidadas.
Una declaración de objeto consta del nombre de su tipo de objeto, seguido de un par de llaves. A continuación, todos los atributos y objetos hijos se declaran dentro de estas llaves.
A continuación se muestra una declaración de objeto sencilla:
Rectangle {
width: 100
height: 100
color: "red"
}Esto declara un objeto de tipo ` Rectangle`, seguido de un par de llaves que engloban los atributos definidos para ese objeto. El tipo ` Rectangle ` es un tipo que ofrece el módulo ` QtQuick `, y los atributos definidos en este caso son los valores de las propiedades ` width`, ` height ` y ` color ` del rectángulo. (Se trata de propiedades que ofrece el tipo ` Rectangle `, tal y como se describe en la documentación de ` Rectangle `.)
El motor puede cargar el objeto anterior si forma parte de un documento QML. Es decir, si el código fuente se complementa con una instrucción de importación que importe el módulo QtQuick (para que el tipo Rectangle esté disponible), tal y como se muestra a continuación:
import QtQuick 2.0
Rectangle {
width: 100
height: 100
color: "red"
}Cuando se incluye en un archivo ` .qml ` y lo carga el motor QML, el código anterior crea un objeto ` Rectangle ` utilizando el tipo ` Rectangle ` proporcionado por el módulo ` QtQuick `:

Nota: Si la definición de un objeto solo tiene un número reducido de propiedades, se puede escribir en una sola línea como se muestra a continuación, con las propiedades separadas por punto y coma:
Rectangle { width: 100; height: 100; color: "red" }Obviamente, el objeto Rectangle declarado en este ejemplo es realmente muy sencillo, ya que no define más que unos pocos valores de propiedad. Para crear objetos más útiles, una declaración de objeto puede definir muchos otros tipos de atributos: estos se tratan en la documentación sobre atributos de objetos de QML. Además, una declaración de objeto puede definir objetos hijos, tal y como se explica a continuación.
Objetos hijos
Cualquier declaración de objeto puede definir objetos hijos mediante declaraciones de objetos anidadas. De este modo, cualquier declaración de objeto declara implícitamente un árbol de objetos que puede contener cualquier número de objetos hijos.
Por ejemplo, la declaración de objeto Rectangle que se muestra a continuación incluye una declaración de objeto Gradient, que a su vez contiene dos declaraciones GradientStop:
import QtQuick 2.0
Rectangle {
width: 100
height: 100
gradient: Gradient {
GradientStop { position: 0.0; color: "yellow" }
GradientStop { position: 1.0; color: "green" }
}
}Cuando el motor carga este código, crea un árbol de objetos con un objeto Rectangle en la raíz; este objeto tiene un objeto hijo Gradient, que a su vez tiene dos hijos GradientStop.
Sin embargo, hay que tener en cuenta que se trata de una relación padre-hijo en el contexto del árbol de objetos QML, no en el contexto de la escena visual. El concepto de relación padre-hijo en una escena visual lo proporciona el tipo Item del módulo QtQuick, que es el tipo base para la mayoría de los tipos QML, ya que la mayoría de los objetos QML están pensados para ser representados visualmente. Por ejemplo, tanto « Rectangle » como « Text » son tipos basados en « Item », y a continuación se ha declarado un objeto « Text » como hijo visual de un objeto « Rectangle »:
import QtQuick 2.0
Rectangle {
width: 200
height: 200
color: "red"
Text {
anchors.centerIn: parent
text: "Hello, QML!"
}
}Cuando el objeto Text hace referencia a su valor parent en el código anterior, se refiere a su padre visual, no al padre en el árbol de objetos. En este caso, ambos son lo mismo: el objeto Rectangle es el padre del objeto Text tanto en el contexto del árbol de objetos QML como en el de la escena visual. Sin embargo, mientras que la propiedad parent puede modificarse para cambiar el padre visual, el padre de un objeto en el contexto del árbol de objetos no puede modificarse desde QML.
(Además, fíjate en que el objeto ` Text ` se ha declarado sin asignarlo a una propiedad de ` Rectangle`, a diferencia del ejemplo anterior, en el que se asignaba un objeto ` Gradient ` a la propiedad ` gradient ` del rectángulo. Esto se debe a que la propiedad ` children ` de ` Item ` se ha establecido como la propiedad predeterminada del tipo para permitir esta sintaxis más cómoda.)
Consulta la documentación sobre la relación de parentesco visual para obtener más información sobre el concepto de relación de parentesco visual con el tipo ` Item `.
Comentarios
La sintaxis para insertar comentarios en QML es similar a la de JavaScript:
- Los comentarios de una sola línea comienzan con // y terminan al final de la línea.
- Los comentarios de varias líneas comienzan con /* y terminan con */
Text {
text: "Hello world!" //a basic greeting
/*
We want this text to stand out from the rest so
we give it a large size and different font.
*/
font.family: "Helvetica"
font.pointSize: 24
}El motor ignora los comentarios al procesar el código QML. Son útiles para explicar qué hace una sección de código, ya sea como referencia para el futuro o para explicar la implementación a otras personas.
Los comentarios también se pueden utilizar para impedir la ejecución del código, lo que a veces resulta útil para localizar problemas.
Text {
text: "Hello world!"
//opacity: 0.5
}En el ejemplo anterior, el objeto ` Text ` tendrá una opacidad normal, ya que la línea `opacity: 0.5` se ha convertido en un comentario.
© 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.