QTP0004

Zusätzliche Verzeichnisse mit QML-Dateien in einem QML-Modul benötigen zusätzliche qmldir-Dateien.

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

Die Aktivierung dieser Richtlinie stellt sicher, dass der implizite Import jeder QML-Komponente in Ihrem Modul derselbe ist wie der des Moduls selbst. Dies bedeutet, dass alle Komponenten einander sehen können, ohne das Modul explizit zu importieren.

Das OLD Verhalten dieser Richtlinie ist, dass eine qmldir-Datei nur für das Stammverzeichnis eines Moduls erzeugt wird.

Das NEW Verhalten dieser Richtlinie ist, dass für jedes Verzeichnis mit QML-Dateien in einem Modul eine separate qmldir-Datei erzeugt wird. Jedes erzeugte qmldir enthält eine prefer Direktive, die den impliziten Import auf den kanonischen Ressourcenspeicherort 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 wird dieser implizite Import in das Modul selbst aufgelöst, so dass alle Geschwisterkomponenten sichtbar sind. Wenn sich QML-Dateien jedoch in Unterverzeichnissen befinden, wird der implizite Import stattdessen in dieses Unterverzeichnis aufgelöst. Komponenten im Unterverzeichnis können dann keine anderen Komponenten im selben Modul sehen, ohne eine explizite import -Anweisung hinzuzufügen. Dies ist eine häufige Fehlerquelle.

Mit dem NEW -Verhalten erzeugt das Build-System eine qmldir-Datei in jedem Unterverzeichnis, die eine prefer -Direktive enthält, die auf den kanonischen Ressourcenspeicherort des Moduls zeigt. Dies macht den impliziten Import jeder QML-Datei im Modul äquivalent zum Import des Moduls selbst, so dass alle Komponenten einander unabhängig von ihrem Verzeichnis finden können.

Beispiel

Nehmen wir ein Modul mit QML-Dateien, die über mehrere Unterverzeichnisse verteilt sind:

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

Es kommt häufig vor, dass views/MyView.qml MyButton aus dem Unterverzeichnis controls verwenden muss. Mit dem OLD Verhalten schlägt dies stillschweigend fehl: views/MyView.qml importiert implizit das views Unterverzeichnis, so dass MyButton nicht gefunden wird, es sei denn, Sie fügen import MyModule explizit hinzu.

Beim Verhalten NEW wird ein zusätzliches qmldir in den beiden Unterverzeichnissen controls und views erzeugt. Beide leiten den impliziten Import auf den kanonischen Ressourcenspeicherort des Moduls um, so dass views/MyView.qml MyButton und jeden anderen Typ im Modul ohne expliziten Import verwenden kann.

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

qt_policy(SET QTP0004 NEW)

Alternativ dazu können Sie qt_standard_project_setup() mit einer REQUIRES Version von 6.8 oder höher aufrufen.

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