En esta página

Módulos identificados

Los módulos identificados son módulos que están instalados y que el motor QML puede identificar mediante un URI en forma de cadena de identificador con puntos, que debe especificar el módulo en su archivo « qmldir ». Esto permite importar dichos módulos con un identificador único que permanece igual independientemente de dónde se encuentre el 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 pueda encontrarlos.

Sintácticamente, cada segmento del URI separado por puntos debe ser un nombre de identificador ECMAScript bien formado. Esto significa, por ejemplo, que los segmentos no deben comenzar con un número ni contener caracteres «-» (menos). Dado que el URI se traducirá a nombres de directorios, debes limitarlo 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 está instalado en la ruta de importación de QML. Cualquier archivo QML del sistema de archivos local puede importar este directorio como módulo mediante una instrucción «import» que haga referencia al URI del módulo, lo que permite al archivo utilizar los tipos de objetos 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 identificador con puntos de la URI, donde cada punto («.») del identificador representa un subnivel en el árbol de directorios. Por ejemplo, el archivo ` qmldir ` del módulo ` com.mycompany.mymodule ` debe estar ubicado en la subruta ` com/mycompany/mymodule/qmldir ` en algún lugar de la ruta de importación.

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

Como alternativa, el control de versiones para diferentes tipos puede definirse dentro del propio archivo qmldir; sin embargo, esto puede dificultar la actualización de dicho módulo (ya que, como parte del procedimiento de actualización, debe realizarse una fusión de archivos qmldir ).

Un ejemplo

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

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

Para que el directorio mycomponents esté disponible como módulo identificado, debe incluir un archivo qmldir que defina el identificador del módulo y describa los tipos de objetos que este pone a disposición. 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 identificación con puntos del módulo. Así pues, supongamos que el directorio de nivel superior myapp se encuentra en C:\qml\projects y 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, cualquier archivo QML ubicado en cualquier lugar del sistema de archivos local podrá 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

También se puede acceder a los módulos identificados como un recurso de red. En el ejemplo anterior, si el directorio C:\qml\projects estuviera alojado en http://www.some-server.com/qml/projects y esta URL se añadiera a la ruta de importación de QML, el módulo podría importarse exactamente de la misma manera.

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

Semántica de los módulos identificados

El motor QML ofrece las siguientes garantías para un módulo identificado:

  • los demás módulos no pueden modificar ni sobrescribir los tipos del espacio de nombres del módulo
  • los demás módulos no pueden registrar nuevos tipos en el espacio de nombres del módulo
  • el uso de los nombres de tipos por parte de los clientes se resolverá de forma determinista en una definición de tipo determinada, en función de la versión especificada y del orden de importación

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

Un módulo identificado está sujeto a varias restricciones:

  • un módulo identificado debe estar instalado en la ruta de importación de QML
  • el identificador del módulo especificado en la directiva «module identifier» debe coincidir con la ruta de instalación del módulo (en relación con la ruta de importación de QML, donde los separadores de directorios se sustituyen por puntos)
  • el módulo debe registrar sus tipos en el espacio de nombres de tipos del identificador del 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 de identificador de módulo debe ser:

module ExampleModule

Si el módulo «strict» está instalado en $QML_IMPORT_PATH/com/example/CustomUi, la directiva de identificador de módulo debe ser:

module com.example.CustomUi

De este modo, los clientes podrán importar el módulo anterior con la siguiente instrucción de importación:

import com.example.CustomUi

Véase también Modernización de módulos QML y Portar módulos QML a CMake.

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