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 der Speicherort relativ zum Speicherort des QML-Dokuments oder der JavaScript-Ressource ermittelt, die den Import enthält. Ist die Skriptdatei nicht zugänglich, tritt ein Fehler auf. Muss das JavaScript von einer Netzwerkressource abgerufen werden, wird der Status „ 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, was im Folgenden 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

Beispiel:

import "jsfile.js" as Logic

Importierte JavaScript-Ressourcen werden immer mit dem Schlüsselwort „as“ qualifiziert. Der Qualifizierer für JavaScript-Ressourcen muss mit einem Großbuchstaben beginnen und eindeutig sein, sodass stets eine Eins-zu-Eins-Zuordnung zwischen Qualifizierern und JavaScript-Dateien besteht. (Dies bedeutet auch, dass Qualifizierer nicht denselben Namen wie integrierte JavaScript-Objekte wie „ Date “ und „ Math “ tragen dürfen.)

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

Importe innerhalb von JavaScript-Ressourcen

In „ QtQuick 2.0 “ wurde eine Funktion hinzugefügt, die es JavaScript-Ressourcen ermöglicht, andere JavaScript-Ressourcen sowie QML-Typ-Namespaces mithilfe einer Abwandlung der Standard-QML-Import-Syntax zu importieren (wobei alle zuvor beschriebenen Regeln und Einschränkungen gelten).

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

• Ein Skript mit Importanweisungen erbt die Importe nicht von dem QML-Dokument, das es importiert hat (der Zugriff auf `Component.errorString` schlägt beispielsweise fehl).
• Ein Skript ohne Importanweisungen erbt die Importe aus dem QML-Dokument, das es importiert hat (der Zugriff auf `Component.errorString` ist beispielsweise erfolgreich).
• Ein gemeinsam genutztes Skript (definiert als `.pragma library`) erbt die Importe aus QML-Dokumenten nicht, selbst wenn das Skript 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 Abwärtskompatibilität beibehalten. Die dritte Semantik bleibt gegenüber der aktuellen Semantik für gemeinsam genutzte Skripte unverändert, wird hier jedoch 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 folgende Weise importieren:

import * as MathFunctions from "factorial.mjs";

Oder:

.import "filename.js" as Qualifier

Ersteres ist die Standard-ECMAScript-Syntax zum Importieren von ECMAScript-Modulen und funktioniert nur innerhalb von ECMAScript-Modulen, die durch die Dateiendung „ mjs “ gekennzeichnet sind. Letzteres ist eine von der „ QML “-Engine bereitgestellte Erweiterung für JavaScript und funktioniert auch mit Nicht-Modulen. Da es sich um eine vom ECMAScript-Standard abgelöste Erweiterung handelt, wird von ihrer Verwendung abgeraten.

Wird eine JavaScript-Datei auf diese Weise importiert, erfolgt der Import mit einem Qualifizierer. Auf die Funktionen in dieser Datei kann dann vom importierenden Skript aus über den Qualifizierer zugegriffen werden (d. h. als ` Qualifier.functionName(params)`).

Manchmal ist es wünschenswert, dass die Funktionen im Importkontext verfügbar sind, ohne dass sie mit einem Qualifizierer versehen werden müssen. In diesem Fall sollten ECMAScript-Module und die JavaScript-Anweisung ` import ` ohne den Qualifizierer ` as ` verwendet werden.

Beispielsweise ruft der unten links stehende QML-Code ` showCalculations() ` in ` script.mjs` auf, das wiederum ` factorial() ` in ` factorial.mjs` aufrufen kann, da es ` factorial.mjs ` mithilfe von ` 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 aus der anderen Datei im Namensraum der aktuellen Datei verfügbar, ignoriert jedoch 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. Es wird in einer zukünftigen Version von Qt entfernt.

Importieren eines QML-Moduls aus einer JavaScript-Ressource

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

.import TypeNamespace MajorVersion.MinorVersion as Qualifier

Nachfolgend finden Sie ein Beispiel, das auch zeigt, wie die QML-Typen aus einem in JavaScript importierten Modul verwendet werden können:

.import Qt.test 1.0 as JsQtTest

var importedEnumValue = JsQtTest.MyQmlObject.EnumValue3

Dies kann insbesondere nützlich sein, um auf Funktionen zuzugreifen, die über einen Singleton-Typ bereitgestellt werden; weitere Informationen finden Sie unter QML_SINGLETON.

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 diese als zustandslose Bibliothek deklariert ist (mit „ .pragma library “) oder eine explizite „ .import “-Anweisung enthält.