Módulos identificados

Los módulos identificados son módulos instalados e identificables para el motor QML mediante un URI en forma de cadena de identificador punteada, que debe especificar el módulo en su archivo qmldir. Esto permite importar dichos módulos con un identificador único que sigue siendo el mismo independientemente de la ubicación del módulo en el sistema de archivos local.

Al importar un módulo identificado, se utiliza un identificador sin comillas, con un número de versión opcional:

import QtQuick
import com.mycompany.qml.mymodule 1.0

Los módulos identificados deben instalarse en la ruta de importación para que el motor QML los encuentre.

Sintácticamente, cada segmento separado por puntos del URI debe ser un nombre de identificador ECMAScript bien formado. Esto significa, por ejemplo, que los segmentos no deben empezar por un número ni contener caracteres - (menos). Como el URI se traducirá a nombres de directorio, debe restringirlo a caracteres alfanuméricos del alfabeto latino, guiones bajos y puntos.

Módulos identificados instalados localmente

Un directorio de archivos QML y/o C++ puede compartirse como módulo identificado si contiene un archivo qmldir con los metadatos del módulo y se instala en la ruta de importación de QML. Cualquier archivo QML del sistema de archivos local puede importar este directorio como módulo utilizando una sentencia import que haga referencia al URI del módulo, lo que permite al archivo utilizar los tipos de objeto QML y los recursos JavaScript definidos por el módulo.

El archivo qmldir del módulo debe residir en una estructura de directorios dentro de la ruta de importación que refleje la cadena de identificadores con puntos del URI, donde cada punto (".") del identificador refleja un subnivel en el árbol de directorios. Por ejemplo, el archivo qmldir del módulo com.mycompany.mymodule debe estar ubicado en la sub-ruta com/mycompany/mymodule/qmldir en algún lugar de la ruta de importación.

Es posible almacenar diferentes versiones de un módulo en subdirectorios propios. Por ejemplo, la versión 2.1 de un módulo podría ubicarse en com/mycompany/mymodule.2/qmldir o com/mycompany/mymodule.2.1/qmldir. El motor cargará automáticamente el módulo que mejor se adapte.

Otra posibilidad es definir las versiones de los distintos tipos en el propio archivo qmldir, aunque esto puede dificultar la actualización de un módulo de este tipo (ya que debe realizarse una fusión de archivos en qmldir como parte del procedimiento de actualización).

Un ejemplo

Considere la siguiente estructura de directorios del proyecto QML. Bajo el directorio de nivel superior myapp, hay un conjunto de componentes comunes de interfaz de usuario en un subdirectorio denominado mycomponents, y el código principal de la aplicación en un subdirectorio denominado main, de la siguiente manera:

myapp
    |- mycomponents
        |- CheckBox.qml
        |- DialogBox.qml
        |- Slider.qml
    |- main
        |- application.qml

Para que el directorio mycomponents esté disponible como un módulo identificado, el directorio debe incluir un archivo qmldir que defina el identificador del módulo y describa los tipos de objetos disponibles para el módulo. Por ejemplo, para que los tipos CheckBox, DialogBox y Slider estén disponibles para la versión 1.0 del módulo, el archivo qmldir contendría lo siguiente:

module myapp.mycomponents
CheckBox 1.0 CheckBox.qml
DialogBox 1.0 DialogBox.qml
Slider 1.0 Slider.qml

Además, la ubicación del archivo qmldir en la ruta de importación debe coincidir con la cadena de identificadores punteados del módulo. Así, digamos que el directorio de nivel superior myapp se encuentra en C:\qml\projects, y digamos que el módulo debe identificarse como "myapp.mycomponents". En este caso:

• La ruta C:\qml\projects debe añadirse a la ruta de importación.
• El archivo qmldir debe ubicarse en C:\qml\projects\myapp\mycomponents\qmldir

Una vez hecho esto, un archivo QML ubicado en cualquier lugar del sistema de archivos local puede importar el módulo haciendo referencia a su URI y a la versión adecuada:

import myapp.mycomponents 1.0

DialogBox {
    CheckBox {
        // ...
    }
    Slider {
        // ...
    }
}

Módulos identificados instalados de forma remota

Los módulos identificados también son accesibles como recursos de red. En el ejemplo anterior, si el directorio C:\qml\projects estuviera alojado como http://www.some-server.com/qml/projects y se añadiera esta URL a la ruta de importación de QML, el módulo podría importarse exactamente del mismo modo.

Tenga en cuenta que cuando un archivo importa un módulo a través de una red, sólo puede acceder a los recursos QML y JavaScript proporcionados por el módulo; no puede acceder a ningún tipo definido por los plugins C++ del módulo.

Semántica de los módulos identificados

El motor QML ofrece las siguientes garantías a los módulos identificados:

• otros módulos no pueden modificar o anular tipos en el espacio de nombres del módulo
• otros módulos no pueden registrar nuevos tipos en el espacio de nombres del módulo
• el uso de nombres de tipo por parte de los clientes se resolverá de forma determinista a una definición de tipo determinada en función del versionado especificado y del orden de importación.

Esto garantiza que los clientes que utilicen el módulo puedan estar seguros de que los tipos de objeto definidos en el módulo se comportarán tal y como el autor del módulo ha documentado.

Un módulo identificado tiene varias restricciones

• un módulo identificado debe estar instalado en la ruta de importación de QML
• el identificador de módulo especificado en la directiva de identificador de módulo debe coincidir con la ruta de instalación del módulo (relativa a la ruta de importación de QML, donde los separadores de directorio se sustituyen por caracteres de punto)
• el módulo debe registrar sus tipos en el espacio de nombres de tipo del identificador de módulo
• el módulo no puede registrar tipos en el espacio de nombres de ningún otro módulo

Por ejemplo, si un módulo identificado se instala en $QML_IMPORT_PATH/ExampleModule, la directiva del identificador del módulo debe ser:

module ExampleModule

Si el módulo estricto se instala en $QML_IMPORT_PATH/com/example/CustomUi, la directiva del identificador del módulo debe ser:

module com.example.CustomUi

Los clientes podrán importar el módulo anterior con la siguiente sentencia import:

import com.example.CustomUi