Moduldefinition qmldir-Dateien

Es gibt zwei verschiedene Arten von qmldir Dateien:

• Dateien, die das QML-Dokumentenverzeichnis auflisten
• QML-Modul-Definitionsdateien

Diese Dokumentation behandelt nur die zweite Form der qmldir Datei, die die QML-Typen, JavaScript-Dateien und Plugins auflistet, die unter einem Modul verfügbar sind. Weitere Informationen über die erste Form der Datei qmldir finden Sie unter Verzeichnisauflistung qmldir-Dateien.

Inhalt einer Moduldefinitionsdatei qmldir

Eine qmldir Datei ist eine Klartextdatei, die die folgenden Befehle enthält:

• Modulbezeichner-Deklaration
• Objekttyp-Deklaration
• Interne Objekttyp-Deklaration
• JavaScript-Ressourcen-Deklaration
• Plugin-Deklaration
• Plugin Classname Deklaration
• Typbeschreibungsdatei Deklaration
• Deklaration von Modul-Abhängigkeiten
• Modul-Import-Deklaration
• Designer Support Deklaration
• Deklaration des bevorzugten Pfades

Zusätzlich zu den Befehlen können Sie auch Kommentare hinzufügen, d. h. Zeilen, die mit # beginnen.

Modulbezeichner-Deklaration

module <ModuleIdentifier>

Deklariert den Modulbezeichner des Moduls. Der <Modulbezeichner> ist der (gepunktete URI-Notation) Bezeichner für das Modul, der mit dem Installationspfad des Moduls übereinstimmen muss.

Die Modulbezeichner-Direktive muss in der ersten Zeile der Datei stehen. Es darf genau eine Modulbezeichner-Direktive in der Datei qmldir vorhanden sein.

Beispiel:

module ExampleModule

Objekttyp-Deklaration

[singleton] <TypeName> <InitialVersion> <File>

Deklariert einen QML-Objekttyp, der durch das Modul verfügbar gemacht werden soll.

• [singleton] Optional. Wird verwendet, um einen Singleton-Typ zu deklarieren.
• <TypeName> ist der Typ, der zur Verfügung gestellt wird
• <InitialVersion> ist die Modulversion, für die der Typ zur Verfügung gestellt werden soll
• <File> ist der (relative) Dateiname der QML-Datei, die den Typ definiert

In der Datei qmldir können null oder mehr Objekttyp-Deklarationen vorhanden sein. Allerdings muss jeder Objekttyp innerhalb einer bestimmten Version des Moduls einen eindeutigen Typnamen haben.

Beispiel:

//Style.qml with custom singleton type definition
pragma Singleton
import QtQuick 2.0

QtObject {
    property int textSize: 20
    property color textColor: "green"
}

// qmldir declaring the singleton type
module CustomStyles
singleton Style 1.0 Style.qml

// singleton type in use
import QtQuick 2.0
import CustomStyles 1.0

Text {
    font.pixelSize: Style.textSize
    color: Style.textColor
    text: "Hello World"
}

Interne Objekttyp-Deklaration

internal <TypeName> <File>

Deklariert einen Objekttyp, der sich im Modul befindet, aber den Benutzern des Moduls nicht zur Verfügung gestellt werden soll.

In der Datei qmldir können null oder mehr interne Objekttyp-Deklarationen vorhanden sein.

Beispiel:

internal MyPrivateType MyPrivateType.qml

Dies ist notwendig, wenn das Modul aus der Ferne importiert wird (siehe Ferninstallierte identifizierte Module), denn wenn ein exportierter Typ von einem nicht exportierten Typ innerhalb des Moduls abhängt, muss die Engine auch den nicht exportierten Typ laden.

JavaScript-Ressourcen-Deklaration

<ResourceIdentifier> <InitialVersion> <File>

Deklariert eine JavaScript-Datei, die durch das Modul verfügbar gemacht werden soll. Die Ressource wird über den angegebenen Bezeichner mit der angegebenen Versionsnummer zur Verfügung gestellt.

In der Datei qmldir können null oder mehr JavaScript-Ressourcen-Deklarationen vorhanden sein. Jede JavaScript-Ressource muss jedoch innerhalb einer bestimmten Version des Moduls einen eindeutigen Bezeichner haben.

Beispiel:

MyScript 1.0 MyScript.js

Weitere Informationen finden Sie in der Dokumentation zur Definition von JavaScript-Ressourcen und zum Import von JavaScript-Ressourcen in QML.

Plugin-Deklaration

[optional] plugin <Name> [<Path>]

Deklariert ein Plugin, das vom Modul zur Verfügung gestellt werden soll.

• optional bedeutet, dass das Plugin selbst keinen relevanten Code enthält und nur dazu dient, eine Bibliothek zu laden, auf die es verweist. Wenn angegeben und wenn irgendwelche Typen für das Modul bereits verfügbar sind, was anzeigt, dass die Bibliothek auf andere Weise geladen wurde, wird QML das Plugin nicht laden.
• <Name> ist der Name der Plugin-Bibliothek. Dieser ist normalerweise nicht identisch mit dem Dateinamen der Plugin-Binärdatei, der plattformabhängig ist. Zum Beispiel würde die Bibliothek MyAppTypes unter Linux libMyAppTypes.so und unter Windows MyAppTypes.dll erzeugen.
• <Path> (optional) spezifiziert entweder:
  • einen absoluten Pfad zu dem Verzeichnis, das die Plugin-Datei enthält, oder
  • einen relativen Pfad von dem Verzeichnis, das die Datei qmldir enthält, zu dem Verzeichnis, das die Plugin-Datei enthält.

Standardmäßig sucht die Engine nach der Plugin-Bibliothek in dem Verzeichnis, das die Datei qmldir enthält. (Der Plugin-Suchpfad kann mit QQmlEngine::pluginPathList() abgefragt und mit QQmlEngine::addPluginPath() geändert werden).

In der Datei qmldir können null oder mehr C++-Plugin-Deklarationen vorhanden sein. Da das Laden von Plugins jedoch eine relativ teure Operation ist, wird den Clients empfohlen, höchstens ein einziges Plugin anzugeben.

Beispiel:

plugin MyPluginLibrary

Plugin Classname Deklaration

classname <C++ plugin class>

Gibt den Klassennamen des vom Modul verwendeten C++-Plugins an.

Diese Information wird für alle QML-Module benötigt, die für zusätzliche Funktionalität von einem C++-Plugin abhängen. Qt Quick Anwendungen, die mit statischem Linking erstellt wurden, können die Modulimporte ohne diese Information nicht auflösen.

Deklaration einer Typbeschreibungsdatei

typeinfo <File>

Deklariert eine Typbeschreibungsdatei für das Modul, die von QML-Tools wie Qt Creator gelesen werden kann, um auf Informationen über die von den Plugins des Moduls definierten Typen zuzugreifen. <File> ist der (relative) Dateiname einer .qmltypes Datei.

Beispiel:

typeinfo mymodule.qmltypes

Ohne eine solche Datei können QML-Tools möglicherweise keine Funktionen wie die Code-Vervollständigung für die in Ihren Plugins definierten Typen anbieten.

Deklaration von Modulabhängigkeiten

depends <ModuleIdentifier> <InitialVersion>

Deklariert, dass dieses Modul von einem anderen abhängt.

Beispiel:

depends MyOtherModule 1.0

Diese Deklaration ist nur in Fällen notwendig, in denen die Abhängigkeit versteckt ist: z. B. wenn der C++-Code eines Moduls verwendet wird, um QML (vielleicht bedingt) zu laden, das dann von anderen Modulen abhängt. In solchen Fällen ist die depends Deklaration notwendig, um die anderen Module in Anwendungspakete einzubinden.

Modul-Import-Deklaration

import <ModuleIdentifier> [<Version>]

Deklariert, dass dieses Modul ein anderes importiert.

Beispiel:

import MyOtherModule 1.0

Die Typen des anderen Moduls werden in demselben Typennamensraum verfügbar gemacht, in den dieses Modul importiert wird. Wird die Version weggelassen, wird die letzte verfügbare Version des anderen Moduls importiert. Die Angabe von auto als Version importiert die gleiche Version wie die in der QML-Anweisung import angegebene Version dieses Moduls.

Erklärung zur Designer-Unterstützung

designersupported

Setzen Sie diese Eigenschaft, wenn das Plugin von Qt Quick Designer unterstützt wird. In der Standardeinstellung wird das Plugin nicht unterstützt.

Ein Plugin, das von Qt Quick Designer unterstützt wird, muss ordnungsgemäß getestet werden. Dies bedeutet, dass das Plugin nicht abstürzt, wenn es innerhalb der qml2puppet läuft, die von Qt Quick Designer zur Ausführung von QML verwendet wird. Generell sollte das Plugin im Qt Quick Designer gut funktionieren und keine Show-Stopper verursachen, wie z.B. übermäßig viel Speicher benötigen, die qml2puppet stark verlangsamen oder irgendetwas anderes, das das Plugin im Qt Quick Designer effektiv unbrauchbar macht.

Die Elemente eines nicht unterstützten Plugins werden im Qt Quick Designer nicht gezeichnet, aber sie sind immer noch als leere Boxen verfügbar und die Eigenschaften können bearbeitet werden.

Bevorzugte Pfaddeklaration

prefer <Path>

Diese Eigenschaft weist die QML-Engine an, alle weiteren Dateien für dieses Modul aus <Pfad> und nicht aus dem aktuellen Verzeichnis zu laden. Dies kann verwendet werden, um Dateien zu laden, die mit qmlcachegen kompiliert wurden.

Zum Beispiel können Sie die QML-Dateien eines Moduls als Ressourcen zu einem Ressourcenpfad :/my/path/MyModule/ hinzufügen. Fügen Sie dann prefer :/my/path/MyModule zur qmldir-Datei hinzu, um die Dateien im Ressourcensystem und nicht die im Dateisystem zu verwenden. Wenn Sie dann qmlcachegen für diese Dateien verwenden, stehen die vorkompilierten Dateien allen Clients des Moduls zur Verfügung.

Versionierungs-Semantik

Alle QML-Typen, die für eine bestimmte Hauptversion exportiert werden, sind mit der neuesten Version der gleichen Hauptversion verfügbar. Wenn ein Modul beispielsweise einen Typ MyButton in Version 1.0 und einen Typ MyWindow in Version 1.1 bereitstellt, können Clients, die die Version 1.1 des Moduls importieren, die Typen MyButton und MyWindow verwenden. Umgekehrt gilt dies jedoch nicht: Ein Typ, der für eine bestimmte Unterversion exportiert wurde, kann nicht verwendet werden, wenn eine ältere oder frühere Unterversion importiert wird. Wenn der Kunde im oben genannten Beispiel die Version 1.0 des Moduls importiert hat, kann er nur den Typ MyButton, nicht aber den Typ MyWindow verwenden.

Ein Modul kann mehrere Hauptversionen anbieten, aber die Kunden haben jeweils nur Zugriff auf eine Hauptversion. Wenn Sie beispielsweise MyExampleModule 2.0 importieren, können Sie nur auf diese Hauptversion zugreifen und nicht auf die vorherige Hauptversion. Obwohl Sie die Artefakte, die zu verschiedenen Hauptversionen gehören, unter einem Sigle-Verzeichnis und einer qmldir -Datei organisieren können, wird empfohlen, für jede Hauptversion unterschiedliche Verzeichnisse zu verwenden. Wenn Sie sich für den früheren Ansatz entscheiden (ein Verzeichnis und eine qmldir Datei), versuchen Sie, das Versionssuffix für die Dateinamen zu verwenden. Zum Beispiel können Artefakte, die zu MyExampleModule 2.0 gehören, das Suffix .2 in ihrem Dateinamen verwenden.

Eine Version kann nicht importiert werden, wenn keine Typen explizit für diese Version exportiert wurden. Wenn ein Modul in Version 1.0 einen Typ MyButton und in Version 1.1 einen Typ MyWindow bereitstellt, können Sie Version 1.2 oder Version 2.0 dieses Moduls nicht importieren.

Ein Typ kann von verschiedenen Dateien in verschiedenen Unterversionen definiert werden. In diesem Fall wird beim Import durch Clients die am besten passende Version verwendet. Wenn zum Beispiel ein Modul die folgenden Typen über seine qmldir Datei spezifiziert hat:

module ExampleModule
MyButton 1.0 MyButton.qml
MyButton 1.1 MyButton11.qml
MyButton 1.3 MyButton13.qml
MyRectangle 1.2 MyRectangle12.qml

Ein Client, der die Version 1.2 von ExampleModule importiert, kann die Typdefinition von MyButton verwenden, die von MyButton11.qml bereitgestellt wird, da sie die neueste Version dieses Typs ist, und die Typdefinition von MyRectangle, die von MyRectangle12.qml bereitgestellt wird.

Das Versionssystem stellt sicher, dass eine gegebene QML-Datei unabhängig von der Version der installierten Software funktioniert, da ein versionierter Import nur Typen für diese Version importiert und andere Bezeichner verfügbar lässt, auch wenn die tatsächlich installierte Version diese Bezeichner andernfalls bereitstellen könnte.

Beispiel für eine qmldir-Datei

Es folgt ein Beispiel für eine qmldir Datei:

module ExampleModule
CustomButton 2.0 CustomButton20.qml
CustomButton 2.1 CustomButton21.qml
plugin examplemodule
MathFunctions 2.0 mathfuncs.js

Die obige Datei qmldir definiert ein Modul namens "ExampleModule". Sie definiert den CustomButton QML-Objekttyp in den Versionen 2.0 und 2.1 des Moduls, mit unterschiedlichen Implementierungen für jede Version. Sie spezifiziert ein Plugin, das von der Engine geladen werden muss, wenn das Modul von Clients importiert wird, und dieses Plugin kann verschiedene C++-definierte Typen im QML-Typsystem registrieren. Auf Unix-ähnlichen Systemen versucht die QML-Engine, libexamplemodule.so als QQmlExtensionPlugin zu laden, und unter Windows lädt sie examplemodule.dll als QQmlExtensionPlugin. Schließlich gibt die Datei qmldir eine JavaScript-Ressource an, die nur verfügbar ist, wenn Version 2.0 oder eine neuere Version (unter derselben Hauptversion) des Moduls importiert wird.

Wenn das Modul im QML-Importpfad installiert ist, könnten Clients das Modul auf folgende Weise importieren und verwenden:

import QtQuick 2.0
import ExampleModule 2.1

Rectangle {
    width: 400
    height: 400
    color: "lightsteelblue"

    CustomButton {
        color: "gray"
        text: "Click Me!"
        onClicked: MathFunctions.generateRandom() > 10 ? color = "red" : color = "gray";
    }
}

Der oben verwendete Typ CustomButton würde aus der in der Datei CustomButton21.qml angegebenen Definition stammen, und die durch den Bezeichner MathFunctions identifizierte JavaScript-Ressource würde in der Datei mathfuncs.js definiert werden.

Typbeschreibungsdateien

QML-Module können auf eine oder mehrere Typinformationsdateien in ihrer qmldir Datei verweisen. Diese haben in der Regel die Erweiterung .qmltypes und werden von externen Tools gelesen, um Informationen über die in C++ definierten und typischerweise über Plugins importierten Typen zu erhalten.

Als solche haben qmltypes-Dateien keinen Einfluss auf die Funktionalität eines QML-Moduls. Ihr einziger Nutzen besteht darin, dass Tools wie Qt Creator den Benutzern Ihres Moduls Codevervollständigung, Fehlerprüfung und andere Funktionen zur Verfügung stellen können.

Jedes Modul, das QML-Typen in C++ definiert, sollte auch eine Typbeschreibungsdatei enthalten.

Der beste Weg, eine qmltypes-Datei für Ihr Modul zu erstellen, ist, sie mit dem Build-System und den QML_ELEMENT -Makros zu erzeugen. Wenn Sie die Dokumentation dazu befolgen, sind keine weiteren Maßnahmen erforderlich. qmltyperegistrar wird die .qmltypes Dateien automatisch erzeugen.

Beispiel: Wenn sich Ihr Modul in /tmp/imports/My/Module befindet, sollte neben dem eigentlichen Plugin-Binary eine Datei namens plugins.qmltypes erzeugt werden.

Fügen Sie die Zeile

typeinfo plugins.qmltypes

zu /tmp/imports/My/Module/qmldir hinzu, um es zu registrieren.