Módulos QML
Un módulo QML proporciona tipos versionados y recursos JavaScript en un espacio de nombres de tipos que pueden utilizar los clientes que importen el módulo. Los tipos que proporciona un módulo pueden definirse en C++ dentro de un complemento o en documentos QML. Los módulos utilizan el sistema de versionado de QML, lo que permite que se actualicen de forma independiente.
La definición de un módulo QML permite:
- Compartir tipos QML comunes dentro de un proyecto; por ejemplo, un grupo de componentes de interfaz de usuario que utilizan diferentes ventanas
- La distribución de bibliotecas basadas en QML
- La modularización de funciones distintas, de modo que las aplicaciones solo carguen las bibliotecas necesarias para sus necesidades individuales
- El control de versiones de tipos y recursos, de modo que el módulo pueda actualizarse de forma segura sin afectar al código del cliente
Módulos QML modernos
La mejor forma de definir los módulos QML es mediante la API de CMake, en concreto con qt_add_qml_module. Las siguientes secciones describen todos los aspectos relacionados con la creación de un módulo QML moderno.
Definición de tipos de objetos mediante documentos QML
Los tipos QML se pueden definir directamente en documentos QML, lo cual es la forma más sencilla de crear componentes reutilizables. Cada archivo QML que comienza con una letra mayúscula define automáticamente un tipo que pueden utilizar otros archivos QML del mismo módulo.
Definición de tipos QML desde C++
Para obtener un mejor rendimiento o acceder a API de bajo nivel, los tipos se pueden definir en C++ y exponer a QML. Los tipos de C++ proporcionan un control total sobre las propiedades, los métodos y las señales, al tiempo que se benefician del tipado estático y la compilación.
Integrarlo todo con CMake
El comando de CMake «qt_add_qml_module » agrupa archivos QML, tipos de C++ y recursos en un módulo cohesionado. Se encarga automáticamente del registro de tipos, la compilación de recursos y la integración de herramientas QML, lo que lo convierte en el enfoque recomendado para el desarrollo moderno de módulos QML.
Modernización de los módulos QML
Esta guía ayuda a migrar módulos QML antiguos basados en CMake a versiones más recientes de Qt. Explica cómo adaptarse a las nuevas políticas de CMake y evitar técnicas obsoletas.
Ajuste fino de los módulos QML
Las opciones avanzadas de configuración de módulos descritas en «Escribir módulos QML» permiten un control minucioso del comportamiento de los módulos. Esto incluye la incorporación de varios módulos QML en el mismo binario, el control de versiones, las estructuras de directorios personalizadas y temas avanzados sobre complementos QML.
Módulos QML antiguos
Nota: Utiliza la API de CMake para definir un módulo QML. Define tu módulo QML manualmente solo si necesitas utilizar ` qmake`.
Un módulo se define mediante un archivo qmldir de definición de módulo. Cada módulo tiene un espacio de nombres de tipos asociado, que es el identificador del módulo. Un módulo puede proporcionar tipos de objetos QML (definidos bien mediante documentos QML o a través de un complemento de C++) y recursos de JavaScript, y puede ser importado por los clientes.
Para definir un módulo, el desarrollador debe reunir en un único directorio los distintos documentos QML, recursos JavaScript y complementos de C++ que pertenecen al módulo, y escribir un archivo qmldir de definición de módulo adecuado, que también debe colocarse en dicho directorio. A continuación, el directorio puede instalarse en la ruta de importación de QML como un módulo.
Ten en cuenta que definir un módulo no es la única forma de compartir tipos QML comunes dentro de un proyecto; también se puede utilizar para este fin una simple importación de un directorio de documentos QML.
Tipos de módulos QML compatibles
QML admite dos tipos diferentes de módulos:
- Módulos identificados
- Módulos heredados (obsoletos)
Los módulos identificados definen explícitamente su identificador y se instalan en la ruta de importación de QML. Los módulos identificados son más fáciles de mantener (gracias al control de versiones de los tipos) y cuentan con garantías de registro de tipos por parte del motor de QML, algo de lo que carecen los módulos heredados. Los módulos heredados solo se admiten para permitir que el código heredado siga funcionando con la última versión de QML, y los clientes deben evitarlos en la medida de lo posible.
Los clientes pueden importar un módulo QML desde documentos QML o archivos JavaScript. Consulta la documentación sobre la importación de módulos QML para obtener más información al respecto.
Proporcionar tipos y funcionalidad en un complemento de C++
Una aplicación que tenga gran parte de su lógica implementada en C++, o que defina tipos en C++ y los exponga a QML, puede necesitar implementar un complemento de QML. Un desarrollador de módulos de extensión de QML puede optar por implementar algunos tipos en un complemento de C++ (en lugar de definirlos mediante documentos QML) para lograr un mejor rendimiento o una mayor flexibilidad.
Cada complemento de C++ para QML tiene una función de inicialización que el motor de QML invoca al cargar el complemento. Esta función de inicialización debe registrar todos los tipos que proporciona el complemento, pero no debe realizar ninguna otra acción (por ejemplo, no está permitido instanciar objetos QObject).
Consulta Creación de complementos de C++ para QML para obtener más información.
Véase también «Modernización demó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.