Import-Anweisungen

Syntax einer Import-Anweisung

Mit einer Import-Anweisung können Clients der Engine mitteilen, welche Module, JavaScript-Ressourcen und Komponentenverzeichnisse in einem QML-Dokument verwendet werden. Die Typen, die in einem Dokument verwendet werden können, hängen davon ab, welche Module, Ressourcen und Verzeichnisse vom Dokument importiert werden.

Es gibt drei verschiedene Arten von Importen. Jeder Importtyp hat eine leicht abweichende Syntax, und für verschiedene Importtypen gelten unterschiedliche Semantiken.

Modul-Importe (Namensraum-Importe)

Die häufigste Art des Imports ist der Modulimport. Clients können QML-Module importieren, die QML-Objekttypen und JavaScript-Ressourcen in einem bestimmten Namespace registrieren.

Die allgemeine Form eines Modulimports ist wie folgt:

import <ModuleIdentifier> [<Version.Number>] [as <Qualifier>]

• <ModuleIdentifier> ist ein in punktierter URI-Notation angegebener Bezeichner, der den vom Modul bereitgestellten Typ-Namensraum eindeutig identifiziert.
• <Version.Number> ist eine Version der Form MajorVersion.MinorVersion, die angibt, welche Definitionen verschiedener Objekttypen und JavaScript-Ressourcen durch den Import zur Verfügung gestellt werden. Es kann weggelassen werden, in diesem Fall wird die letzte Version des Moduls importiert. Es ist auch möglich, nur die Minor-Version wegzulassen. Dann wird die letzte Minor-Version der angegebenen Major-Version importiert.
• <Qualifier> ist ein optionaler lokaler Namespace-Bezeichner, in den die vom Modul bereitgestellten Objekttypen und JavaScript-Ressourcen installiert werden, falls angegeben. Wird er weggelassen, werden die vom Modul bereitgestellten Objekttypen und JavaScript-Ressourcen in den globalen Namespace installiert.

Ein Beispiel für einen unqualifizierten Modulimport lautet wie folgt:

import QtQuick

Dieser Import ermöglicht die Verwendung aller vom Modul QtQuick bereitgestellten Typen, ohne dass ein Qualifier angegeben werden muss. Der Client-Code zur Erstellung eines Rechtecks sieht beispielsweise wie folgt aus:

import QtQuick

Rectangle {
    width: 200
    height: 100
    color: "red"
}

Ein Beispiel für einen unqualifizierten Import mit Version wäre

import QtQuick 2.10

In diesem Fall wären alle Typen, die in QtQuick 2.11 und höher oder in einer höheren Hauptversion, wie 6.0, definiert sind, für die Datei nicht verfügbar.

Ein Beispiel für einen qualifizierten Modulimport lautet wie folgt:

import QtQuick as Quick

Da jedoch jeder Verwendung eines Typs, der von einem Modul bereitgestellt wird, das in einen qualifizierten Namensraum importiert wurde, der Qualifier vorangestellt werden muss, kann der Konflikt von der QML-Engine eindeutig gelöst werden.

Ein Beispiel für Client-Code, der ein Rechteck erzeugt, nachdem ein qualifizierter Modulimport verwendet wurde, lautet wie folgt:

import QtQuick as Quick

Quick.Rectangle {
    width: 200
    height: 100
    color: "red"
}

Weitere Informationen über qualifizierte Importe finden Sie im nächsten Abschnitt über den Import in einen qualifizierten lokalen Namespace.

Beachten Sie, dass ein Fehler auftritt, wenn ein QML-Dokument ein Modul, das einen bestimmten QML-Objekttyp bereitstellt, nicht importiert, aber dennoch versucht, diesen Objekttyp zu verwenden. Das folgende QML-Dokument importiert zum Beispiel nicht QtQuick, so dass der Versuch, den Typ Rectangle zu verwenden, fehlschlägt:

Rectangle {
    width: 200
    height: 100
    color: "red"
}

In diesem Fall gibt die Engine einen Fehler aus und weigert sich, die Datei zu laden.

C++-Modul-Importe

Normalerweise werden C++-Typen mit den Makros QML_ELEMENT und QML_NAMED_ELEMENT() deklariert und über das Build-System mit QML_IMPORT_NAME und QML_IMPORT_MAJOR_VERSION registriert. Der auf diese Weise angegebene Importname und die Version bilden ein Modul, das für den Zugriff auf die Typen importiert werden kann.

Dies ist vor allem in Client-Anwendungen üblich, die ihre eigenen QML-Objekttypen in C++ definieren.

Importieren in einen qualifizierten lokalen Namespace

Die Anweisung import kann optional das Schlüsselwort as verwenden, um anzugeben, dass die Typen in einen bestimmten dokumentenlokalen Namensraum importiert werden sollen. Wenn ein Namespace angegeben wird, müssen alle Verweise auf die Typen, die durch den Import verfügbar gemacht werden, mit dem lokalen Namespace-Qualifizierer versehen werden.

Im Folgenden wird das Modul QtQuick in den Namespace "CoreItems" importiert. Nun muss allen Verweisen auf Typen aus dem Modul QtQuick der Name CoreItems vorangestellt werden:

import QtQuick as CoreItems

CoreItems.Rectangle {
    width: 100; height: 100

    CoreItems.Text { text: "Hello, world!" }

    // WRONG! No namespace prefix - the Text type won't be found
    Text { text: "Hello, world!" }
}

Ein Namespace dient als Bezeichner für ein Modul innerhalb des Geltungsbereichs der Datei. Der Namespace wird nicht zu einem Attribut des Stammobjekts, auf das von außen verwiesen werden kann, wie dies bei Eigenschaften, Signalen und Methoden der Fall ist.

Der Namespaced-Import ist nützlich, wenn zwei QML-Typen verwendet werden sollen, die denselben Namen haben, aber in verschiedenen Modulen liegen. In diesem Fall können die beiden Module in verschiedene Namespaces importiert werden, um sicherzustellen, dass sich der Code auf den richtigen Typ bezieht:

import QtQuick as CoreItems
import "../textwidgets" as MyModule

CoreItems.Rectangle {
    width: 100; height: 100

    MyModule.Text { text: "Hello from my custom text item!" }
    CoreItems.Text { text: "Hello from Qt Quick!" }
}

Beachten Sie, dass mehrere Module in denselben Namespace importiert werden können, genauso wie mehrere Module in den globalen Namespace importiert werden können. Zum Beispiel:

import QtQuick as Project
import QtMultimedia as Project

Project.Rectangle {
    width: 100; height: 50

    Project.Audio {
        source: "music.wav"
        autoPlay: true
    }
}

Verzeichnis-Importe

Ein Verzeichnis, das QML-Dokumente enthält, kann auch direkt in ein QML-Dokument importiert werden. Auf diese Weise können QML-Typen auf einfache Weise in wiederverwendbare Gruppierungen unterteilt werden: Verzeichnisse im Dateisystem.

Die generische Form eines Verzeichnisimports sieht wie folgt aus:

import "<DirectoryPath>" [as <Qualifier>]

Für Verzeichnisimporte gilt eine ähnliche Semantik für die <Qualifier> wie für Modulimporte; weitere Informationen zu diesem Thema finden Sie im vorherigen Abschnitt über den Import in einen qualifizierten lokalen Namensraum.

Weitere Informationen zu Verzeichnisimporten finden Sie in der ausführlichen Dokumentation zu Verzeichnisimporten.

JavaScript-Ressourcen-Importe

JavaScript-Ressourcen können direkt in ein QML-Dokument importiert werden. Jede JavaScript-Ressource muss einen Bezeichner haben, über den auf sie zugegriffen werden kann.

Die generische Form eines JavaScript-Ressourcen-Imports sieht wie folgt aus:

import "<JavaScriptFile>" as <Identifier>

Beachten Sie, dass der <Identifier> innerhalb eines QML-Dokuments eindeutig sein muss, im Gegensatz zum lokalen Namespace-Qualifier, der auf Modul-Importe angewendet werden kann.

JavaScript-Ressourcen von Modulen

Javascript-Dateien können von Modulen zur Verfügung gestellt werden, indem Bezeichnerdefinitionen zur qmldir Datei hinzugefügt werden, die das Modul spezifiziert.

Wenn zum Beispiel das Modul projects.MyQMLProject.MyFunctions mit der folgenden Datei qmldir angegeben und in den QML-Importpfad installiert wird:

module projects.MyQMLProject.MyFunctions
SystemFunctions 1.0 SystemFunctions.js
UserFunctions 1.0 UserFunctions.js

kann eine Client-Anwendung die im Modul deklarierten JavaScript-Ressourcen importieren, indem sie das Modul importiert und den mit einer deklarierten Ressource verbundenen Bezeichner verwendet:

import QtQuick
import projects.MyQMLProject.MyFunctions

Item {
    Component.onCompleted: { SystemFunctions.cleanUp(); }
}

Wenn das Modul in einen dokumentenlokalen Namespace importiert wurde, muss den JavaScript-Ressourcenbezeichnern der Namespace-Qualifier vorangestellt werden, damit sie verwendet werden können:

import QtQuick
import projects.MyQMLProject.MyFunctions as MyFuncs
import org.example.Functions as TheirFuncs

Item {
    Component.onCompleted: {
        MyFuncs.SystemFunctions.cleanUp();
        TheirFuncs.SystemFunctions.shutdown();
    }
}

Weitere Informationen

Weitere Informationen über JavaScript-Ressourcen finden Sie in der Dokumentation über die Definition von JavaScript-Ressourcen in QML, und weitere Informationen über den Import von JavaScript-Ressourcen und die Verwendung von Importen innerhalb von JavaScript-Ressourcen finden Sie in der ausführlichen Dokumentation über den Import von JavaScript-Ressourcen in QML.

QML-Importpfad

Wenn ein identifiziertes Modul importiert wird, durchsucht die QML-Engine den Importpfad nach einem passenden Modul.

Dieser Importpfad, der von QQmlEngine::importPathList() zurückgegeben wird, definiert die Standardspeicherorte, die von der Engine durchsucht werden. Standardmäßig enthält diese Liste:

• Das Verzeichnis der aktuellen Datei
• Das Verzeichnis, das durch QLibraryInfo::QmlImportsPath
• Pfade, die durch die Umgebungsvariable QML_IMPORT_PATH angegeben werden
• Der Pfad qrc:/qt-project.org/imports innerhalb der Ressourcen.
• Den qrc:/qt/qml-Pfad innerhalb der Ressourcen (seit Qt 6.5).

Zusätzliche Importpfade können über QQmlEngine::addImportPath() oder die Umgebungsvariable QML_IMPORT_PATH hinzugefügt werden. Wenn Sie das qml-Werkzeug ausführen, können Sie auch die Option -I verwenden, um einen Importpfad hinzuzufügen.

Sie können mehrere Importpfade in der Umgebungsvariablen QML_IMPORT_PATH angeben, indem Sie sie mit dem Pfadseparator verbinden. Unter Windows ist das Pfad-Trennzeichen ein Semikolon (;), auf anderen Plattformen ist es ein Doppelpunkt (:). Dies bedeutet, dass Sie keine Ressourcenpfade oder URLs in QML_IMPORT_PATH angeben können, da diese selbst Doppelpunkte enthalten. Sie können jedoch Ressourcenpfade und URLs hinzufügen, indem Sie QQmlEngine::addImportPath() programmatisch aufrufen.

Fehlersuche

Die Umgebungsvariable QML_IMPORT_TRACE kann für die Fehlersuche nützlich sein, wenn es Probleme beim Finden und Laden von Modulen gibt. Siehe Debugging von Modulimporten für weitere Informationen.