QML-Module nach CMake portieren

QML-Module sind in Qt 6 leistungsfähiger und einfacher zu verwenden geworden. Die folgenden Abschnitte beschreiben, wie man QML-Module auf die qt_add_qml_module CMake API portiert.

Siehe auch Moderne QML-Module, wie man ein QML-Modul modernisiert, das bereits qt_add_qml_module verwendet.

Identifizieren Sie zu behebende Probleme

Verwenden Sie qmllint, um Sie durch den Prozess zu unterstützen.

Jedes QML-Modul, das mit qt_add_qml_module definiert wurde, hat ein _qmllint CMake-Target, das Sie verwenden können, um mögliche Probleme oder Verbesserungen zu identifizieren. Für ein QML-Modul namens MyQmlLibrary verwenden Sie zum Beispiel MyQmlLibrary_qmllint. Um qmllint auf alle QML-Module anzuwenden, verwenden Sie all_qmllint.

Die Warnkategorien von qmllint, die auf Probleme mit QML-Modulen hinweisen, sind:

• [import]
• [unused-imports]
• [unresolved-type]
• [unresolved-alias]
• [missing-enum-entry]
• [missing-property]
• [missing-type]

Das Projekt für qt_add_qml_module vorbereiten

qt_add_qml_module in CMake verfügbar machen

Um qt_add_qml_module in CMake verfügbar zu machen, fügen Sie Core und Qml zu Ihrem find_package Aufruf in der Top-Level-Datei des Projekts CMakeLists.txt hinzu:

find_package(Qt6 REQUIRED COMPONENTS Core Qml)

Verwenden Sie qt_standard_project_setup

qt_standard_project_setup setzt die Qt CMake Richtlinien, die unter anderem für qt_add_qml_module benötigt werden.

Rufen Sie qt_standard_project_setup in der obersten Datei des Projekts CMakeLists.txt vor jedem qt_add_qml_module Aufruf auf:

qt_standard_project_setup(REQUIRES 6.8)

Verwenden Sie qt_add_qml_module

qt_add_qml_module ist die CMake-Funktion, die sich um die Erzeugung von QML-Modulen kümmert. Sie generiert automatisch qmldir und qmltypes Dateien und richtet Werkzeuge wie qmlcachegen oder qmllint ein.

QML-Module können in CMake sowohl zu ausführbaren als auch zu Bibliothekszielen hinzugefügt werden. QML-Module, die an ein ausführbares Ziel angehängt sind, können nicht von anderen ausführbaren Programmen verwendet oder gelinkt werden, während QML-Module, die an Bibliotheksziele angehängt sind, dies können.

Hinzufügen eines QML-Moduls zu Ihrem ausführbaren Ziel

In diesem Fall werden die Quelldateien des QML-Moduls als Teil der ausführbaren Datei selbst behandelt und nicht in eine separate Bibliothek kompiliert. Das bedeutet, dass weder ein Modul noch eine Plugin-Bibliothek für dieses Modul erstellt wird - das Modul ist vollständig in die ausführbare Datei integriert. Folglich ist das Modul an dieses spezielle Programm gebunden und kann nicht von anderen ausführbaren Programmen oder Bibliotheken wiederverwendet werden.

Um ein QML-Modul zu Ihrer ausführbaren Datei hinzuzufügen, geben Sie in Ihrem CMakeLists.txt ein:

# 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
)

Das Main.qml sollte mit einem Großbuchstaben beginnen, damit es von loadFromModule Methoden wie QQmlApplicationEngine::loadFromModule oder QQmlComponent::loadFromModule instanziiert werden kann. Außerdem sollte sich der QML-Modul-URI vom Zielnamen unterscheiden, um Namenskonflikte im Build-Ordner zu vermeiden.

Hinzufügen eines QML-Moduls zu Ihrem Bibliotheksziel

Um ein QML-Modul zu Ihrer Bibliothek hinzuzufügen, fügen Sie in Ihrem 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 erstellt eine SHARED Bibliothek über qt_add_library, wenn das MyQmlLibrary Ziel noch nicht existiert, wie in diesem Beispiel.

Verwenden Sie loadFromModule, um Ihre QML-Dateien zu laden

Verwenden Sie loadFromModule, um Ihre QML-Datei zu laden, zum Beispiel:

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

Entfernen Sie handgeschriebene qmldir-Dateien

qt_add_qml_module erzeugt automatisch qmldir Dateien. Wenn Sie Singletons in Ihrem qmldir haben, deklarieren Sie diese in Ihrem CMakeLists.txt vor dem qt_add_qml_module Aufruf mit:

set_source_files_properties(MySingleton.qml PROPERTIES QT_QML_SINGLETON_TYPE TRUE)

Löschen Sie danach die handgeschriebene qmldir.

Entfernen der von qmlplugindump erzeugten qmltypes-Dateien

qt_add_qml_module generiert automatisch qmltypes Dateien, wenn alle Ihre Typen die deklarative Typregistrierung verwenden, wodurch die Notwendigkeit entfällt, qmltypes Dateien von Hand mit Tools wie qmlplugindump zu generieren.

Um dies zu erreichen, entfernen Sie manuelle Aufrufe von qmlRegisterType und seinen Varianten. Registrieren Sie dann Ihre Typen deklarativ, zum Beispiel mit QML_ELEMENT:

// 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
    ....
};

Siehe Registrierung von C++-Typen mit dem QML-Typesystem, um kompliziertere Registrierungsfälle wie die Registrierung fremder Typen zu behandeln.

Löschen Sie danach die handgeschriebenen qmltypes Dateien.

Entfernen Sie handgeschriebene Typregistrierungs-Plugins

qt_add_qml_module kann automatisch ein QML-Modul-Plugin für Sie erzeugen. Sie brauchen kein handgeschriebenes Plugin, wenn die einzige Aufgabe Ihres Plugins darin besteht, die Typregistrierung durchzuführen. Entfernen Sie das Plugin ganz, wenn der Wechsel zur deklarativen Typregistrierung den gesamten Code aus Ihrem Plugin entfernt hat.

Stellen Sie sicher, dass Sie die Argumente NO_PLUGIN, NO_PLUGIN_OPTIONAL, NO_CREATE_PLUGIN_TARGET und NO_GENERATE_PLUGIN_SOURCE aus qt_add_qml_module entfernen, um eine automatische Plugin-Generierung zu ermöglichen.

Entfernen von qrc-Dateien

qt_add_qml_module generiert automatisch qrc Dateien. Um Ressourcen in den qrc Dateien aufzulisten, wie z.B. Bilder oder Sounddateien, fügen Sie diese dem RESOURCES Argument von qt_add_qml_module hinzu. Sie können die Ressourcen des Moduls unter :/qt/qml/MyQmlLibraryModule/ finden.

Ersetzen von Verzeichnisimporten durch QML-Modulimporte

Ersetzen Sie Verzeichnisimporte durch QML-Modulimporte. Zum Beispiel,

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

SomeType {
    ...
}

Beachten Sie, dass Dateien innerhalb eines QML-Moduls automatisch ihr eigenes QML-Modul importieren. Sie können die Selbst-Importe entfernen.