Import-Anweisungen

Syntax einer Import-Anweisung

Mit einer Importanweisung können Clients der Engine mitteilen, welche Module, JavaScript-Ressourcen und Komponentenverzeichnisse in einem QML-Dokument verwendet werden. Welche Typen innerhalb eines Dokuments verwendet werden können, hängt davon ab, welche Module, Ressourcen und Verzeichnisse von dem Dokument importiert werden.

Es gibt drei verschiedene Arten von Importen. Jede Importart hat eine leicht unterschiedliche Syntax, und für die verschiedenen Importarten gelten unterschiedliche Semantiken.

Modul- (Namespace-)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 lautet wie folgt:

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

• Der „ <ModuleIdentifier> “ ist ein Bezeichner in der Punkt-URI-Notation, der den vom Modul bereitgestellten Typ-Namespace eindeutig identifiziert.
• Der „ <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. Er kann weggelassen werden; in diesem Fall wird die neueste Version des Moduls importiert. Es ist auch möglich, nur die Nebenversion wegzulassen. Dann wird die neueste Nebenversion der angegebenen Hauptversion importiert.
• Der <Qualifier> ist ein optionaler lokaler Namensraumbezeichner, in den die vom Modul bereitgestellten Objekttypen und JavaScript-Ressourcen installiert werden, sofern er angegeben wird. Wird er weggelassen, werden die vom Modul bereitgestellten Objekttypen und JavaScript-Ressourcen im globalen Namensraum 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 Qualifizierer angegeben werden muss. Der Client-Code zum Erstellen eines Rechtecks sieht beispielsweise wie folgt aus:

import QtQuick

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

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

import QtQuick 2.10

In diesem Fall stünden der Datei keine Typen zur Verfügung, die in „ Qt Quick “ 2.11 und höher oder in einer höheren Hauptversion, wie z. B. 6.0, definiert sind.

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

import QtQuick as Quick

Dieser Import ermöglicht es, mehrere Module, die konfliktbehaftete Typnamen bereitstellen, gleichzeitig zu importieren. Da jedoch jeder Verwendung eines Typs, der von einem in einen qualifizierten Namensraum importierten Modul bereitgestellt wird, der Qualifizierer vorangestellt werden muss, kann der Konflikt von der QML-Engine eindeutig aufgelöst werden.

Ein Beispiel für Client-Code, der nach Verwendung eines qualifizierten Modulimports ein Rechteck erstellt, lautet wie folgt:

import QtQuick as Quick

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

Weitere Informationen zu qualifizierten Importen finden Sie im folgenden Abschnitt „Importieren in einen qualifizierten lokalen Namensraum“.

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

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

In diesem Fall gibt die Engine eine Fehlermeldung aus und weigert sich, die Datei zu laden.

C++-Modulimporte

In der Regel werden C++-Typen mithilfe der 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 importiert werden kann, um auf die Typen zuzugreifen.

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

Import in einen qualifizierten lokalen Namensraum

Die Anweisung „ import “ kann optional das Schlüsselwort „ as “ verwenden, um anzugeben, dass die Typen in einen bestimmten dokumentlokalen Namensraum importiert werden sollen. Wenn ein Namensraum angegeben wird, müssen alle Verweise auf die durch den Import bereitgestellten Typen mit dem lokalen Namensraumqualifizierer vorangestellt werden.

Im folgenden Beispiel wird das Modul „ QtQuick “ in den Namensraum „CoreItems“ importiert. Nun müssen alle Verweise auf Typen aus dem Modul „ QtQuick “ mit dem Namen „ 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 Namensraum dient als Bezeichner für ein Modul innerhalb des Geltungsbereichs der Datei. Der Namensraum wird nicht zu einem Attribut des Wurzelobjekts, auf das extern verwiesen werden kann, wie dies bei Eigenschaften, Signalen und Methoden der Fall ist.

Der Import mit Namespace ist nützlich, wenn zwei QML-Typen verwendet werden müssen, die denselben Namen haben, sich aber in unterschiedlichen Modulen befinden. In diesem Fall können die beiden Module in unterschiedliche Namespaces importiert werden, um sicherzustellen, dass der Code auf den richtigen Typ verweist:

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 Namensraum importiert werden können, genauso wie mehrere Module in den globalen Namensraum 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
    }
}

Verzeichnisimporte

Ein Verzeichnis, das QML-Dokumente enthält, kann auch direkt in ein QML-Dokument importiert werden. Dies bietet eine einfache Möglichkeit, QML-Typen in wiederverwendbare Gruppierungen zu unterteilen: Verzeichnisse im Dateisystem.

Die allgemeine Form eines Verzeichnisimports lautet wie folgt:

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

Für die Datei „ <Qualifier> “ gelten bei Verzeichnisimporten ähnliche Regeln wie bei Modulimporten; 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.

Import von JavaScript-Ressourcen

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

Die allgemeine Form eines JavaScript-Ressourcenimports lautet wie folgt:

import "<JavaScriptFile>" as <Identifier>

Beachten Sie, dass der „ <Identifier> “ innerhalb eines QML-Dokuments eindeutig sein muss, im Gegensatz zum Qualifizierer für den lokalen Namensraum, der bei Modulimporten verwendet werden kann.

JavaScript-Ressourcen aus Modulen

JavaScript-Dateien können von Modulen bereitgestellt werden, indem Identifikator-Definitionen zur Datei „ qmldir “ hinzugefügt werden, die das Modul spezifiziert.

Wenn beispielsweise das Modul „ projects.MyQMLProject.MyFunctions “ mit der folgenden Datei „ qmldir “ definiert und im QML-Importpfad installiert ist:

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 verknüpften Bezeichner verwendet:

import QtQuick
import projects.MyQMLProject.MyFunctions

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

Wurde das Modul in einen dokumentlokalen Namensraum importiert, muss den JavaScript-Ressourcenbezeichnern der Namensraumqualifizierer 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 zu JavaScript-Ressourcen finden Sie in der Dokumentation zum Definieren von JavaScript-Ressourcen in QML. Weitere Informationen zum Importieren von JavaScript-Ressourcen und zur Verwendung von Importen innerhalb von JavaScript-Ressourcen finden Sie in der ausführlichen Dokumentation zum Importieren von JavaScript-Ressourcen in QML.

QML-Importpfad

Wenn ein identifiziertes Modul importiert wird, durchsucht die Qml-Engine den Importpfad nach einem passenden Modul, um QML-Dateien und QML-Modul-Plugins zu laden. Qt geht davon aus, dass alle Dateien im Importpfad aus einer vertrauenswürdigen Quelle stammen.

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

• Plattformspezifische Bundle-Pfade, falls vorhanden (z. B. unter macOS oder Android)
• Das Verzeichnis der Anwendungsbinärdatei
• Den Pfad `qrc:/qt-project.org/imports` innerhalb der Ressourcen.
• Den Pfad „qrc:/qt/Qml“ innerhalb der Ressourcen (seit Qt 6.5).
• Durch die Umgebungsvariable „ QML2_IMPORT_PATH “ angegebene Pfade (veraltet)
• Durch die Umgebungsvariable „ QML_IMPORT_PATH “ angegebene Pfade
• Der durch QLibraryInfo::QmlImportsPath

Wenn das Attribut „ Qt::AA_PluginApplication “ für „ QCoreApplication “ gesetzt ist, werden das Anwendungsverzeichnis, alle durch Umgebungsvariablen angegebenen Pfade sowie alle plattformspezifischen Bundle-Pfade außerhalb des Ressourcen-Dateisystems standardmäßig weggelassen.

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

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

Fehlerbehebung

Die Umgebungsvariable „ QML_IMPORT_TRACE “ kann beim Debuggen hilfreich sein, wenn Probleme beim Auffinden und Laden von Modulen auftreten. Weitere Informationen finden Sie unter „Debuggen von Modulimporten “.