En esta página

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:

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 ExampleModule

Declaració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.qml

Esto 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.js

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

  • optional indica 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 biblioteca MyAppTypes generaría libMyAppTypes.so en Linux y MyAppTypes.dll en 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 qmldir hasta 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 MyPluginLibrary

Declaració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.qmltypes

Sin 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.0

Esta 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.0

Los 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

designersupported

Establece 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.qml

un 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.js

El 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.qmltypes

a /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.