Importación de directorios de documentos QML
Se puede importar un directorio local de archivos QML sin necesidad de ninguna configuración adicional. También se puede importar un directorio remoto de archivos QML, pero para ello es necesario que exista un archivo de listado de directorios qmldir. Un directorio local puede contener opcionalmente un archivo de listado de directorios qmldir para definir los nombres de los tipos que deben proporcionarse a los clientes que importan el directorio, así como para especificar los recursos de JavaScript que deben ponerse a disposición de los importadores.
Qt da por hecho que todos los archivos del directorio importado proceden de una fuente de confianza.
Importaciones de directorios locales
Cualquier archivo QML del sistema de archivos local puede importar un directorio local mediante una instrucción `import` que haga referencia a la ruta absoluta o relativa del directorio en el sistema de archivos, lo que permite al archivo utilizar los tipos de objeto definidos en dicho directorio.
El QML Runtime lee un archivo opcional de listado de directorios ` qmldir ` del directorio importado para detectar los tipos disponibles definidos en QML y C++. El archivo ` qmldir ` especifica los nombres de los tipos definidos en QML y las rutas de los complementos que contienen tipos definidos en C++.
Los archivos QML estarán disponibles con los nombres de tipo especificados en el archivo qmldir, si existe; de lo contrario, estarán disponibles con nombres de tipo derivados de los nombres de archivo de los documentos QML. Solo los nombres de archivo que empiecen por una letra mayúscula y terminen en «.qml» se expondrán como tipos si no se especifica ningún archivo qmldir en el directorio.
El QML Runtime carga todos los complementos enumerados en el archivo qmldir para localizar todos los tipos expuestos desde C++.
Las importaciones de directorios tienen menor prioridad que las importaciones de módulos. Si se define el mismo nombre en un módulo y en un directorio, ambos importados al mismo espacio de nombres, solo estará disponible el tipo del módulo.
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.qmlEl archivo main/application.qml puede importar el directorio mycomponents utilizando la ruta relativa a dicho directorio, lo que le permite utilizar los tipos de objetos QML definidos en ese directorio:
El directorio puede importarse a un espacio de nombres local calificado; en tal caso, el uso de cualquier tipo proporcionado en el directorio debe calificarse:
import "../mycomponents" as MyComponents
MyComponents.DialogBox {
// ...
}La posibilidad de importar un directorio local resulta útil en casos como los conjuntos de componentes dentro de la aplicación y la creación de prototipos de aplicaciones, aunque cualquier código que importe dichos módulos debe actualizar sus sentencias import correspondientes si el directorio del módulo se traslada a otra ubicación. Esto puede evitarse si se utilizan módulos QML en su lugar, ya que un módulo instalado se importa con una cadena identificadora única en lugar de una ruta del sistema de archivos.
La importación implícita
El directorio en el que se encuentra un documento QML se importa automáticamente. No es necesario importar explícitamente ` "." ` ni nada similar.
Nota: Debes asegurarte de que el archivo `qmldir` que especifica el módulo al que pertenece un documento QML se encuentre en el mismo directorio que el propio documento QML. De lo contrario, la importación implícita será diferente del módulo al que pertenece el documento. Entonces, por ejemplo, otro documento QML podría ser un singleton en el contexto del módulo, pero no en el contexto de la importación implícita. Esto suele ser una fuente frecuente de errores.
Directorios ubicados de forma remota
Un directorio de archivos QML también se puede importar desde una ubicación remota si dicho directorio contiene un archivo « qmldir » que enumera su contenido.
Nota: Esto también se aplica a la importación implícita del directorio en el que reside un documento QML. Si tus documentos QML se cargan desde una ubicación remota, debes añadir archivos `qmldir` aunque no contengan ninguna instrucción explícita de importación de directorios. De lo contrario, tus documentos QML no se verán entre sí.
Por ejemplo, si el directorio myapp del ejemplo anterior estuviera alojado en «http://www.my-example-server.com», y el directorio mycomponents contuviera un archivo qmldir definido de la siguiente manera:
CheckBox CheckBox.qml
DialogBox DialogBox.qml
Slider Slider.qmlEntonces, el directorio se podría importar utilizando la URL del directorio remoto mycomponents:
import "http://www.my-example-server.com/myapp/mycomponents"
DialogBox {
CheckBox {
// ...
}
Slider {
// ...
}
}Ten en cuenta que, cuando un archivo importa un directorio a través de una red, solo puede acceder a los archivos QML y JavaScript especificados en el archivo qmldir ubicado en dicho directorio.
Advertencia: Al importar directorios desde un servidor remoto, los desarrolladores deben tener siempre cuidado de cargar únicamente directorios procedentes de fuentes de confianza para evitar la carga de código malicioso.
Archivos qmldir de listado de directorios
Un archivo « qmldir » de listado de directorios es claramente diferente de un archivo «qmldir» de definición de módulos. Un archivo « qmldir » de listado de directorios permite compartir de forma rápida y sencilla un grupo de documentos QML, pero no define un espacio de nombres de tipos en el que se registren los tipos de objetos QML definidos por los documentos, ni admite el control de versiones de dichos tipos de objetos QML.
La sintaxis de un archivo de listado de directorios qmldir es la siguiente:
| Comando | Sintaxis | Descripción |
|---|---|---|
| Declaración de tipo de objeto | <NombreDelTipo> <NombreDelArchivo> | Una declaración de tipo de objeto permite que un documento QML se exponga con el ` <TypeName>` especificado.Ejemplo: |
| Declaración de tipo de objeto interno | internal <TypeName> <FileName> | Una declaración de tipo de objeto interno permite que un documento QML se registre como un tipo que solo estará disponible para los demás documentos QML contenidos en el directorio import. El tipo interno no estará disponible para los clientes que importen el directorio. Ejemplo: |
| Declaración de recursos JavaScript | <Identificador> <NombreDeArchivo> | Una declaración de recurso de JavaScript permite que un archivo de JavaScript se exponga a través del identificador indicado. Ejemplo: |
Un directorio del sistema de archivos local puede incluir, de forma opcional, un archivo ` qmldir `. Esto permite al motor exponer únicamente determinados tipos QML a los clientes que importen el directorio. Además, los recursos JavaScript del directorio no se exponen a los clientes a menos que se declaren en un archivo ` qmldir `.
© 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.