Estructura de un documento QML
Un documento QML es un fragmento autónomo de código fuente QML que consta de tres partes:
- Una lista opcional de pragmas
- Sus sentencias de importación
- Una única declaración de objeto raíz
Por convención, una única línea en blanco separa las importaciones de la definición de la jerarquía de objetos.
Los documentos QML siempre se codifican en formato UTF-8.
Pragmas
Los pragmas son instrucciones dirigidas al propio motor de QML que pueden utilizarse para especificar determinadas características de los objetos del archivo actual o para modificar la forma en que el motor interpreta el código. A continuación se explican en detalle los siguientes pragmas.
| pragma | valores | valor por defecto | desde |
|---|---|---|---|
| Singleton | 5.2 | ||
| ListPropertyAssignBehavior | Añadir | X | 6.3 |
| Reemplazar | 6.3 | ||
| Reemplazar si no es el valor predeterminado | 6.3 | ||
| Comportamiento del componente | Enlazado | 6.4 | |
| Sin vincular | X | 6.4 | |
| Comportamiento de la firma de la función | Ignorado | 6.5 | |
| Obligatorio | X | 6.5 | |
| NativeMethodBehavior | AceptarEsteObjeto | 6,5 | |
| RechazarEsteObjeto | X | 6,5 | |
| Comportamiento del tipo de valor | Referencia | X | 6.5 |
| Copiar | 6.5 | ||
| Direccionable | 6,6 | ||
| No direccionable | X | 6.6 | |
| Asignable | 6,8 | ||
| Traductor | <contexto de traducción> | <nombre de archivo> | 6,7 |
Singleton
pragma Singleton declara el componente definido en la raíz del documento QML como singleton. Consulta «Singletons en QML» para obtener más información.
ListPropertyAssignBehavior
Con este pragma se puede definir cómo se gestionarán las asignaciones a propiedades de lista en los componentes definidos en el documento QML. Por defecto, al asignar un valor a una propiedad de lista, este se añade al final de la lista. Puede solicitar explícitamente este comportamiento utilizando el valor Append. Alternativamente, puede solicitar que el contenido de las propiedades de lista se sustituya siempre utilizando Replace, o que se sustituya si la propiedad no es la propiedad por defecto utilizando ReplaceIfNotDefault.
Consideremos un tipo base en un documento Base.qml:
pragma ListPropertyAssignBehavior: ReplaceIfNotDefault
import QtQuick
Item {
objectName: "outer"
default property list<Item> d: [
Item { objectName: "inner" }
]
property list<Item> notDefault: [
Item { objectName: "one" }
]
}Entonces, si se deriva de Base y se modifican sus propiedades de lista, se aplica el comportamiento `ListPropertyAssignBehavior`. En este caso:
Base {
// The new item is appended to the list even though you're assigning.
// The (default) property "d" now contains "inner" and "inner2".
d: [
Item { objectName: "inner2" }
]
// The list is replaced by the list given here.
// The (non-default) property "notDefault" now contains only "two".
notDefault: [
Item { objectName: "two" }
]
}Si no se especifica « ListPropertyAssignBehavior » o si se especifica « Append », el objeto «two» se añadirá a la propiedad « notDefault », lo que dará como resultado una lista que contenga tanto «one» como «two».
Si se especifica ` Replace `, el contenido de la propiedad predeterminada «d» también se sustituirá, lo que dará como resultado una lista que contenga únicamente «inner2».
Nota: La misma declaración también se puede aplicar a tipos definidos en C++, añadiendo las macros QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND, QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE y QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT a la declaración de la clase. Por ejemplo:
class MyType : public QObject
{
Q_OBJECT
QML_ELEMENT
QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE
Q_PROPERTY(QQmlListProperty<QObject> a READ a)
[...]
};ComponentBehavior
Es posible definir varios componentes en el mismo archivo QML. El ámbito raíz del archivo QML es un componente, y además puede haber elementos de tipo ` QQmlComponent` creados de forma explícita o implícita como propiedades, o componentes en línea. Estos componentes están anidados. Cada uno de los componentes internos se encuentra dentro de un componente externo específico. En la mayoría de los casos, se puede acceder a los ID definidos en un componente externo desde todos sus componentes internos anidados. Sin embargo, puedes crear elementos a partir de un componente en cualquier otro contexto, con ID diferentes disponibles. Al hacerlo, se rompe la suposición de que los ID externos están disponibles. Por lo tanto, el motor y las herramientas de QML no pueden saber, por lo general, de antemano a qué tipo —si es que hay alguno— se resolverán dichos ID en tiempo de ejecución.
Con el pragma `ComponentBehavior` se puede restringir que todos los componentes internos definidos en un archivo solo creen objetos dentro de su contexto original. Si un componente está vinculado a su contexto, se pueden utilizar con seguridad dentro del componente los identificadores de los componentes externos del mismo archivo. Las herramientas de QML asumirán entonces que los identificadores externos, con sus tipos específicos, están disponibles.
Para vincular los componentes a su contexto, especifica el argumento ` Bound `:
pragma ComponentBehavior: BoundEsto implica que, en caso de conflictos de nombres, los identificadores definidos fuera de un componente vinculado tienen prioridad sobre las propiedades locales de los objetos creados a partir del componente. De lo contrario, no sería realmente seguro utilizar los identificadores, ya que las versiones posteriores de un módulo podrían añadir más propiedades al componente. Si el componente no está vinculado, las propiedades locales anulan los identificadores definidos fuera del componente, pero no los definidos dentro del mismo.
El ejemplo siguiente muestra la propiedad `r` del objeto ` ListView ` con el identificador `color`, no la propiedad `r ` del color del rectángulo.
pragma ComponentBehavior: Bound
import QtQuick
ListView {
id: color
property int r: 12
model: 1
delegate: Rectangle {
Component.onCompleted: console.log(color.r)
}
}El valor por defecto de ` ComponentBehavior ` es ` Unbound`. También se puede especificar explícitamente. En una futura versión de Qt, el valor por defecto cambiará a ` Bound`.
Los componentes delegados vinculados a su contexto no reciben sus propios contextos privados al instanciarse. Esto significa que, en este caso, los datos del modelo solo se pueden pasar a través de propiedades obligatorias. Pasar datos del modelo a través de propiedades de contexto no funcionará. Esto afecta a los delegados de, por ejemplo, Instantiator, Repeater, ListView, TableView, GridView, TreeView y, en general, a cualquier elemento que utilice DelegateModel internamente.
Por ejemplo, lo siguiente no funcionará:
pragma ComponentBehavior: Bound
import QtQuick
ListView {
delegate: Rectangle {
color: model.myColor
}
}La propiedad ` delegate ` de ` ListView ` es un componente. Por lo tanto, aquí se crea implícitamente un ` Component ` alrededor de ` Rectangle `. Ese componente está vinculado a su contexto. No recibe la propiedad de contexto ` model ` proporcionada por ` ListView`. Para que funcione, tendrías que escribirlo de esta manera:
pragma ComponentBehavior: Bound
import QtQuick
ListView {
delegate: Rectangle {
required property color myColor
color: myColor
}
}Se pueden anidar componentes en un archivo QML. El pragma se aplica a todos los componentes del archivo, independientemente de su nivel de anidación.
FunctionSignatureBehavior
Con este pragma puedes cambiar la forma en que se gestionan las anotaciones de tipo en las funciones. Desde Qt 6.7, las anotaciones de tipo se aplican al llamar a funciones. Antes, solo el compilador de scripts QML aplicaba las anotaciones de tipo. El intérprete y el compilador JIT las ignoraban. La aplicación sistemática de las anotaciones de tipo supone un cambio de comportamiento con respecto a versiones anteriores, ya que antes se podían llamar a funciones con argumentos no coincidentes.
Al especificar « Ignored » como valor, el motor QML y el compilador de scripts QML ignoran cualquier anotación de tipo y, por lo tanto, se restablece el comportamiento del intérprete y del JIT anterior a la versión 6.7. Como resultado, se compila menos código a C++ por adelantado y hay que interpretar o compilar mediante JIT una mayor cantidad de código.
Al especificar « Enforced » como valor, se establece explícitamente el valor por defecto: las anotaciones de tipo siempre se aplican.
NativeMethodBehavior
La llamada a métodos de C++ con objetos ` this ` distintos de aquel del que se obtuvieron no funciona, por razones históricas. Se utiliza el objeto original como objeto ` this `. Puedes permitir que se utilice el objeto ` this ` dado configurando ` pragma NativeMethodBehavior: AcceptThisObject`. Al especificar ` RejectThisObject ` se mantiene el comportamiento histórico.
Se puede encontrar un ejemplo de esto en la sección sobre métodos de C++ y el objeto «this».
ValueTypeBehavior
Con este pragma se puede cambiar la forma en que se gestionan los tipos de valor y las secuencias.
Normalmente, los nombres en minúsculas no pueden ser nombres de tipos en el código JavaScript. Esto supone un problema, ya que los nombres de los tipos de valor están en minúsculas. Para solucionarlo, puedes especificar « Addressable » como valor para este pragma. Si se especifica « Addressable », un valor de JavaScript puede ser convertido explícitamente a un tipo de valor específico y con nombre. Esto se hace utilizando el operador « as », igual que se haría con los tipos de objeto. Además, también puedes comprobar si se trata de un tipo de valor utilizando el operador « instanceof »:
pragma ValueTypeBehavior: Addressable
import QtQml
QtObject {
property var a
property real b: (a as rect).x
property bool c: a instanceof rect
property var rect // inaccessible. "rect" is a type name.
}Dado que rect en el ejemplo anterior es ahora un nombre de tipo, anulará cualquier propiedad llamada rect.
La conversión explícita al tipo deseado facilita el uso de las herramientas. Permite que el compilador deQt Quick genere código eficiente donde, de otro modo, no podría hacerlo. Puedes utilizar qmllint para detectar estos casos.
También hay un valor de « Inaddressable » que puedes utilizar para especificar explícitamente el comportamiento por defecto.
Otro atributo del pragma « ValueTypeBehavior » es « Assertable », introducido en Qt 6.8. Debido a un error en Qt 6.6 y 6.7, el « a as rect » anterior no solo comprueba si « a » es un « rect », sino que también construye un « rect » si « a » es de un tipo compatible. Obviamente, esto no es lo que debería hacer una aserción de tipo. Especificar ` Assertable ` evita este comportamiento y restringe las aserciones de tipo para los tipos de valor, de modo que solo comprueben el tipo. Debes especificarlo siempre que vayas a utilizar tipos de valor con ` as`. En cualquier caso, si la aserción de tipo para un tipo de valor falla, el resultado es ` undefined`.
instanceof no presenta este problema, ya que solo comprueba la herencia, no todas las posibles coerciones de tipo.
Nota: No es recomendableutilizar ` as ` con los tipos ` int ` y ` double `, ya que, según las reglas de JavaScript, el resultado de cualquier cálculo es un número de coma flotante, incluso si coincide con el valor de su equivalente entero. Por el contrario, cualquier constante entera que se declare en JavaScript no es un `double` según las reglas de mapeo de tipos de QML. Además, ` int ` y ` double ` son palabras reservadas. Solo puedes acceder a estos tipos a través de espacios de nombres de tipos.
Los tipos de valor y las secuencias se tratan generalmente como referencias. Esto significa que, si se recupera una instancia de tipo de valor de una propiedad en una variable local y, a continuación, se modifica el valor local, la propiedad original también se modifica. Además, si se escribe la propiedad original de forma explícita, el valor local también se actualiza. Este comportamiento resulta bastante poco intuitivo en muchos casos, por lo que no debes confiar en él. Los valores Copy y Reference del pragma ValueTypeBehavior son opciones experimentales para modificar este comportamiento. No debes utilizarlas. Al especificar Copy, todos los tipos de valor se tratan como copias reales. Al especificar Reference, se establece explícitamente el comportamiento predeterminado.
En lugar de utilizar Copy, debes recargar explícitamente las referencias a tipos de valor y secuencias cada vez que puedan haberse visto afectadas por efectos secundarios. Los efectos secundarios pueden producirse cada vez que se llama a una función o se establece una propiedad de forma imperativa. qmllint ofrece orientación al respecto. Por ejemplo, en el siguiente código, la variable f se ve afectada por efectos secundarios tras escribir width. Esto se debe a que puede haber un enlace en un tipo derivado o en un elemento Binding que actualice font cuando se modifica width.
import QtQuick
Text {
function a() : real {
var f = font;
width = f.pixelSize;
return f.pointSize;
}
}Para solucionar esto, puedes evitar mantener f durante la operación de escritura en width:
import QtQuick
Text {
function a() : real {
var f = font;
width = f.pixelSize;
f = font;
return f.pointSize;
}
}Esto, a su vez, se puede acortar a:
import QtQuick
Text {
function a() : real {
width = font.pixelSize;
return font.pointSize;
}
}Podrías pensar que volver a recuperar la propiedad font es costoso, pero, en realidad, el motor de QML actualiza automáticamente las referencias de tipo valor cada vez que se lee de ellas. Por lo tanto, esto no es más costoso que la primera versión, sino una forma más clara de expresar las mismas operaciones.
Traductor
Con este pragma puedes establecer el contexto para las traducciones del archivo.
pragma Translator: myTranslationContextpragma Translator: "myTranslationContext"Para obtener más información sobre la internacionalización con QML, consulta «Escritura de código fuente para la traducción en QML».
Importaciones
Un documento debe importar los módulos o espacios de nombres de tipos necesarios para que el motor pueda cargar los tipos de objetos QML a los que se hace referencia en el documento. Por defecto, un documento puede acceder a cualquier tipo de objeto QML que se haya definido mediante archivos ` .qml ` en el mismo directorio; si un documento necesita hacer referencia a otros tipos de objetos, debe importar el espacio de nombres de tipos en el que se hayan registrado dichos tipos.
QML no dispone de un preprocesador que modifique el documento antes de su presentación al compilador ( QML engine), a diferencia de C o C++. Las instrucciones import no copian ni anteponen el código en el documento, sino que indican al motor de QML cómo resolver las referencias de tipos que se encuentran en el documento. Cualquier referencia de tipo presente en un documento QML —como Rectangle y ListView —, incluidas las realizadas dentro de un bloque de JavaScript o en enlaces de propiedades, se resuelve basándose exclusivamente en las sentencias de importación. Debe haber al menos una sentencia « import », como import QtQuick 2.0.
Consulta la documentación «Sintaxis de QML: declaraciones de importación » para obtener información detallada sobre las importaciones en QML.
La declaración del objeto raíz
Un documento QML describe una jerarquía de objetos que pueden instanciarse. Cada definición de objeto tiene una estructura determinada: cuenta con un tipo, puede tener un identificador y un nombre de objeto, puede tener propiedades, métodos, señales y controladores de señales.
Un archivo QML solo debe contener una única definición de objeto raíz. Lo siguiente no es válido y generará un error:
// MyQmlFile.qml
import QtQuick 2.0
Rectangle { width: 200; height: 200; color: "red" }
Rectangle { width: 200; height: 200; color: "blue" } // invalid!Esto se debe a que un archivo .qml define automáticamente un tipo QML, que encapsula una única definición de objeto QML. Esto se explica con más detalle en la sección «Documentos como definiciones de tipos de objetos QML».
Véase también Anotaciones y aserciones de tipo.
© 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.