QJSEngine Class

Member Function Dokumentation

QJSEngine::QJSEngine()

Konstruiert ein QJSEngine-Objekt.

globalObject() wird so initialisiert, dass es die in ECMA-262, Abschnitt 15.1 beschriebenen Eigenschaften besitzt.

[explicit] QJSEngine::QJSEngine(QObject *parent)

Konstruiert ein QJSEngine-Objekt mit der angegebenen parent.

Die globalObject() wird so initialisiert, dass sie die in ECMA-262, Abschnitt 15.1 beschriebenen Eigenschaften besitzt.

[override virtual noexcept] QJSEngine::~QJSEngine()

Zerstört diese QJSEngine.

Während der Zerstörung von QJSEngine wird kein Speicher aus dem persistenten JS-Heap entfernt. Wenn Sie den gesamten Speicher freigeben müssen, rufen Sie collectGarbage() manuell auf, unmittelbar bevor Sie QJSEngine zerstören.

[since Qt 6.1] QJSValue QJSEngine::catchError()

Wenn gerade eine Ausnahme ansteht, fängt sie diese ab und gibt sie als QJSValue zurück. Andernfalls wird als QJSValue undefiniert zurückgegeben. Nach dem Aufruf dieser Methode hasError() wird false zurückgegeben.

Diese Funktion wurde in Qt 6.1 eingeführt.

template <typename From, typename To> To QJSEngine::coerceValue(const From &from)

Gibt die angegebene from zurück, konvertiert in den Vorlagentyp To. Die Konvertierung erfolgt in JavaScript-Semantik. Diese unterscheiden sich von der Semantik von qvariant_cast. Es gibt eine Reihe von impliziten Konvertierungen zwischen JavaScript-äquivalenten Typen, die von qvariant_cast standardmäßig nicht durchgeführt werden. Diese Methode ist eine Verallgemeinerung aller anderen Konvertierungsmethoden in dieser Klasse.

Siehe auch fromVariant(), qvariant_cast(), fromScriptValue(), und toScriptValue().

void QJSEngine::collectGarbage()

Führt den Garbage Collector aus.

Der Garbage Collector versucht, Speicher zurückzugewinnen, indem er Objekte, die in der Skriptumgebung nicht mehr erreichbar sind, aufspürt und entsorgt.

Normalerweise brauchen Sie diese Funktion nicht aufzurufen; der Garbage Collector wird automatisch aufgerufen, wenn QJSEngine entscheidet, dass dies sinnvoll ist (d. h. wenn eine bestimmte Anzahl neuer Objekte erstellt wurde). Sie können diese Funktion jedoch auch aufrufen, um explizit anzufordern, dass die Garbage Collection so bald wie möglich durchgeführt werden soll.

Siehe auch Garbage Collection und gc().

QJSValue QJSEngine::evaluate(const QString &program, const QString &fileName = QString(), int lineNumber = 1, QStringList *exceptionStackTrace = nullptr)

Wertet program aus, wobei lineNumber als Basiszeilennummer verwendet wird, und gibt das Ergebnis der Auswertung zurück.

Der Skriptcode wird im Kontext des globalen Objekts ausgewertet.

Die Auswertung von program kann eine exception in der Engine auslösen; in diesem Fall ist der Rückgabewert die Ausnahme, die ausgelöst wurde (typischerweise ein Error Objekt; siehe QJSValue::isError()).

lineNumber wird verwendet, um eine Startzeilennummer für program anzugeben; Zeilennummern, die von der Engine gemeldet werden und sich auf diese Auswertung beziehen, basieren auf diesem Argument. Wenn program beispielsweise aus zwei Codezeilen besteht und die Anweisung in der zweiten Zeile eine Skriptausnahme verursacht, ist die Nummer der Ausnahmezeile lineNumber plus eins. Wenn keine Startzeilennummer angegeben wird, werden die Zeilennummern auf 1 basieren.

fileName wird für Fehlerberichte verwendet. In Fehlerobjekten ist zum Beispiel der Dateiname über die Eigenschaft "fileName" zugänglich, wenn er mit dieser Funktion angegeben wird.

exceptionStackTrace wird verwendet, um zu melden, ob eine nicht abgefangene Ausnahme ausgelöst wurde. Wenn Sie dieser Funktion einen Zeiger auf QStringList übergeben, der nicht leer ist, wird er auf eine Liste von "stackframe messages" gesetzt, wenn das Skript eine unbehandelte Ausnahme ausgelöst hat, andernfalls auf eine leere Liste. Eine Stackframe-Meldung hat das Format Funktionsname:Zeilennummer:Spalte:Dateiname

Siehe auch QQmlExpression::evaluate.

template <typename T> T QJSEngine::fromManagedValue(const QJSManagedValue &value)

Gibt die angegebene value zurück, konvertiert in den Vorlagentyp T.

Siehe auch toManagedValue() und coerceValue().

template <typename T> T QJSEngine::fromPrimitiveValue(const QJSPrimitiveValue &value)

Gibt den angegebenen value in den Vorlagentyp T konvertiert zurück.

Da QJSPrimitiveValue nur int, bool, double, QString und die Äquivalente von JavaScript null und undefined enthalten kann, wird der Wert aggressiv gezwungen, wenn Sie einen anderen Typ anfordern.

Siehe auch toPrimitiveValue() und coerceValue().

template <typename T> T QJSEngine::fromScriptValue(const QJSValue &value)

Gibt die angegebene value zurück, konvertiert in den Vorlagentyp T.

Siehe auch toScriptValue() und coerceValue().

template <typename T> T QJSEngine::fromVariant(const QVariant &value)

Gibt die angegebene value zurück, konvertiert in den Vorlagentyp T. Die Konvertierung erfolgt in JavaScript-Semantik. Diese unterscheiden sich von der Semantik von qvariant_cast. Es gibt eine Reihe von impliziten Konvertierungen zwischen JavaScript-äquivalenten Typen, die von qvariant_cast standardmäßig nicht durchgeführt werden.

Siehe auch coerceValue(), fromScriptValue(), und qvariant_cast().

QJSValue QJSEngine::globalObject() const

Gibt das Global Object dieser Engine zurück.

Standardmäßig enthält das Global Object die eingebauten Objekte, die Teil der ECMA-262 sind, wie z. B. Math, Date und String. Zusätzlich können Sie Eigenschaften des Global Objects festlegen, um Ihre eigenen Erweiterungen für den gesamten Skriptcode verfügbar zu machen. Nichtlokale Variablen im Skriptcode werden als Eigenschaften des Globalen Objekts erstellt, ebenso wie lokale Variablen im globalen Code.

[since Qt 6.1] bool QJSEngine::hasError() const

Gibt true zurück, wenn die letzte JavaScript-Ausführung zu einer Ausnahme geführt hat oder wenn throwError() aufgerufen wurde. Andernfalls wird false zurückgegeben. Beachten Sie, dass evaluate() alle im ausgewerteten Code ausgelösten Exceptions abfängt.

Diese Funktion wurde in Qt 6.1 eingeführt.

QJSValue QJSEngine::importModule(const QString &fileName)

Importiert das Modul unter fileName und gibt ein Modul-Namespace-Objekt zurück, das alle exportierten Variablen, Konstanten und Funktionen als Eigenschaften enthält.

Wenn dies das erste Mal ist, dass das Modul in die Engine importiert wird, wird die Datei vom angegebenen Speicherort entweder im lokalen Dateisystem oder im Qt-Ressourcensystem geladen und als ECMAScript-Modul ausgewertet. Es wird erwartet, dass die Datei in UTF-8-Text kodiert ist.

Nachfolgende Importe desselben Moduls geben die zuvor importierte Instanz zurück. Module sind Singletons und bleiben bestehen, bis die Engine zerstört wird.

Die angegebene fileName wird intern mit QFileInfo::canonicalFilePath() normalisiert. Das bedeutet, dass mehrere Importe der gleichen Datei auf der Festplatte unter Verwendung unterschiedlicher relativer Pfade die Datei nur einmal laden.

Siehe auch registerModule().

void QJSEngine::installExtensions(QJSEngine::Extensions extensions, const QJSValue &object = QJSValue())

Installiert JavaScript extensions, um Funktionen hinzuzufügen, die in einer Standard-ECMAScript-Implementierung nicht verfügbar sind.

Die Erweiterungen werden auf dem angegebenen object installiert, oder auf dem Global Object, wenn kein Objekt angegeben wird.

Es können mehrere Erweiterungen auf einmal installiert werden, indem man die OR-Werte der Aufzählung angibt:

installExtensions(QJSEngine::TranslationExtension | QJSEngine::ConsoleExtension);

Siehe auch Extension.

bool QJSEngine::isInterrupted() const

Gibt zurück, ob die JavaScript-Ausführung gerade unterbrochen ist.

Siehe auch setInterrupted().

QJSValue QJSEngine::newArray(uint length = 0)

Erzeugt ein JavaScript-Objekt der Klasse Array mit der angegebenen length.

Siehe auch newObject().

QJSValue QJSEngine::newErrorObject(QJSValue::ErrorType errorType, const QString &message = QString())

Erzeugt ein JavaScript-Objekt der Klasse Error, mit message als Fehlermeldung.

Der Prototyp des erstellten Objekts ist errorType.

Siehe auch newObject(), throwError(), und QJSValue::isError().

QJSValue QJSEngine::newObject()

Erzeugt ein JavaScript-Objekt der Klasse Object.

Der Prototyp des erstellten Objekts ist das Objekt Object prototype.

Siehe auch newArray() und QJSValue::setProperty().

template <typename T> QJSValue QJSEngine::newQMetaObject()

Erzeugt ein JavaScript-Objekt, das das statische QMetaObject umhüllt, das mit der Klasse T verbunden ist.

Siehe auch newQObject() und QObject Integration.

QJSValue QJSEngine::newQMetaObject(const QMetaObject *metaObject)

Erzeugt ein JavaScript-Objekt, das das angegebene QMetaObject umhüllt. metaObject muss die Script-Engine überdauern. Es wird empfohlen, diese Methode nur mit statischen Metaobjekten zu verwenden.

Wenn sie als Konstruktor aufgerufen wird, wird eine neue Instanz der Klasse erstellt. Nur Konstruktoren, die von Q_INVOKABLE offengelegt werden, sind für die Script-Engine sichtbar.

Siehe auch newQObject() und QObject Integration.

QJSValue QJSEngine::newQObject(QObject *object)

Erzeugt ein JavaScript-Objekt, das das angegebene QObject object umhüllt, wobei JavaScriptOwnership verwendet wird.

Signale und Slots, Eigenschaften und Kinder von object sind als Eigenschaften des erstellten QJSValue verfügbar.

Wenn object ein Null-Zeiger ist, gibt diese Funktion einen Null-Wert zurück.

Wenn ein Standardprototyp für die Klasse object(oder ihre Oberklasse, rekursiv) registriert wurde, wird der Prototyp des neuen Skriptobjekts auf diesen Standardprototyp gesetzt.

Wenn das angegebene object außerhalb der Kontrolle der Engine gelöscht wird, führt jeder Versuch, über das JavaScript-Wrapper-Objekt auf die Mitglieder des gelöschten QObject zuzugreifen (entweder durch Skriptcode oder C++), zu einem script exception.

Siehe auch QJSValue::toQObject().

[since 6.2] QJSValue QJSEngine::newSymbol(const QString &name)

Erzeugt ein JavaScript-Objekt der Klasse Symbol mit dem Wert name.

Der Prototyp des erstellten Objekts ist das Symbol-Prototyp-Objekt.

Diese Funktion wurde in Qt 6.2 eingeführt.

Siehe auch newObject().

[static] QJSEngine::ObjectOwnership QJSEngine::objectOwnership(QObject *object)

Gibt den Eigentümer von object zurück.

Siehe auch setObjectOwnership() und QJSEngine::ObjectOwnership.

bool QJSEngine::registerModule(const QString &moduleName, const QJSValue &value)

Registriert QJSValue, um als Modul zu dienen. Nach dem Aufruf dieser Funktion werden alle Module, die moduleName importieren, den Wert von value importieren, anstatt moduleName aus dem Dateisystem zu laden.

Jedes gültige QJSValue kann registriert werden, aber benannte Exporte (z.B. import { name } from "info" ) werden als Mitglieder eines Objekts behandelt, so dass der Standard-Export mit einer der newXYZ-Methoden von QJSEngine erstellt werden muss.

Da auf diese Weise Module importiert werden können, die nicht im Dateisystem vorhanden sind, können Skripting-Anwendungen dies nutzen, um eingebaute Module bereitzustellen, ähnlich wie bei Node.js.

Gibt bei Erfolg true zurück, andernfalls false.

Siehe auch importModule().

void QJSEngine::setInterrupted(bool interrupted)

Unterbricht die JavaScript-Ausführung oder aktiviert sie wieder.

Wenn interrupted gleich true ist, bricht jedes von dieser Engine ausgeführte JavaScript sofort ab und gibt ein Fehlerobjekt zurück, bis diese Funktion erneut mit einem Wert von false für interrupted aufgerufen wird.

Diese Funktion ist thread-sicher. Sie können sie von einem anderen Thread aus aufrufen, um z. B. eine Endlosschleife in JavaScript zu unterbrechen.

Siehe auch isInterrupted().

[static] void QJSEngine::setObjectOwnership(QObject *object, QJSEngine::ObjectOwnership ownership)

Setzt die ownership von object.

Ein Objekt mit JavaScriptOwnership wird nicht in den Müll geworfen, solange es noch ein übergeordnetes Objekt hat, auch wenn es keine Verweise auf dieses Objekt gibt.

Siehe auch objectOwnership() und QJSEngine::ObjectOwnership.

[since Qt 5.12] void QJSEngine::throwError(const QString &message)

Löst einen Laufzeitfehler (Exception) mit dem angegebenen message aus.

Diese Methode ist das C++-Gegenstück eines throw() -Ausdrucks in JavaScript. Sie ermöglicht es C++-Code, Laufzeitfehler an QJSEngine zu melden. Daher sollte sie nur von C++-Code aufgerufen werden, der von einer JavaScript-Funktion über QJSEngine aufgerufen wurde.

Bei der Rückkehr aus C++ unterbricht die Engine den normalen Ausführungsfluss und ruft den nächsten vorregistrierten Exception-Handler mit einem Fehlerobjekt auf, das den angegebenen message enthält. Das Fehlerobjekt verweist auf die Position des obersten Kontexts auf dem JavaScript-Aufrufer-Stack; insbesondere hat es die Eigenschaften lineNumber, fileName und stack. Diese Eigenschaften werden in Script Exceptions beschrieben.

Im folgenden Beispiel wirft eine C++-Methode in FileAccess.cpp einen Fehler in qmlFile.qml an der Stelle, an der readFileAsText() aufgerufen wird:

// qmlFile.qml
function someFunction() {
  ...
  var text = FileAccess.readFileAsText("/path/to/file.txt");
}

// FileAccess.cpp
// Assuming that FileAccess is a QObject-derived class that has been
// registered as a singleton type and provides an invokable method
// readFileAsText()

QJSValue FileAccess::readFileAsText(const QString & filePath) {
  QFile file(filePath);

  if (!file.open(QIODevice::ReadOnly)) {
    jsEngine->throwError(file.errorString());
    return QString();
  }

  ...
  return content;
}

Es ist auch möglich, den ausgelösten Fehler in JavaScript abzufangen:

// qmlFile.qml
function someFunction() {
  ...
  var text;
  try {
    text = FileAccess.readFileAsText("/path/to/file.txt");
  } catch (error) {
    console.warn("In " + error.fileName + ":" + "error.lineNumber" +
                 ": " + error.message);
  }
}

Wenn Sie einen spezifischeren Laufzeitfehler zur Beschreibung einer Ausnahme benötigen, können Sie die Überladung throwError(QJSValue::ErrorType errorType, const QString &message) verwenden.

Diese Funktion wurde in Qt 5.12 eingeführt.

Siehe auch Script Exceptions.

[since 6.1] void QJSEngine::throwError(const QJSValue &error)

Diese Funktion überlastet throwError().

Wirft eine vorkonstruierte Laufzeit error (Ausnahme). Auf diese Weise können Sie newErrorObject() verwenden, um den Fehler zu erstellen und ihn nach Bedarf anzupassen.

Diese Funktion wurde in Qt 6.1 eingeführt.

Siehe auch Script Exceptions und newErrorObject().

[since Qt 5.12] void QJSEngine::throwError(QJSValue::ErrorType errorType, const QString &message = QString())

Diese Funktion überlastet throwError().

Wirft einen Laufzeitfehler (Exception) mit dem angegebenen errorType und message.

// Assuming that DataEntry is a QObject-derived class that has been
// registered as a singleton type and provides an invokable method
// setAge().

void DataEntry::setAge(int age) {
  if (age < 0 || age > 200) {
    jsEngine->throwError(QJSValue::RangeError,
                         "Age must be between 0 and 200");
  }
  ...
}

Diese Funktion wurde in Qt 5.12 eingeführt.

Siehe auch Script Exceptions und newErrorObject().

template <typename T> QJSManagedValue QJSEngine::toManagedValue(const T &value)

Erzeugt eine QJSManagedValue mit der angegebenen value.

Siehe auch fromManagedValue() und coerceValue().

template <typename T> QJSPrimitiveValue QJSEngine::toPrimitiveValue(const T &value)

Erzeugt eine QJSPrimitiveValue mit dem angegebenen value.

Da QJSPrimitiveValue nur int, bool, double, QString und die Äquivalente von JavaScript null und undefined enthalten kann, wird der Wert aggressiv erzwungen, wenn Sie einen anderen Typ übergeben.

Siehe auch fromPrimitiveValue() und coerceValue().

template <typename T> QJSValue QJSEngine::toScriptValue(const T &value)

Erzeugt eine QJSValue mit der angegebenen value.

Siehe auch fromScriptValue() und coerceValue().