Archivos qmldir de definición de módulos
Existen dos tipos distintos de archivos « qmldir »:
- Archivos de listado del directorio de documentos QML
- Archivos de definición de módulos QML
Esta documentación solo aborda el segundo tipo de archivo « qmldir », que enumera los tipos QML, los archivos JavaScript y los complementos disponibles en un módulo. Para obtener más información sobre el primer tipo de archivo « qmldir », consulta los archivos «qmldir» de listado de directorios.
Contenido de un archivo qmldir de definición de módulo
Nota: Utilice la API de CMake para generar archivos qmldir. Escriba su archivo « qmldir » manualmente solo si necesita utilizar « qmake ».
Un archivo « qmldir » es un archivo de texto sin formato que contiene los siguientes comandos:
- Declaración del identificador del módulo
- Declaración del tipo de objeto
- Declaración de tipo de objeto interno
- Declaración de recursos de JavaScript
- Declaración de complementos
- Declaración del nombre de clase del complemento
- Declaración de archivo de descripción de tipos
- Declaración de dependencias de módulos
- Declaración de importación de módulos
- Declaración de compatibilidad con el diseñador
- Declaración de ruta preferida
Nota: Cada comando de un archivo « qmldir » debe estar en una línea separada.
Además de los comandos, también se pueden añadir comentarios, que son líneas que comienzan por #.
Declaración del identificador del módulo
module <ModuleIdentifier>Declara el identificador del módulo. El <ModuleIdentifier> es el identificador (en notación URI con puntos) del módulo, que debe coincidir con la ruta de instalación del módulo.
La directiva del identificador del módulo debe ser la primera línea del archivo. Solo puede haber una directiva del identificador del módulo en el archivo qmldir.
Ejemplo:
module ExampleModuleDeclaración de tipo de objeto
[singleton] <TypeName> <InitialVersion> <File>Declara un tipo de objeto QML que el módulo pondrá a disposición.
[singleton]Opcional. Se utiliza para declarar un tipo singleton.<TypeName>es el tipo que se pone a disposición<InitialVersion>es la versión del módulo para la que se va a poner a disposición el tipo<File>es el nombre (relativo) del archivo QML que define el tipo
Puede haber cero o más declaraciones de tipos de objeto en el archivo qmldir. Sin embargo, cada tipo de objeto debe tener un nombre de tipo único dentro de cualquier versión concreta del módulo.
Nota: Para declarar un tipo « singleton », el archivo QML que define el tipo debe incluir la instrucción « pragma Singleton ».
Ejemplo:
//Style.qml with custom singleton type definition
pragma Singleton
import QtQuick 2.0
QtObject {
property int textSize: 20
property color textColor: "green"
}
// qmldir declaring the singleton type
module CustomStyles
singleton Style 1.0 Style.qml
// singleton type in use
import QtQuick 2.0
import CustomStyles 1.0
Text {
font.pixelSize: Style.textSize
color: Style.textColor
text: "Hello World"
}Declaración de tipo de objeto interno
internal <TypeName> <File>Declara un tipo de objeto que se encuentra en el módulo, pero que no debe ponerse a disposición de los usuarios del mismo.
En el archivo qmldir pueden existir cero o más declaraciones de tipos de objeto internos.
Ejemplo:
internal MyPrivateType MyPrivateType.qmlEsto es necesario si el módulo se importa de forma remota (véase «Módulos identificados instalados de forma remota»), ya que si un tipo exportado depende de un tipo no exportado dentro del módulo, el motor también debe cargar el tipo no exportado.
Declaración de recursos JavaScript
<ResourceIdentifier> <InitialVersion> <File>Declara un archivo JavaScript que el módulo pondrá a disposición. El recurso estará disponible a través del identificador especificado con el número de versión indicado.
Puede haber cero o más declaraciones de recursos JavaScript en el archivo « qmldir ». Sin embargo, cada recurso JavaScript debe tener un identificador único dentro de cualquier versión concreta del módulo.
Ejemplo:
MyScript 1.0 MyScript.jsConsulta la documentación sobre cómo definir recursos de JavaScript e «Importación de recursos de JavaScript en QML» para obtener más información.
Declaración de complementos
[optional] plugin <Name> [<Path>]Declara un complemento que el módulo pondrá a disposición.
optionalindica que el propio complemento no contiene ningún código relevante y solo sirve para cargar una biblioteca a la que está vinculado. Si se especifica, y si ya hay tipos disponibles para el módulo —lo que indica que la biblioteca se ha cargado por otros medios—, QML no cargará el complemento.<Name>es el nombre de la biblioteca del complemento. Normalmente no coincide con el nombre del archivo binario del complemento, que depende de la plataforma. Por ejemplo, la bibliotecaMyAppTypesgeneraríalibMyAppTypes.soen Linux yMyAppTypes.dllen Windows.<Path>(opcional) especifica:- una ruta absoluta al directorio que contiene el archivo del complemento, o
- una ruta relativa desde el directorio que contiene el archivo
qmldirhasta el directorio que contiene el archivo del complemento.
Por defecto, el motor busca la biblioteca del complemento en el directorio que contiene el archivo « qmldir ». (La ruta de búsqueda del complemento se puede consultar con ` QQmlEngine::pluginPathList()` y modificar mediante ` QQmlEngine::addPluginPath()`.)
En el archivo ` qmldir ` puede haber cero o más declaraciones de complementos en C++. Sin embargo, dado que la carga de complementos es una operación relativamente costosa, se recomienda a los clientes que especifiquen, como máximo, un único complemento.
Ejemplo:
plugin MyPluginLibraryDeclaración del nombre de clase del complemento
classname <C++ plugin class>Proporciona el nombre de la clase del complemento de C++ utilizado por el módulo.
Esta información es obligatoria para todos los módulos QML que dependen de un complemento de C++ para obtener funcionalidad adicional. Las aplicaciones Qt Quick compiladas con enlace estático no pueden resolver las importaciones de módulos sin esta información.
Declaración del archivo de descripción de tipos
typeinfo <File>Declara un archivo de descripción de tipos para el módulo que pueden leer herramientas de QML como Qt Creator para acceder a la información sobre los tipos definidos por los complementos del módulo. <File> es el nombre de archivo (relativo) de un archivo .qmltypes.
Ejemplo:
typeinfo mymodule.qmltypesSin dicho archivo, es posible que las herramientas de QML no puedan ofrecer funciones como la finalización automática de código para los tipos definidos en tus complementos.
Declaración de dependencias del módulo
depends <ModuleIdentifier> <InitialVersion>Declara que este módulo depende de otro.
Ejemplo:
depends MyOtherModule 1.0Esta declaración solo es necesaria en los casos en que la dependencia está oculta: por ejemplo, cuando se utiliza el código C++ de un módulo para cargar QML (quizá de forma condicional), que a su vez depende de otros módulos. En tales casos, la declaración « depends » es necesaria para incluir los demás módulos en los paquetes de la aplicación.
Declaración de importación de módulos
import <ModuleIdentifier> [<Version>]Declara que este módulo importa otro.
Ejemplo:
import MyOtherModule 1.0Los tipos del otro módulo están disponibles en el mismo espacio de nombres de tipos en el que se importa este módulo. Si se omite la versión, se importa la última versión disponible del otro módulo. Si se especifica auto como versión, se importa la misma versión que la de este módulo especificada en la instrucción QML import.
Declaración de compatibilidad con el diseñador
designersupportedEstablece esta propiedad si el complemento es compatible con el Diseñador de Qt Quick. Por defecto, el complemento no será compatible.
Un complemento compatible con el Diseñador de Qt Quick debe haberse probado adecuadamente. Esto significa que el complemento no se bloquea al ejecutarse dentro de qml2puppet, que es el programa que utiliza el Diseñador de Qt Quick para ejecutar QML. En general, el complemento debería funcionar bien en el Diseñador de Qt Quick y no provocar ningún problema grave, como consumir una cantidad excesiva de memoria, ralentizar considerablemente el qml2puppet o cualquier otra cosa que haga que el complemento resulte prácticamente inutilizable en el Diseñador de Qt Quick.
Los elementos de un complemento no compatible no se visualizan en el Diseñador de Qt Quick, pero siguen estando disponibles como cuadros vacíos y sus propiedades se pueden editar.
Declaración de ruta preferida
prefer <Path>Esta propiedad indica al motor QML que cargue cualquier otro archivo de este módulo desde <path>, en lugar de desde el directorio actual. Esto se puede utilizar para cargar archivos compilados con qmlcachegen.
Por ejemplo, puedes añadir los archivos QML de un módulo como recursos a una ruta de recursos :/my/path/MyModule/. A continuación, añade prefer :/my/path/MyModule al archivo qmldir para utilizar los archivos del sistema de recursos, en lugar de los del sistema de archivos. Si después utilizas qmlcachegen para ellos, los archivos precompilados estarán disponibles para cualquier cliente del módulo.
Semántica de las versiones
Todos los tipos QML que se exportan para una versión principal concreta están disponibles con la última versión de esa misma versión principal. Por ejemplo, si un módulo proporciona un tipo MyButton en la versión 1.0 y un tipo MyWindow en la versión 1.1, los clientes que importen la versión 1.1 del módulo podrán utilizar los tipos MyButton y MyWindow. Sin embargo, lo contrario no es cierto: un tipo exportado para una versión menor concreta no puede utilizarse al importar una versión menor anterior o más antigua. En el ejemplo mencionado anteriormente, si el cliente hubiera importado la versión 1.0 del módulo, solo podría utilizar el tipo MyButton, pero no el tipo MyWindow.
Un módulo puede ofrecer varias versiones principales, pero los clientes solo tienen acceso a una versión principal a la vez. Por ejemplo, al importar MyExampleModule 2.0 se obtiene acceso únicamente a esa versión principal y no a la versión principal anterior. Aunque es posible organizar los artefactos que pertenecen a diferentes versiones principales en un único directorio y un archivo qmldir, se recomienda utilizar directorios diferentes para cada versión principal. Si optas por el primer enfoque (un directorio y un archivo qmldir ), intenta utilizar el sufijo de la versión en los nombres de los archivos. Por ejemplo, los artefactos que pertenecen a MyExampleModule 2.0 pueden utilizar el sufijo .2 en su nombre de archivo.
No se puede importar una versión si no se han exportado explícitamente tipos para esa versión. Si un módulo proporciona un tipo MyButton en la versión 1.0 y un tipo MyWindow en la versión 1.1, no se puede importar la versión 1.2 ni la versión 2.0 de ese módulo.
Un tipo puede definirse en diferentes archivos en distintas versiones menores. En este caso, cuando los clientes lo importan, se utiliza la versión que más se aproxime. Por ejemplo, si un módulo hubiera especificado los siguientes tipos a través de su archivo qmldir:
module ExampleModule
MyButton 1.0 MyButton.qml
MyButton 1.1 MyButton11.qml
MyButton 1.3 MyButton13.qml
MyRectangle 1.2 MyRectangle12.qmlun cliente que importe la versión 1.2 de ExampleModule puede utilizar la definición de tipo MyButton proporcionada por MyButton11.qml, ya que es la versión más reciente de ese tipo, y la definición de tipo MyRectangle proporcionada por MyRectangle12.qml.
El sistema de versiones garantiza que un archivo QML determinado funcione independientemente de la versión del software instalado, ya que una importación con versión solo importa los tipos correspondientes a esa versión, dejando disponibles otros identificadores, incluso si la versión realmente instalada pudiera proporcionar dichos identificadores.
Ejemplo de un archivo qmldir
A continuación se muestra un ejemplo de un archivo qmldir:
module ExampleModule
CustomButton 2.0 CustomButton20.qml
CustomButton 2.1 CustomButton21.qml
plugin examplemodule
MathFunctions 2.0 mathfuncs.jsEl archivo « qmldir » anterior define un módulo denominado «ExampleModule». Define el tipo de objeto QML « CustomButton » en las versiones 2.0 y 2.1 del módulo, con diferentes implementaciones para cada versión. Especifica un complemento que el motor debe cargar cuando los clientes importan el módulo, y dicho complemento puede registrar varios tipos definidos en C++ en el sistema de tipos de QML. En sistemas tipo Unix, el motor QML intenta cargar libexamplemodule.so como QQmlExtensionPlugin, y en Windows carga examplemodule.dll como QQmlExtensionPlugin. Por último, el archivo qmldir especifica un recurso JavaScript, que solo está disponible si se importa la versión 2.0 o una versión posterior (dentro de la misma versión principal) del módulo.
Si el módulo se instala en la ruta de importación de QML, los clientes podrían importarlo y utilizarlo de la siguiente manera:
import QtQuick 2.0
import ExampleModule 2.1
Rectangle {
width: 400
height: 400
color: "lightsteelblue"
CustomButton {
color: "gray"
text: "Click Me!"
onClicked: MathFunctions.generateRandom() > 10 ? color = "red" : color = "gray";
}
}El tipo ` CustomButton ` utilizado anteriormente procedería de la definición especificada en el archivo ` CustomButton21.qml `, y el recurso JavaScript identificado por el identificador ` MathFunctions ` se definiría en el archivo ` mathfuncs.js `.
Archivos de descripción de tipos
Los módulos QML pueden hacer referencia a uno o varios archivos de información de tipos en su archivo qmldir. Estos suelen tener la extensión .qmltypes y son leídos por herramientas externas para obtener información sobre los tipos definidos en C++ y que, por lo general, se importan a través de complementos.
Por lo tanto, los archivos qmltypes no tienen ningún efecto sobre la funcionalidad de un módulo QML. Su única finalidad es permitir que herramientas como Qt Creator ofrezcan autocompletado de código, comprobación de errores y otras funcionalidades a los usuarios de tu módulo.
Cualquier módulo que defina tipos QML en C++ también debería incluir un archivo de descripción de tipos.
La mejor forma de crear un archivo qmltypes para tu módulo es generarlo utilizando el sistema de compilación y las macros QML_ELEMENT. Si sigues la documentación al respecto, no es necesario realizar ninguna acción adicional. qmltyperegistrar generará automáticamente los archivos .qmltypes.
Ejemplo: si tu módulo se encuentra en /tmp/imports/My/Module, debería generarse un archivo llamado plugins.qmltypes junto con el binario del complemento.
Añade la línea
typeinfo plugins.qmltypesa /tmp/imports/My/Module/qmldir para registrarlo.
© 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.