Identifizierte Module

Identifizierte Module sind Module, die installiert sind und von der QML-Engine anhand einer URI in Form einer durch Punkte getrennten Bezeichnerzeichenfolge identifiziert werden können, die vom Modul in seiner Datei „ qmldir “ angegeben werden sollte. Dadurch können solche Module mit einem eindeutigen Bezeichner importiert werden, der unabhängig vom Speicherort des Moduls im lokalen Dateisystem immer gleich bleibt.

Beim Importieren eines identifizierten Moduls wird ein nicht in Anführungszeichen gesetzter Bezeichner verwendet, optional ergänzt um eine Versionsnummer:

import QtQuick
import com.mycompany.qml.mymodule 1.0

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

Syntaktisch muss jedes durch einen Punkt getrennte Segment der URI ein wohlgeformter ECMAScript-Bezeichner sein. Das bedeutet beispielsweise, dass die Segmente nicht mit einer Zahl beginnen dürfen und keine Minuszeichen ( - ) enthalten dürfen. Da die URI in Verzeichnisnamen übersetzt wird, sollten Sie sie 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 Metadaten des Moduls 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 die URI des Moduls verweist. Dadurch kann die Datei die vom Modul definierten QML-Objekttypen und JavaScript-Ressourcen nutzen.

Die Datei „ qmldir “ des Moduls muss sich in einer Verzeichnisstruktur innerhalb des Importpfads befinden, die die URI-Bezeichnerzeichenfolge mit Punkten widerspiegelt, wobei jeder Punkt („.“) im Bezeichner eine Unterebene in der Verzeichnisstruktur darstellt. Beispielsweise 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. Beispielsweise könnte sich eine Version 2.1 eines Moduls unter com/mycompany/mymodule.2/qmldir oder com/mycompany/mymodule.2.1/qmldir befinden. Die Engine lädt automatisch das Modul, das am besten passt.

Alternativ kann die Versionierung für verschiedene Typen innerhalb einer qmldir-Datei selbst definiert werden; dies kann jedoch die Aktualisierung eines solchen Moduls erschweren (da im Rahmen des Aktualisierungsvorgangs eine Zusammenführung der Datei „ qmldir “ erfolgen muss).

Ein Beispiel

Betrachten Sie die folgende Verzeichnisstruktur eines QML-Projekts. Unter dem obersten Verzeichnis „ myapp “ befinden sich eine Reihe gängiger UI-Komponenten in einem Unterverzeichnis namens „ mycomponents “ sowie der Hauptanwendungscode in einem Unterverzeichnis namens „ main “, wie folgt:

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 Modulbezeichner definiert und die vom Modul bereitgestellten Objekttypen beschreibt. Um beispielsweise die Typen „ CheckBox “, „ DialogBox “ und „ Slider “ für 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

Zudem muss der Speicherort der Datei „ qmldir “ im Importpfad mit der gepunkteten Bezeichnerzeichenfolge des Moduls übereinstimmen. Angenommen, das oberste Verzeichnis „ myapp “ befindet sich unter „ 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 Datei „qmldir“ sollte sich unter C:\qml\projects\myapp\mycomponents\qmldir

Sobald dies erledigt ist, kann eine QML-Datei, die sich an beliebiger Stelle im lokalen Dateisystem befindet, das Modul importieren, indem sie auf dessen URI und die entsprechende Version verweist:

import myapp.mycomponents 1.0

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

Remote installierte, identifizierte Module

Identifizierte Module sind auch als Netzwerkressource zugänglich. Im vorherigen Beispiel könnte das Modul auf genau dieselbe Weise importiert werden, wenn das Verzeichnis „ C:\qml\projects “ unter „ http://www.some-server.com/qml/projects “ gehostet und diese URL zum QML-Importpfad hinzugefügt würde.

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

Semantik identifizierter Module

Ein identifiziertes Modul erhält von der QML-Engine folgende Garantien:

• Andere Module können Typen im Namensraum des Moduls weder ändern noch überschreiben
• Andere Module können keine neuen Typen im Namensraum des Moduls registrieren
• Die Verwendung von Typnamen durch Clients führt deterministisch zu einer bestimmten Typdefinition, 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.

Für ein identifiziertes Modul gelten mehrere Einschränkungen:

• Ein identifiziertes Modul muss im QML-Importpfad installiert sein
• Die in der Modulbezeichner-Anweisung angegebene Modulbezeichnung muss mit dem Installationspfad des Moduls übereinstimmen (relativ zum QML-Importpfad, wobei Verzeichnistrennzeichen durch Punkte ersetzt werden)
• Das Modul muss seine Typen im Typen-Namespace des Modulidentifikators registrieren
• Das Modul darf keine Typen im Namensraum eines anderen Moduls registrieren

Wenn beispielsweise ein identifiziertes Modul unter „ $QML_IMPORT_PATH/ExampleModule “ installiert ist, muss die Modulbezeichner-Direktive wie folgt lauten:

module ExampleModule

Wenn das Modul „strict“ unter „ $QML_IMPORT_PATH/com/example/CustomUi “ installiert ist, muss die Modulbezeichner-Direktive wie folgt lauten:

module com.example.CustomUi

Clients können das oben genannte Modul dann mit der folgenden Importanweisung importieren:

import com.example.CustomUi