Documentos QML

Un documento QML es una cadena que se ajusta a la sintaxis de documentos QML. Un documento define un tipo de objeto QML. Un documento se carga generalmente desde un archivo ".qml" almacenado local o remotamente, pero puede construirse manualmente en código. Una instancia del tipo de objeto definido por un documento puede crearse utilizando un Component en código QML, o un QQmlComponent en C++. Alternativamente, si el tipo de objeto se expone explícitamente al sistema de tipos QML con un nombre de tipo concreto, el tipo puede utilizarse directamente en las declaraciones de objetos de otros documentos.

La capacidad de definir tipos de objeto QML reutilizables en documentos es un importante habilitador para permitir a los clientes escribir código modular, altamente legible y mantenible.

Desde Qt 5.4, un documento también puede tener la extensión de archivo ".ui.qml". El motor QML trata estos archivos como archivos .qml estándar e ignora la parte .ui de la extensión. Qt Design Studio trata estos archivos como archivos de interfaz de usuario. Los archivos sólo pueden contener un subconjunto de las características del lenguaje QML.

Estructura de un documento QML

Un documento QML consta de dos secciones: la sección de importaciones y la sección de declaración de objetos. La sección de importaciones de un documento contiene declaraciones de importación que definen qué tipos de objetos QML y recursos JavaScript puede utilizar el documento. La sección de declaración de objetos define el árbol de objetos que se creará al instanciar el tipo de objeto definido por el documento.

A continuación se muestra un ejemplo de documento sencillo:

import QtQuick 2.0

Rectangle {
    width: 300
    height: 200
    color: "blue"
}

Consulte la Estructura de un documento QML para obtener más información sobre el tema.

Sintaxis del lenguaje QML

La sección de declaración de objetos del documento debe especificar una jerarquía de objetos válida con la sintaxis QML adecuada. Una declaración de objeto puede incluir la especificación de atributos de objeto personalizados. Los atributos de método de objeto pueden especificarse como funciones JavaScript, y a los atributos de propiedad de objeto se les pueden asignar expresiones de vinculación de propiedades.

Consulte la documentación sobre la sintaxis de QML para obtener más información sobre la sintaxis válida, y consulte la documentación sobre la integración de QML y JavaScript para obtener información detallada sobre ese tema.

Definición de tipos de objeto mediante documentos QML

Como se ha descrito brevemente en la sección anterior, un documento define implícitamente un tipo de objeto QML. Uno de los principios básicos de QML es la posibilidad de definir y reutilizar tipos de objeto. Esto mejora la capacidad de mantenimiento del código QML, aumenta la legibilidad de las declaraciones de jerarquía de objetos y promueve la separación entre la definición de la interfaz de usuario y la implementación lógica.

En el siguiente ejemplo, el desarrollador del cliente define un tipo Button con un documento en un archivo:

// Button.qml
import QtQuick

Rectangle {
    width: 100; height: 100
    color: "red"

    MouseArea {
        anchors.fill: parent
        onClicked: console.log("Button clicked!")
    }
}

A continuación, el tipo Button puede utilizarse en una aplicación:

// application.qml
import QtQuick

Column {
    Button { width: 50; height: 50 }
    Button { x: 50; width: 100; height: 50; color: "blue" }
    Button { width: 50; height: 50; radius: 8 }
}

Consulte la documentación sobre la definición de tipos de objeto en documentos para obtener información detallada sobre el tema.

Carga de recursos y transparencia de la red

Es importante señalar que QML es transparente para la red. Las aplicaciones pueden importar documentos de rutas remotas con la misma facilidad que documentos de rutas locales. De hecho, a cualquier propiedad de url se le puede asignar una URL remota o local, y el motor QML gestionará cualquier comunicación de red implicada.

Consulte la documentación Transparencia de red para obtener más información sobre la transparencia de red en las importaciones.

Ámbito y resolución de nombres

Las expresiones de los documentos suelen implicar objetos o propiedades de objetos, y dado que pueden definirse varios objetos y que distintos objetos pueden tener propiedades con el mismo nombre, QML debe definir cierta semántica de resolución de símbolos predefinida. Consulte la página sobre ámbito y resolución de símbolos para obtener información detallada sobre el tema.