Portar módulos QML a CMake
Los módulos Qml se han vuelto más potentes y fáciles de usar en Qt 6. En las siguientes secciones se describe cómo portar módulos Qml a la API de CMake qt_add_qml_module.
Consulta también «Modernización de módulos QML » para saber cómo modernizar un módulo QML que ya utiliza ` qt_add_qml_module`.
Identifica los problemas que hay que solucionar
Utiliza qmllint como ayuda durante el proceso.
Cada módulo QML definido con `qt_add_qml_module` tiene un objetivo de CMake ` _qmllint ` que puedes utilizar para identificar posibles problemas o mejoras. Por ejemplo, para un módulo QML llamado ` MyQmlLibrary `, utiliza ` MyQmlLibrary_qmllint`. Para ejecutar `qmllint` en todos los módulos QML, utiliza ` all_qmllint`.
Las categorías de advertencias de qmllint que indican problemas en los módulos QML son:
- [import]
- [unused-imports]
- [unresolved-type]
- [alias-no-resuelto]
- [entrada-de-enumeración-faltante]
- [propiedad que falta]
- [tipo-que-falta]
Prepara el proyecto para qt_add_qml_module
Hacer que qt_add_qml_module esté disponible en CMake
Para que qt_add_qml_module esté disponible en CMake, añade Core y Qml a tu llamada a find_package en el archivo CMakeLists.txt de nivel superior del proyecto:
find_package(Qt6 REQUIRED COMPONENTS Core Qml)Utiliza qt_standard_project_setup
qt_standard_project_setup configura, entre otras cosas, las políticas de CMake de Qt necesarias para qt_add_qml_module.
Llama a `qt_standard_project_setup ` en el archivo de nivel superior del proyecto ` CMakeLists.txt ` antes de cualquier llamada a ` qt_add_qml_module `:
qt_standard_project_setup(REQUIRES 6.8)Utiliza qt_add_qml_module
`qt_add_qml_module` es la función de CMake que se encarga de generar módulos QML. Genera automáticamente los archivos ` qmldir ` y ` qmltypes `, y configura herramientas como `qmlcachegen ` o `qmllint`.
Los módulos QML se pueden añadir tanto a objetivos ejecutables como a objetivos de biblioteca en CMake. Los módulos QML asociados a un objetivo ejecutable no pueden ser utilizados ni enlazados por otros ejecutables, mientras que los módulos QML asociados a objetivos de biblioteca sí pueden.
Añadir un módulo QML a tu objetivo ejecutable
En este caso, los archivos fuente del módulo QML se tratan como parte del propio ejecutable, en lugar de compilarse en una biblioteca independiente. Esto significa que no se crea ni un módulo ni una biblioteca de complementos para este módulo: el módulo queda totalmente integrado en el ejecutable. Como resultado, el módulo queda vinculado a ese programa específico y no puede ser reutilizado por otros ejecutables o bibliotecas.
Para añadir un módulo QML a tu ejecutable, en tu ` CMakeLists.txt`:
# pre-existing:
qt_add_executable(MyApp main.cpp)
# add this
qt_add_qml_module(MyApp
URI MyAppModule
QML_FILES
Main.qml # and possibly more .qml files
)El nombre del objetivo « Main.qml » debe comenzar con una letra mayúscula para que pueda ser instanciado por métodos de « loadFromModule » como « QQmlApplicationEngine::loadFromModule » o « QQmlComponent::loadFromModule ». Además, el URI del módulo QML debe ser diferente del nombre del objetivo para evitar conflictos de nombres en la carpeta de compilación.
Añadir un módulo QML al destino de tu biblioteca
Para añadir un módulo QML a tu biblioteca, en tu archivo ` CMakeLists.txt`:
qt_add_qml_module(MyQmlLibrary
URI MyQmlModule
QML_FILES MyQmlComponent1.qml MyQmlComponent2.qml...
SOURCES MyCppComponent1.h MyCppComponent1.cpp MyCppComponent2.h MyCppComponent2.cpp...
RESOURCES MyResource1.png MyResource2.png...
)qt_add_qml_module crea una biblioteca « SHARED » mediante qt_add_library si el objetivo « MyQmlLibrary » aún no existe, como en este ejemplo.
Nota: El URIde tu módulo QML debe ser diferente del nombre del objetivo para evitar conflictos de nombres en la carpeta de compilación.
Utiliza `loadFromModule` para cargar tus archivos QML
Utiliza loadFromModule para cargar tu archivo QML, por ejemplo:
engine.load(QUrl(QStringLiteral("qrc:/MyQmlModule/Main.qml")));
// becomes
engine.loadFromModule("MyQmlModule", "Main");Elimina los archivos `qmldir` creados manualmente
qt_add_qml_module genera automáticamente archivos ` qmldir `. Si tienes singletons en tu ` qmldir`, decláralos en tu ` CMakeLists.txt ` antes de la llamada a ` qt_add_qml_module ` con:
set_source_files_properties(MySingleton.qml PROPERTIES QT_QML_SINGLETON_TYPE TRUE)A continuación, elimina los archivos ` qmldir ` creados manualmente.
Elimina los archivos `qmltypes` generados por `qt_plugindump`
qt_add_qml_module genera automáticamente archivos qmltypes cuando todos tus tipos utilizan el registro declarativo de tipos, lo que elimina la necesidad de generar archivos qmltypes manualmente mediante herramientas como qmlplugindump.
Para ello, elimina las llamadas manuales a ` qmlRegisterType ` y sus variantes. A continuación, registra tus tipos de forma declarativa utilizando ` QML_ELEMENT`, por ejemplo:
// add this header
#include <QtQml/qqmlregistrations.h>
class MyComponent: public QObject {
Q_OBJECT
// add this line to register MyComponent as 'MyComponent' in QML.
QML_ELEMENT
....
};Consulta «Registro de tipos C++ con el sistema de tipos de QML» para saber cómo gestionar casos de registro más complejos, como el registro de tipos externos.
A continuación, elimina los archivos « qmltypes » escritos a mano.
Elimina los complementos de registro de tipos escritos manualmente
qt_add_qml_module puede generar automáticamente un complemento de módulo QML por ti. No necesitas un complemento escrito manualmente si la única tarea de tu complemento es realizar el registro de tipos. Elimina el complemento por completo si al pasar al registro declarativo de tipos se ha eliminado todo el código de tu complemento.
Asegúrate de eliminar los argumentos NO_PLUGIN, NO_PLUGIN_OPTIONAL, NO_CREATE_PLUGIN_TARGET y NO_GENERATE_PLUGIN_SOURCE de qt_add_qml_module para permitir la generación automática del complemento.
Elimina los archivos qrc
qt_add_qml_module genera automáticamente archivos qrc. Para enumerar los recursos en los archivos qrc, como imágenes o archivos de sonido, añádelos al argumento RESOURCES de qt_add_qml_module. Puedes encontrar los recursos del módulo en :/qt/qml/MyQmlLibraryModule/.
Sustituye las importaciones de directorios por importaciones de módulos QML
Sustituye las importaciones de directorios por importaciones de módulos QML. Por ejemplo,
import "content" // contains SomeType.qml
// becomes
import MyQmlModule // contains SomeType.qml
SomeType {
...
}Ten en cuenta que los archivos dentro de un módulo QML importan automáticamente su propio módulo QML. Puedes eliminar las autoimportaciones.
Véase también Cambios en « Qt Qml » y Modernización de los módulos QML.
© 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.