JavaScript-Host-Umgebung

QML bietet eine JavaScript-Host-Umgebung, die auf das Schreiben von QML-Anwendungen zugeschnitten ist. Diese Umgebung unterscheidet sich von der Host-Umgebung, die von einem Browser oder einer serverseitigen JavaScript-Umgebung wie Node.js bereitgestellt wird. So bietet QML beispielsweise kein window -Objekt oder DOM API, wie es in einer Browserumgebung üblich ist.

Gemeinsame Basis

Wie ein Browser oder eine serverseitige JavaScript-Umgebung implementiert die QML-Laufzeitumgebung den Standard ECMAScript Language Specification. Dies ermöglicht den Zugriff auf alle vom Standard definierten eingebauten Typen und Funktionen, wie Object, Array und Math. Die QML Runtime implementiert die 7. Ausgabe des Standards.

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

Die Standard-ECMAScript-Build-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-Skript-Referenzen und -Tutorials, wie z. B. der W3Schools JavaScript-Referenz (Abschnitt JavaScript Objects Reference). Viele Websites konzentrieren sich auf JavaScript im Browser, so dass Sie in einigen Fällen die Spezifikation überprüfen müssen, um festzustellen, ob eine bestimmte Funktion oder ein bestimmtes Objekt Teil des ECMAScript-Standards oder spezifisch für die Browserumgebung ist. Im Fall des obigen W3Schools-Links deckt der Abschnitt JavaScript Objects Reference im Allgemeinen den Standard ab, während die Abschnitte Browser Objects Reference und HTML DOM Objects Reference browserspezifisch sind (und daher nicht für QML gelten).

Typ-Annotationen und Assertions

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

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

Typ-Annotationen helfen Tools wie Qt Creator und qmllint, den Code zu verstehen und bessere Diagnosen zu stellen. Außerdem machen sie die Verwendung von Funktionen in C++ einfacher. Siehe Interaktion mit QML-Objekten von C++ aus für weitere Informationen.

Type Assertions (manchmal auch as-casts genannt) können auch verwendet werden, um ein Objekt auf einen anderen Objekttyp zu casten. Wenn das Objekt tatsächlich vom angegebenen Typ ist, gibt die Typbehauptung das gleiche Objekt zurück. Wenn nicht, gibt sie null zurück. Im folgenden Ausschnitt stellen wir fest, dass das Objekt parent ein Rectangle ist, bevor wir auf ein bestimmtes Element des Objekts zugreifen.

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

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

Seit Qt 6.7 werden Typ-Annotationen beim Aufruf von Funktionen immer erzwungen. Werte werden bei Bedarf in die erforderlichen Typen umgewandelt. Zuvor wurden Typ-Annotationen vom Interpreter und dem JIT-Compiler ignoriert, aber von qmlcachegen und qmlsc beim Kompilieren nach C++ erzwungen. Dies konnte in einigen Eckfällen zu unterschiedlichem Verhalten 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

QML Globales Objekt

Die QML-JavaScript-Host-Umgebung implementiert eine Reihe von Host-Objekten und -Funktionen, die in der QML-Global-Object-Dokumentation beschrieben sind.

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

JavaScript-Objekte und -Funktionen

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

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

• Dem Prototyp String wurde eine Funktion arg() hinzugefügt.
• Die Prototypen Date und Number werden um Funktionen zur lokalisierten Konvertierung erweitert.

Darüber hinaus erweitert QML auch das Verhalten der instanceof-Funktion, um eine Typüberprüfung gegen QML-Typen zu ermöglichen. Dies bedeutet, dass Sie die Funktion verwenden können, um zu überprüfen, ob eine Variable tatsächlich dem erwarteten Typ entspricht:

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

...

JavaScript-Umgebungseinschränkungen

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

• JavaScript-Code, der in einer .qml -Datei geschrieben ist, kann das globale Objekt nicht verändern. JavaScript-Code in einer .js-Datei kann das globale Objekt ändern, und diese Änderungen werden in der .qml-Datei sichtbar, wenn sie importiert wird.

  In QML ist das globale Objekt konstant - bestehende Eigenschaften können nicht geändert oder gelöscht werden, und es können keine neuen Eigenschaften erstellt 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 Scope-Kette existiert, ist der folgende Code in QML illegal:

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

  Er kann trivialerweise in diesen legalen Code geändert werden.

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

  Jeder Versuch, das globale Objekt - entweder implizit oder explizit - zu verändern, führt zu einer Ausnahme. Wird diese nicht abgefangen, so wird eine Warnung ausgegeben, die die Datei- und Zeilennummer des betreffenden Codes enthält.

• Globaler Code wird in einem reduzierten Bereich ausgeführt.

  Wenn eine QML-Datei beim Start eine externe JavaScript-Datei mit "globalem" Code enthält, wird dieser in einem Bereich 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, die er normalerweise hätte.

  Globaler Code, der nur auf lokale Skriptvariablen 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. Um Code auszuführen, nachdem die Einrichtung der Umgebung abgeschlossen ist, siehe JavaScript im Code für den Anwendungsstart.

• 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 deklarierten QML-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. 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)
      }
  }