JavaScript-Hostumgebung

QML bietet eine JavaScript-Hostumgebung, die speziell auf die Entwicklung von QML-Anwendungen zugeschnitten ist. Diese Umgebung unterscheidet sich von der Hostumgebung eines Browsers oder einer serverseitigen JavaScript-Umgebung wie Node.js. Beispielsweise stellt QML kein ` window `-Objekt oder ` DOM API ` zur Verfügung, wie sie üblicherweise in einer Browserumgebung zu finden sind.

Gemeinsame Grundlage

Wie eine Browser- oder serverseitige JavaScript-Umgebung implementiert auch die QML Runtime den Standard der ECMAScript-Sprachspezifikation. Dies ermöglicht den Zugriff auf alle im Standard definierten integrierten Typen und Funktionen, wie z. B. `Object`, `Array` und `Math`. Die QML Runtime implementiert die 7. Auflage des Standards.

Nullish Coalescing (??) (seit Qt 5.15) und Optional Chaining (?.) (seit Qt 6.2) sind ebenfalls in der QML Runtime implementiert.

Zudem werden seit Qt 6.8 numerische Literaltrennzeichen (die Unterstriche in 1_000_000) unterstützt.

Die standardmäßigen ECMAScript-Built-ins sind in der QML-Dokumentation nicht explizit dokumentiert. Weitere Informationen zu ihrer Verwendung finden Sie im ECMA-262-Standard, 7. Auflage, oder auf einer der vielen Online-Referenz- und Tutorial-Seiten zu JavaScript, wie beispielsweise der W3Schools-JavaScript-Referenz (Abschnitt „JavaScript Objects Reference“). Viele Seiten konzentrieren sich auf JavaScript im Browser; daher müssen Sie in manchen Fällen die Spezifikation noch einmal überprüfen, um festzustellen, ob eine bestimmte Funktion oder ein bestimmtes Objekt Teil des ECMAScript-Standards ist oder spezifisch für die Browserumgebung gilt. Im Falle des oben genannten W3Schools-Links behandelt der Abschnitt „ JavaScript Objects Reference “ im Allgemeinen den Standard, während die Abschnitte „ Browser Objects Reference “ und „ HTML DOM Objects Reference “ browserspezifisch sind (und daher nicht auf QML anwendbar sind).

Typangaben und Assertions

Funktionsdeklarationen in QML-Dokumenten können und sollten Typ-Annotationen enthalten. Typ-Annotationen werden an die Deklaration der Argumente sowie an die Funktion selbst angehängt, um den Rückgabetyp zu kennzeichnen. Die folgende Funktion nimmt die Parameter „ int “ und „ string “ entgegen und gibt einen „ QtObject “ zurück:

function doThings(a: int, b: string) : QtObject { ... }

Typangaben helfen Tools wie Qt Creator und qmllint dabei, den Code zu verstehen und bessere Diagnosen zu liefern. Zudem erleichtern sie die Verwendung von Funktionen aus C++ heraus. Weitere Informationen finden Sie unter „Interaktion mit QML-Objekten aus C++ “.

Eine Ausnahme von dieser Regel bilden Funktionen, die Signal-Handlern zugewiesen werden: Dort sind Typangaben verboten, um eine mögliche Diskrepanz mit den Typen des Signals zu vermeiden. Dies verursacht keine Probleme für die Tools, da das Signal bereits die erforderlichen Informationen bereitstellt.

Typüberprüfungen (manchmal auch als „as-casts“ bezeichnet) können ebenfalls verwendet werden, um ein Objekt in einen anderen Objekttyp umzuwandeln. Ist das Objekt tatsächlich vom angegebenen Typ, gibt die Typüberprüfung dasselbe Objekt zurück. Ist dies nicht der Fall, wird „ null “ zurückgegeben. Im folgenden Codeausschnitt überprüfen wir, ob das Objekt „ parent “ ein „ Rectangle “ ist, bevor wir auf ein bestimmtes Mitglied davon zugreifen.

Item {
    property color parentColor: (parent as Rectangle)?.color || "red"
}

Die optionale Verkettung (?.) verhindert, dass eine Ausnahme ausgelöst wird, falls das übergeordnete Objekt tatsächlich kein Rechteck ist. In diesem Fall wird „red“ als „ parentColor “ ausgewählt.

Seit Qt 6.7 werden Typangaben beim Aufruf von Funktionen stets durchgesetzt. Werte werden bei Bedarf in die erforderlichen Typen umgewandelt. Zuvor wurden Typangaben vom Interpreter und vom JIT-Compiler ignoriert, bei der Kompilierung nach C++ jedoch von qmlcachegen und qmlsc erzwungen. Dies konnte in einigen Randfällen zu Verhaltensunterschieden führen. Um das alte Verhalten des Interpreters und des JIT explizit anzufordern, können Sie Folgendes zu Ihrem QML-Dokument hinzufügen:

pragma FunctionSignatureBehavior: Ignored

Globales QML-Objekt

Die QML-JavaScript-Hostumgebung implementiert eine Reihe von Host-Objekten und -Funktionen, wie in der Dokumentation zu QML-Globalobjekten beschrieben.

Diese Host-Objekte und -Funktionen sind immer verfügbar, unabhängig davon, ob Module importiert wurden.

JavaScript-Objekte und -Funktionen

Eine Liste der von der QML-Engine unterstützten JavaScript-Objekte, -Funktionen und -Eigenschaften finden Sie in der Liste der JavaScript-Objekte und -Funktionen.

Beachten Sie, dass QML die folgenden Änderungen an nativen Objekten vornimmt:

• Dem Prototyp „ String “ wird eine „ arg() “-Funktion hinzugefügt.
• Den Prototypen „Date“ und „Number“ werden lokalisierungsfähige Konvertierungsfunktionen hinzugefügt.

Siehe auch:

• Number – Das JavaScript-Objekt „Number“
• Date – Das JavaScript-Objekt „Date“
• XMLHttpRequest – Das JavaScript-Objekt „XMLHttpRequest“

Darüber hinaus erweitert QML das Verhalten der „instanceof“-Funktion, um eine Typüberprüfung anhand von QML-Typen zu ermöglichen. Das bedeutet, dass Sie damit überprüfen können, ob eine Variable tatsächlich den erwarteten Typ aufweist, zum Beispiel:

var v = something();
if (!v instanceof Item) {
    throw new TypeError("I need an Item type!");
}

...

Einschränkungen der JavaScript-Umgebung

QML wendet die folgenden Einschränkungen für JavaScript-Code an:

• JavaScript-Code, der in einer „ .qml “-Datei geschrieben ist, kann das globale Objekt nicht ändern. JavaScript-Code in einer „.js“-Datei kann das globale Objekt ändern, und diese Änderungen sind für die „.qml“-Datei beim Import sichtbar.

  In QML ist das globale Objekt konstant – vorhandene Eigenschaften können weder geändert noch gelöscht werden, und es dürfen keine neuen Eigenschaften angelegt werden.

  Die meisten JavaScript-Programme ändern das globale Objekt nicht absichtlich. Die automatische Erstellung nicht deklarierter Variablen durch JavaScript stellt jedoch eine implizite Änderung des globalen Objekts dar und ist in QML verboten.

  Unter der Annahme, dass die Variable ` a ` nicht in der Geltungsbereichskette existiert, ist der folgende Code in QML unzulässig:

  // Illegal modification of undeclared variable
  a = 1;
  for (var ii = 1; ii < 10; ++ii)
      a = a * ii;
  console.log("Result: " + a);

  Er lässt sich auf einfache Weise zu diesem zulässigen Code umschreiben.

  var a = 1;
  for (var ii = 1; ii < 10; ++ii)
      a = a * ii;
  console.log("Result: " + a);

  Jeder Versuch, das globale Objekt zu ändern – sei es implizit oder explizit – löst eine Ausnahme aus. Wird diese nicht abgefangen, wird eine Warnung ausgegeben, die den Dateinamen und die Zeilennummer des fehlerhaften Codes enthält.

• Globaler Code wird in einem eingeschränkten Gültigkeitsbereich ausgeführt.

  Wenn eine QML-Datei beim Start eine externe JavaScript-Datei mit „globalem“ Code einbindet, wird dieser in einem Geltungsbereich ausgeführt, der nur die externe Datei selbst und das globale Objekt enthält. Das heißt, er hat keinen Zugriff auf die QML-Objekte und -Eigenschaften, auf die er normalerweise Zugriff hätte.

  Globaler Code, der ausschließlich auf skriptlokale Variablen zugreift, ist zulässig. Dies ist ein Beispiel für gültigen globalen Code.

  var colors = [ "red", "blue", "green", "orange", "purple" ];

  Globaler Code, der auf QML-Objekte zugreift, wird nicht korrekt ausgeführt.

  // Invalid global code - the "rootObject" variable is undefined
  var initialPosition = { rootObject.x, rootObject.y }

  Diese Einschränkung besteht, da die QML-Umgebung noch nicht vollständig eingerichtet ist. Informationen zur Ausführung von Code nach Abschluss der Umgebungseinrichtung finden Sie unter „JavaScript im Startcode der Anwendung“.

• Der Wert von „ this “ ist in QML in den meisten Kontexten undefiniert.

  Das Schlüsselwort „ this “ wird beim Binden von Eigenschaften aus JavaScript unterstützt. In QML-Bindungsausdrücken, QML-Signal-Handlern und in QML deklarierten Funktionen bezieht sich „ this “ auf das Scope-Objekt. In allen anderen Situationen ist der Wert von „ this “ in QML undefiniert.

  Um auf ein bestimmtes Objekt zu verweisen, geben Sie „ id “ an. Zum Beispiel:

  Item {
      width: 200; height: 100
      function mouseAreaClicked(area) {
          console.log("Clicked in area at: " + area.x + ", " + area.y);
      }
      // This will pass area to the function
      MouseArea {
          id: area
          y: 50; height: 50; width: 200
          onClicked: mouseAreaClicked(area)
      }
  }