Portar módulos QML a CMake

Los módulos QML son ahora más potentes y fáciles de usar en Qt 6. Las siguientes secciones describen cómo portar módulos QML a la API qt_add_qml_module de CMake.

Consulte también Modernización de módulos QML sobre cómo modernizar un módulo QML que ya utiliza qt_add_qml_module.

Identificar problemas a solucionar

Utilice qmllint para ayudarle durante el proceso.

Cada módulo QML definido con qt_add_qml_module tiene un objetivo CMake _qmllint que puede utilizar para identificar posibles problemas o mejoras. Para un módulo QML llamado MyQmlLibrary utilice MyQmlLibrary_qmllint, por ejemplo. Para ejecutar qmllint en todos los módulos QML, utilice all_qmllint.

Las categorías de advertencia de qmllint que indican problemas con los módulos QML son:

• [import]
• [importaciones no utilizadas]
• [tipo no resuelto]
• [alias no resuelto]
• [missing-enum-entry]
• [missing-property] [missing-type
• [falta-tipo]

Preparar el proyecto para qt_add_qml_module

Hacer qt_add_qml_module disponible en CMake

Para que qt_add_qml_module esté disponible en CMake, añada Core y Qml a su llamada a find_package en el archivo CMakeLists.txt de nivel superior del proyecto:

find_package(Qt6 REQUIRED COMPONENTS Core Qml)

Utilice qt_standard_project_setup

qt_standard_project_setup configura las políticas de Qt CMake necesarias para qt_add_qml_module, entre otras cosas.

Llame qt_standard_project_setup en el archivo CMakeLists.txt de nivel superior del proyecto antes de cualquier llamada qt_add_qml_module:

qt_standard_project_setup(REQUIRES 6.8)

Utilice qt_add_qml_module

qt_add_qml_module es la función de CMake que se encarga de generar los módulos QML. Genera automáticamente los archivos qmldir y qmltypes, y configura herramientas como qmlcachegen o qmllint.

Los módulos QML pueden añadirse tanto a ejecutables como a bibliotecas en CMake. Los módulos QML adjuntos al ejecutable no pueden ser utilizados o enlazados por otros ejecutables, mientras que los módulos QML adjuntos a las bibliotecas sí pueden.

Añadir un módulo QML al 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 se integra completamente en el ejecutable. Como resultado, el módulo está vinculado a ese programa específico y no puede ser reutilizado por otros ejecutables o bibliotecas.

Para añadir un módulo QML a su ejecutable, en su 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
)

Main.qml debe empezar con 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 de destino para evitar conflictos de nombres en la carpeta de compilación.

Añadir un módulo QML a la biblioteca de destino

Para añadir un módulo QML a la biblioteca, en 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.

Utilice loadFromModule para cargar sus archivos QML

Utilice loadFromModule para cargar su archivo QML, por ejemplo:

engine.load(QUrl(QStringLiteral("qrc:/MyQmlModule/Main.qml")));
// becomes
engine.loadFromModule("MyQmlModule", "Main");

Eliminar los archivos qmldir escritos a mano

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)

Elimine después los qmldir declarados a mano.

Eliminar los archivos qmltypes generados por qmlplugindump

qt_add_qml_module auto-genera archivos qmltypes cuando todos tus tipos están usando el registro declarativo de tipos, lo que elimina la necesidad de generar archivos qmltypes a mano usando herramientas como qmlplugindump.

Para conseguirlo, elimina las llamadas manuales a qmlRegisterType y sus variantes. Entonces, registra tus tipos declarativamente usando 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
    ....
};

Ver Registro de tipos C++ con el sistema de tipos QML sobre cómo manejar casos de registro más complicados como el registro de tipos foráneos.

Elimine después los archivos qmltypes escritos a mano.

Eliminar los plugins de registro de tipos escritos a mano

qt_add_qml_module puede generar un plugin de módulo QML automáticamente para usted. No necesitas un plugin escrito a mano si la única tarea de tu plugin es hacer el registro de tipos. Elimine el plugin por completo si el cambio al registro de tipos declarativo eliminó todo el código de su plugin.

Asegúrese 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 plugin.

Eliminar archivos qrc

qt_add_qml_module genera automáticamente archivos qrc. Para listar recursos en los archivos qrc, como imágenes o archivos de sonido, añádalos al argumento RESOURCES de qt_add_qml_module. Puede encontrar los recursos del módulo en :/qt/qml/MyQmlLibraryModule/.

Sustitución de importaciones de directorios por importaciones de módulos QML

Sustituya las importaciones de directorios por importaciones de módulos QML. Por ejemplo,

import "content" // contains SomeType.qml
// becomes
import MyQmlModule // contains SomeType.qml

SomeType {
    ...
}

Tenga en cuenta que los archivos dentro de un módulo QML importan automáticamente su propio módulo QML. Puede eliminar las autoimportaciones.