QTP0004

Zusätzliche Verzeichnisse mit QML-Dateien in einem QML-Modul erfordern zusätzliche qmldir-Dateien.

Diese Richtlinie wurde in Qt 6.8 eingeführt. Sie bewirkt, dass das Build-System für jedes zusätzliche Verzeichnis, das QML-Dateien in einem QML-Modul enthält, eine zusätzliche „qmldir“-Datei generiert.

Durch die Aktivierung dieser Richtlinie wird sichergestellt, dass der implizite Import jeder der QML-Komponenten in Ihrem Modul mit dem des Moduls selbst übereinstimmt. Das bedeutet, dass alle Komponenten einander erkennen können, ohne das Modul explizit importieren zu müssen.

Das „ OLD “-Verhalten dieser Richtlinie sieht vor, dass eine „qmldir“-Datei nur für das Stammverzeichnis eines Moduls generiert wird.

Das „ NEW “-Verhalten dieser Richtlinie besteht darin, dass für jedes Verzeichnis mit QML-Dateien in einem Modul eine separate „qmldir“-Datei generiert wird. Jede generierte „qmldir“-Datei enthält eine „ prefer “-Anweisung, die den impliziten Import auf den kanonischen Ressourcenpfad des Moduls umleitet.

Hintergrund

Die QML-Engine führt immer einen impliziten Import des Verzeichnisses durch, in dem sich eine QML-Datei befindet. Bei Dateien im Stammverzeichnis des Moduls führt dieser implizite Import zum Modul selbst, sodass alle gleichrangigen Komponenten sichtbar sind. Befinden sich QML-Dateien jedoch in Unterverzeichnissen, führt der implizite Import stattdessen zu diesem Unterverzeichnis. Komponenten im Unterverzeichnis können dann andere Komponenten im selben Modul nicht sehen, ohne eine explizite ` import `-Anweisung hinzuzufügen. Dies ist eine häufige Fehlerquelle.

Mit dem „ NEW “-Verhalten generiert das Build-System in jedem Unterverzeichnis eine „qmldir“-Datei, die eine „ prefer “-Anweisung enthält, die auf den kanonischen Ressourcenpfad des Moduls verweist. Dadurch entspricht der implizite Import jeder QML-Datei im Modul dem Import des Moduls selbst, sodass alle Komponenten einander unabhängig von ihrem Verzeichnis finden können.

Beispiel

Betrachten wir ein Modul, dessen QML-Dateien auf mehrere Unterverzeichnisse verteilt sind:

qt_add_qml_module(mymodule
    URI MyModule
    QML_FILES
        Main.qml
        controls/MyButton.qml
        views/MyView.qml
)

Häufig soll ` views/MyView.qml ` die Datei ` MyButton ` aus dem Unterverzeichnis ` controls ` verwenden. Mit dem Verhalten „ OLD “ schlägt dies ohne Fehlermeldung fehl: ` views/MyView.qml ` importiert implizit das Unterverzeichnis ` views `, sodass ` MyButton ` nicht gefunden wird, es sei denn, man fügt ` import MyModule ` explizit hinzu.

Beim Verhalten „ NEW “ wird sowohl im Unterverzeichnis „ controls “ als auch im Unterverzeichnis „ views “ ein zusätzliches „qmldir“ generiert. Jedes davon leitet den impliziten Import zum kanonischen Ressourcenpfad des Moduls um, sodass views/MyView.qml MyButton und jeden anderen Typ im Modul ohne expliziten Import verwenden kann.

Sie können die Richtlinie explizit in Ihrem Projekt festlegen, bevor Sie qt_add_qml_module() aufrufen:

qt_policy(SET QTP0004 NEW)

Alternativ können Sie ` qt_standard_project_setup() ` mit einer Version von ` REQUIRES ` ab 6.8 aufrufen.

Qt 6.8 gibt Warnungen aus, wenn Sie die Richtlinie nicht explizit festlegen.