Importieren von JavaScript-Ressourcen in QML

JavaScript-Ressourcen können von QML-Dokumenten und anderen JavaScript-Ressourcen importiert werden. JavaScript-Ressourcen können entweder über relative oder absolute URLs importiert werden. Im Falle einer relativen URL wird die Position relativ zur Position des QML-Dokuments oder der JavaScript-Ressource, die den Import enthält, aufgelöst. Wenn die Skriptdatei nicht zugänglich ist, tritt ein Fehler auf. Wenn das JavaScript von einer Netzwerkressource abgerufen werden muss, wird die status der Komponente auf "Loading" gesetzt, bis das Skript heruntergeladen wurde.

JavaScript-Ressourcen können auch QML-Module und andere JavaScript-Ressourcen importieren. Die Syntax einer Import-Anweisung innerhalb einer JavaScript-Ressource unterscheidet sich geringfügig von der einer Import-Anweisung innerhalb eines QML-Dokuments, die weiter unten ausführlich dokumentiert wird.

Importieren einer JavaScript-Ressource aus einem QML-Dokument

Ein QML-Dokument kann eine JavaScript-Ressource mit der folgenden Syntax importieren:

import "ResourceURL" as Qualifier

Zum Beispiel:

import "jsfile.js" as Logic

Importierte JavaScript-Ressourcen werden immer mit dem Schlüsselwort "as" bezeichnet. Der Qualifier für JavaScript-Ressourcen muss mit einem Großbuchstaben beginnen und eindeutig sein, so dass es immer eine Eins-zu-Eins-Zuordnung zwischen Qualifiern und JavaScript-Dateien gibt. (Das bedeutet auch, dass Qualifier nicht denselben Namen tragen dürfen wie integrierte JavaScript-Objekte wie Date und Math).

Die in einer importierten JavaScript-Datei definierten Funktionen stehen den im importierenden QML-Dokument definierten Objekten über die "Qualifier.functionName(params)" -Syntax zur Verfügung. Funktionen in JavaScript-Ressourcen können Parameter annehmen, deren Typen beliebige QML-Wertetypen oder Objekttypen sowie normale JavaScript-Typen sein können. Die normalen Datentypkonvertierungsregeln gelten für Parameter und Rückgabewerte beim Aufruf solcher Funktionen aus QML.

Importe innerhalb von JavaScript-Ressourcen

In QtQuick 2.0 wurde Unterstützung hinzugefügt, um JavaScript-Ressourcen den Import anderer JavaScript-Ressourcen und auch QML-Typ-Namensräume zu ermöglichen, wobei eine Variation der standardmäßigen QML-Import-Syntax verwendet wird (für die alle zuvor beschriebenen Regeln und Qualifikationen gelten).

Da eine JavaScript-Ressource ein anderes Skript oder QML-Modul auf diese Weise in QtQuick 2.0 importieren kann, werden einige zusätzliche Semantiken definiert:

• ein Skript mit Importen erbt nicht die Importe des QML-Dokuments, das es importiert hat (so schlägt z. B. der Zugriff auf Component.errorString fehl)
• ein Skript ohne Importe erbt die Importe des QML-Dokuments, das es importiert hat (der Zugriff auf Component.errorString schlägt also z. B. fehl)
• ein gemeinsam genutztes Skript (d. h. als .pragma-Bibliothek definiert) erbt keine Importe von einem QML-Dokument, selbst wenn es keine anderen Skripte oder Module importiert

Die erste Semantik ist konzeptionell korrekt, da ein bestimmtes Skript von einer beliebigen Anzahl von QML-Dateien importiert werden kann. Die zweite Semantik wird aus Gründen der Rückwärtskompatibilität beibehalten. Die dritte Semantik bleibt gegenüber der aktuellen Semantik für gemeinsam genutzte Skripte unverändert, wird aber hier im Hinblick auf den neu möglichen Fall (in dem das Skript andere Skripte oder Module importiert) präzisiert.

Importieren einer JavaScript-Ressource aus einer anderen JavaScript-Ressource

Eine JavaScript-Ressource kann eine andere auf die folgende Weise importieren:

import * as MathFunctions from "factorial.mjs";

Oder:

.import "filename.js" as Qualifier

Ersteres ist die standardmäßige ECMAScript-Syntax für den Import von ECMAScript-Modulen und funktioniert nur innerhalb von ECMAScript-Modulen, die durch die Dateierweiterung mjs gekennzeichnet sind. Letzteres ist eine Erweiterung von JavaScript, die von der QML Engine bereitgestellt wird und auch mit Nicht-Modulen funktioniert. Da es sich um eine Erweiterung handelt, die durch den ECMAScript-Standard überholt ist, wird von ihrer Verwendung abgeraten.

Wenn eine JavaScript-Datei auf diese Weise importiert wird, wird sie mit einem Qualifier importiert. Die Funktionen in dieser Datei sind dann vom importierenden Skript aus über den Qualifier zugänglich (d. h. als Qualifier.functionName(params)).

Manchmal ist es wünschenswert, dass die Funktionen im Importkontext zur Verfügung stehen, ohne dass sie qualifiziert werden müssen. In diesem Fall sollten ECMAScript-Module und die JavaScript-Anweisung import ohne den Qualifizierer as verwendet werden.

Zum Beispiel ruft der QML-Code unten links showCalculations() in script.mjs auf, das wiederum factorial() in factorial.mjs aufrufen kann, da es factorial.mjs über import eingebunden hat.

import QtQuick
import "script.mjs" as MyScript

Item {
    width: 100; height: 100

    MouseArea {
        anchors.fill: parent
        onClicked: {
            MyScript.showCalculations(10)
            console.log("Call factorial() from QML:",
                MyScript.factorial(10))
        }
    }
}

// script.mjs
import { factorial } from "factorial.mjs"
export { factorial }

export function showCalculations(value) {
    console.log(
        "Call factorial() from script.js:",
        factorial(value));
}

// factorial.mjs
export function factorial(a) {
    a = parseInt(a);
    if (a <= 0)
        return 1;
    else
        return a * factorial(a - 1);
}

Die Funktion Qt.include() bindet eine JavaScript-Datei aus einer anderen ein, ohne ECMAScript-Module zu verwenden und ohne den Import zu qualifizieren. Sie macht alle Funktionen und Variablen der anderen Datei im Namensraum der aktuellen Datei verfügbar, ignoriert aber alle in dieser Datei definierten Pragmas und Importe. Dies ist keine gute Idee, da ein Funktionsaufruf niemals den Kontext des Aufrufers verändern sollte.

Qt.include() ist veraltet und sollte vermieden werden. Sie wird in einer zukünftigen Version von Qt entfernt werden.

Importieren eines QML-Moduls aus einer JavaScript-Ressource

Eine JavaScript-Ressource kann ein QML-Modul auf die folgende Weise importieren:

.import TypeNamespace MajorVersion.MinorVersion as Qualifier

Unten sehen Sie ein Beispiel, das auch zeigt, wie man die QML-Typen aus einem in JavaScript importierten Modul verwendet:

.import Qt.test 1.0 as JsQtTest

var importedEnumValue = JsQtTest.MyQmlObject.EnumValue3

Insbesondere kann dies nützlich sein, um auf Funktionen zuzugreifen, die über einen Singleton-Typ zur Verfügung gestellt werden; siehe QML_SINGLETON für weitere Informationen.

Ihre JavaScript-Ressource kann standardmäßig auf alle Importe der Komponente zugreifen, die die Ressource importiert. Sie hat keinen Zugriff auf die Importe der Komponente, wenn sie als zustandslose Bibliothek deklariert ist (mit .pragma library) oder eine explizite .import -Anweisung enthält.