Identifizierte Module

Identifizierte Module sind Module, die installiert und für die QML-Engine durch einen URI in Form einer gepunkteten Identifizierungszeichenfolge identifizierbar sind, die vom Modul in seiner Datei qmldir angegeben werden sollte. Auf diese Weise können solche Module mit einem eindeutigen Bezeichner importiert werden, der immer gleich bleibt, egal wo sich das Modul im lokalen Dateisystem befindet.

Beim Importieren eines identifizierten Moduls wird ein nicht in Anführungszeichen gesetzter Bezeichner mit einer optionalen Versionsnummer verwendet:

import QtQuick
import com.nokia.qml.mymodule 1.0

Identifizierte Module müssen in den Importpfad installiert werden, damit sie von der QML-Engine gefunden werden können.

Syntaktisch muss jedes durch Punkte getrennte Segment des URI ein wohlgeformter ECMAScript Identifier Name sein. Das bedeutet zum Beispiel, dass die Segmente nicht mit einer Zahl beginnen und keine - (Minus-)Zeichen enthalten dürfen. Da der URI in Verzeichnisnamen übersetzt wird, sollten Sie ihn auf alphanumerische Zeichen des lateinischen Alphabets, Unterstriche und Punkte beschränken.

Lokal installierte, identifizierte Module

Ein Verzeichnis mit QML- und/oder C++-Dateien kann als identifiziertes Modul freigegeben werden, wenn es eine qmldir-Datei mit den Modul-Metadaten enthält und im QML-Importpfad installiert ist. Jede QML-Datei auf dem lokalen Dateisystem kann dieses Verzeichnis als Modul importieren, indem sie eine Importanweisung verwendet, die auf den URI des Moduls verweist, so dass die Datei die vom Modul definierten QML-Objekttypen und JavaScript-Ressourcen verwenden kann.

Die Datei qmldir des Moduls muss sich in einer Verzeichnisstruktur innerhalb des Importpfads befinden, die die gepunktete Bezeichnerzeichenfolge des URI widerspiegelt, wobei jeder Punkt (".") im Bezeichner eine Unterebene im Verzeichnisbaum darstellt. Zum Beispiel muss sich die Datei qmldir des Moduls com.mycompany.mymodule im Unterpfad com/mycompany/mymodule/qmldir irgendwo im Importpfad befinden.

Es ist möglich, verschiedene Versionen eines Moduls in eigenen Unterverzeichnissen zu speichern. Zum Beispiel könnte die Version 2.1 eines Moduls unter com/mycompany/mymodule.2/qmldir oder com/mycompany/mymodule.2.1/qmldir liegen. Die Engine lädt automatisch das Modul, das am besten passt.

Alternativ kann die Versionierung für verschiedene Typen auch in einer qmldir-Datei selbst definiert werden, was jedoch die Aktualisierung eines solchen Moduls erschweren kann (da eine qmldir -Datei als Teil des Aktualisierungsvorgangs zusammengeführt werden muss).

Ein Beispiel

Betrachten Sie die folgende Verzeichnisstruktur des QML-Projekts. Unter dem obersten Verzeichnis myapp befindet sich eine Reihe von gemeinsamen UI-Komponenten in einem Unterverzeichnis namens mycomponents und der Hauptanwendungscode in einem Unterverzeichnis namens main:

myapp
    |- mycomponents
        |- CheckBox.qml
        |- DialogBox.qml
        |- Slider.qml
    |- main
        |- application.qml

Um das Verzeichnis mycomponents als identifiziertes Modul verfügbar zu machen, muss das Verzeichnis eine qmldir-Datei enthalten, die den Modulidentifikator definiert und die Objekttypen beschreibt, die durch das Modul verfügbar gemacht werden. Um zum Beispiel die Typen CheckBox, DialogBox und Slider für die Version 1.0 des Moduls verfügbar zu machen, würde die Datei qmldir Folgendes enthalten:

module myapp.mycomponents
CheckBox 1.0 CheckBox.qml
DialogBox 1.0 DialogBox.qml
Slider 1.0 Slider.qml

Außerdem muss der Speicherort der Datei qmldir im Importpfad mit der gepunkteten Bezeichnerzeichenfolge des Moduls übereinstimmen. Angenommen, das oberste Verzeichnis myapp befindet sich in C:\qml\projects, und das Modul soll als "myapp.mycomponents" identifiziert werden. In diesem Fall:

• Der Pfad C:\qml\projects sollte zum Importpfad hinzugefügt werden.
• Die qmldir-Datei sollte sich unter C:\qml\projects\myapp\mycomponents\qmldir

Sobald dies geschehen ist, kann eine QML-Datei, die sich irgendwo im lokalen Dateisystem befindet, das Modul importieren, indem sie auf seinen URI und die entsprechende Version verweist:

import myapp.mycomponents 1.0

DialogBox {
    CheckBox {
        // ...
    }
    Slider {
        // ...
    }
}

Entfernt installierte identifizierte Module

Identifizierte Module sind auch als Netzwerkressource zugänglich. Wenn im vorigen Beispiel das Verzeichnis C:\qml\projects als http://www.some-server.com/qml/projects gehostet wurde und diese URL dem QML-Importpfad hinzugefügt wurde, könnte das Modul auf genau dieselbe Weise importiert werden.

Beachten Sie, dass eine Datei, die ein Modul über ein Netzwerk importiert, nur auf die vom Modul bereitgestellten QML- und JavaScript-Ressourcen zugreifen kann; sie kann nicht auf Typen zugreifen, die von C++-Plugins im Modul definiert wurden.

Semantik von identifizierten Modulen

Ein identifiziertes Modul wird von der QML-Engine mit den folgenden Garantien ausgestattet:

• andere Module können die Typen im Namensraum des Moduls nicht ändern oder überschreiben
• andere Module können keine neuen Typen im Namensraum des Moduls registrieren
• Die Verwendung von Typnamen durch Clients wird deterministisch zu einer bestimmten Typdefinition aufgelöst, abhängig von der angegebenen Versionierung und der Importreihenfolge.

Dadurch wird sichergestellt, dass Clients, die das Modul verwenden, sicher sein können, dass sich die im Modul definierten Objekttypen so verhalten, wie es der Modulautor dokumentiert hat.

Ein identifiziertes Modul unterliegt mehreren Einschränkungen:

• ein identifiziertes Modul muss im QML-Importpfad installiert sein
• der in der Modul-Identifizierungs-Direktive angegebene Modul-Identifizierer muss mit dem Installationspfad des Moduls übereinstimmen (relativ zum QML-Importpfad, wobei Verzeichnis-Trennzeichen durch Punkt-Zeichen ersetzt werden)
• das Modul muss seine Typen im Typ-Namensraum des Modulbezeichners registrieren
• Das Modul darf keine Typen in den Namespace eines anderen Moduls registrieren.

Wenn beispielsweise ein identifiziertes Modul in $QML_IMPORT_PATH/ExampleModule installiert wird, muss die Modulbezeichner-Direktive lauten:

module ExampleModule

Wenn das strikte Modul in $QML_IMPORT_PATH/com/example/CustomUi installiert ist, muss die Modulbezeichner-Direktive lauten:

module com.example.CustomUi

Clients können dann das oben genannte Modul mit der folgenden Import-Anweisung importieren:

import com.example.CustomUi