QJSEngine Class

Dokumentation der Member-Funktionen

QJSEngine::QJSEngine()

Erstellt ein QJSEngine-Objekt.

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

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

Erstellt ein QJSEngine-Objekt mit dem angegebenen „ parent “.

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

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

Löscht diesen „ QJSEngine “.

Beim Löschen von „ QJSEngine “ wird der persistente JS-Heap nicht von Garbage Collection bereinigt. Wenn der gesamte Speicher freigegeben werden soll, rufen Sie „ collectGarbage()“ manuell unmittelbar vor dem Löschen von „ QJSEngine “ auf.

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

Wenn derzeit eine Ausnahme aussteht, wird diese abgefangen und als ` QJSValue` zurückgegeben. Andernfalls wird „undefiniert“ als ` QJSValue` zurückgegeben. Nach dem Aufruf dieser Methode gibt ` hasError()` ` false` zurück.

Diese Funktion wurde in Qt 6.1 eingeführt.

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

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

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

void QJSEngine::collectGarbage()

Führt den Garbage Collector aus.

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

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

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 Basiszahl verwendet wird, und gibt das Ergebnis der Auswertung zurück.

Der Skriptcode wird im Kontext des globalen Objekts ausgewertet.

Die Auswertung von ` program ` kann in der Engine zu einer ` exception ` führen; in diesem Fall ist der Rückgabewert die ausgelöste Ausnahme (in der Regel ein ` Error `-Objekt; siehe ` QJSValue::isError()`).

lineNumber wird verwendet, um eine Startzeilennummer für ` program` anzugeben; die von der Engine gemeldeten Zeilennummernangaben, die sich auf diese Auswertung beziehen, basieren auf diesem Argument. Wenn beispielsweise „ program “ aus zwei Codezeilen besteht und die Anweisung in der zweiten Zeile eine Skript-Ausnahme auslöst, wäre die Zeilennummer der Ausnahme „ lineNumber “ plus eins. Wenn keine Startzeilennummer angegeben wird, beginnen die Zeilennummern bei 1.

fileName wird für die Fehlerberichterstattung verwendet. In Fehlerobjekten ist der Dateiname beispielsweise über die Eigenschaft „fileName“ zugänglich, sofern er dieser Funktion übergeben wurde.

exceptionStackTrace wird verwendet, um zu melden, ob eine nicht abgefangene Ausnahme ausgelöst wurde. Wenn Sie einen nicht-null-Zeiger auf einen „ QStringList “ an die Funktion übergeben, wird dieser auf eine Liste von „Stackframe-Meldungen“ gesetzt, falls 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 das angegebene ` value ` zurück, das in den Vorlagentyp ` T` konvertiert wurde.

Siehe auch toManagedValue() und coerceValue().

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

Gibt die angegebene „ value “-Variable zurück, die in den Vorlagentyp „ T “ konvertiert wurde.

Da ` QJSPrimitiveValue ` nur Werte vom Typ `int`, `bool`, `double`, ` QString` sowie die Entsprechungen der JavaScript-Typen ` null ` und ` undefined` enthalten kann, wird der Wert aggressiv umgewandelt, wenn Sie einen anderen Typ anfordern.

Siehe auch toPrimitiveValue() und coerceValue().

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

Gibt das angegebene ` value ` zurück, das in den Vorlagentyp ` T` konvertiert wurde.

Siehe auch toScriptValue() und coerceValue().

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

Gibt das angegebene ` value ` zurück, das in den Vorlagentyp ` T` konvertiert wurde. Die Konvertierung erfolgt gemäß der JavaScript-Semantik. Diese unterscheidet sich von der Semantik von ` qvariant_cast`. Es gibt eine Reihe impliziter 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 globale Objekt dieser Engine zurück.

Standardmäßig enthält das globale Objekt die in ECMA-262 integrierten Objekte wie „Math“, „Date“ und „String“. Darüber hinaus können Sie Eigenschaften des globalen Objekts festlegen, um Ihre eigenen Erweiterungen für den gesamten Skriptcode verfügbar zu machen. Nicht-lokale Variablen im Skriptcode werden als Eigenschaften des globalen Objekts angelegt, 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 Ausnahmen 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 das Modul zum ersten Mal 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. Die Datei sollte im UTF-8-Textformat kodiert sein.

Bei nachfolgenden Importen desselben Moduls wird die zuvor importierte Instanz zurückgegeben. Module sind Singletons und bleiben so lange bestehen, bis die Engine zerstört wird.

Der angegebene „ fileName “ wird intern mithilfe von „ QFileInfo::canonicalFilePath()“ normalisiert. Das bedeutet, dass mehrere Importe derselben Datei auf der Festplatte über unterschiedliche relative Pfade dazu führen, dass die Datei nur einmal geladen wird.

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, falls kein Objekt angegeben ist, auf dem ` Global Object `.

Es können mehrere Erweiterungen gleichzeitig installiert werden, indem die Enum-Werte als „ OR “ angegeben werden:

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

Siehe auch ` Extension`.

bool QJSEngine::isInterrupted() const

Gibt zurück, ob die Ausführung von JavaScript derzeit unterbrochen ist.

Siehe auch ` setInterrupted()`.

QJSValue QJSEngine::newArray(uint length = 0)

Erstellt ein JavaScript-Objekt der Klasse „Array“ mit dem angegebenen Array length.

Siehe auch ` newObject()`.

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

Erstellt ein JavaScript-Objekt der Klasse „Error“ mit der Fehlermeldung „ message “.

Der Prototyp des erstellten Objekts lautet „ errorType “.

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

QJSValue QJSEngine::newObject()

Erstellt ein JavaScript-Objekt der Klasse „Object“.

Der Prototyp des erstellten Objekts ist das Prototyp-Objekt „Object“.

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

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

Erstellt ein JavaScript-Objekt, das die statische Methode „ QMetaObject “ umschließt, die der Klasse „ T “ zugeordnet ist.

Siehe auch „ newQObject()“ und „ QObject Integration “.

QJSValue QJSEngine::newQMetaObject(const QMetaObject *metaObject)

Erstellt ein JavaScript-Objekt, das das angegebene „ QMetaObject “ umschließt. Das „ metaObject “ muss länger bestehen bleiben als die Skript-Engine. Es wird empfohlen, diese Methode nur mit statischen Metaobjekten zu verwenden.

Wird die Methode als Konstruktor aufgerufen, wird eine neue Instanz der Klasse erstellt. Nur die von ` Q_INVOKABLE ` bereitgestellten Konstruktoren sind von der Skript-Engine aus sichtbar.

Siehe auch newQObject() und QObject Integration.

QJSValue QJSEngine::newQObject(QObject *object)

Erstellt ein JavaScript-Objekt, das das angegebene „ QObject “ object mithilfe von „ JavaScriptOwnership “ umschließt.

Signale und Slots, Eigenschaften und untergeordnete Elemente von ` object ` stehen als Eigenschaften des erstellten ` QJSValue` zur Verfügung.

Ist ` object ` ein Null-Zeiger, gibt diese Funktion einen Nullwert zurück. Dasselbe gilt, wenn ` object ` zum Löschen vorgesehen ist oder wenn sein Destruktor bereits ausgeführt wird.

Wenn für die Klasse von ` object` (oder deren Oberklasse, rekursiv) ein Standardprototyp registriert wurde, wird der Prototyp des neuen Skript-Objekts auf diesen Standardprototyp gesetzt.

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

Siehe auch ` QJSValue::toQObject()`.

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

Erstellt ein JavaScript-Objekt der Klasse „Symbol“ mit dem Wert „ name “.

Der Prototyp des erstellten Objekts ist das Symbol-Prototypobjekt.

Diese Funktion wurde in Qt 6.2 eingeführt.

Siehe auch ` newObject()`.

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

Gibt die Eigentumsrechte an „ object “ zurück.

Siehe auch „ setObjectOwnership()“ und „ QJSEngine::ObjectOwnership “.

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

Registriert eine ` QJSValue ` als Modul. Nach dem Aufruf dieser Funktion importieren alle Module, die ` moduleName ` importieren, den Wert von ` value `, 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 Elemente eines Objekts behandelt, sodass der Standardexport mit einer der `newXYZ`-Methoden von ` QJSEngine` erstellt werden muss.

Da dadurch Module importiert werden können, die im Dateisystem nicht vorhanden sind, können Skriptanwendungen dies nutzen, um integrierte Module bereitzustellen, ähnlich wie bei Node.js.

Gibt bei Erfolg ` true ` zurück, andernfalls ` false `.

// C++ setup
QJSValue container = engine.newObject();
container.setProperty("instance", engine.newQObject(&myDynamicObject));
engine.registerModule("api.mjs", container);

// JavaScript usage
import {instance as Api} from "api.mjs"

// ...

console.log(Api.dynamicProperty)

Siehe auch importModule().

void QJSEngine::setInterrupted(bool interrupted)

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

Wenn „ interrupted “ auf „ true “ gesetzt ist, wird jedes von dieser Engine ausgeführte JavaScript sofort abgebrochen und ein Fehlerobjekt zurückgegeben, bis diese Funktion erneut mit dem Wert „ false “ für „ interrupted “ aufgerufen wird.

Diese Funktion ist threadsicher. Sie können sie aus einem anderen Thread aufrufen, um beispielsweise eine Endlosschleife in JavaScript zu unterbrechen.

Siehe auch ` isInterrupted()`.

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

Setzt die Eigenschaft „ ownership “ von „ object “.

Ein Objekt mit „ JavaScriptOwnership “ wird nicht von der Garbage Collection entfernt, solange es noch einen übergeordneten Eintrag hat, selbst wenn keine Verweise darauf vorhanden sind.

Siehe auch „ objectOwnership()“ und „ QJSEngine::ObjectOwnership “.

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

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

Diese Methode ist das C++-Äquivalent zu einem ` throw() `-Ausdruck in JavaScript. Sie ermöglicht es C++-Code, Laufzeitfehler an ` QJSEngine` zu melden. Daher sollte sie nur aus 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 vorab registrierten Ausnahmebehandler mit einem Fehlerobjekt auf, das den angegebenen ` message` enthält. Das Fehlerobjekt verweist auf die Position des obersten Kontexts im JavaScript-Aufrufstapel; konkret verfügt es über die Eigenschaften ` lineNumber`, ` fileName ` und ` stack`. Diese Eigenschaften sind unter Script Exceptions beschrieben.

Im folgenden Beispiel löst eine C++-Methode in „FileAccess.cpp“ einen Fehler in „qmlFile.qml“ an der Stelle aus, 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 benötigen, um eine Ausnahme zu beschreiben, können Sie die Überladung von ` 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)

Löst eine vorgefertigte Laufzeit- error (Ausnahme) aus. Auf diese Weise können Sie mit ` newErrorObject()` den Fehler erzeugen und ihn nach Bedarf anpassen.

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())

Löst einen Laufzeitfehler (Ausnahme) mit den angegebenen Werten für ` errorType ` und ` message` aus.

// 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)

Erstellt eine „ QJSManagedValue “ mit dem angegebenen „ value “.

Siehe auch „ fromManagedValue()“ und „ coerceValue()“.

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

Erstellt ein „ QJSPrimitiveValue “-Objekt mit dem angegebenen „ value “.

Da ` QJSPrimitiveValue ` nur die Typen `int`, `bool`, `double`, ` QString` sowie die Entsprechungen der JavaScript-Typen ` null ` und ` undefined` enthalten kann, wird der Wert aggressiv umgewandelt, wenn Sie einen anderen Typ übergeben.

Siehe auch fromPrimitiveValue() und coerceValue().

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

Erstellt eine „ QJSValue “ mit dem angegebenen „ value “.

Siehe auch fromScriptValue() und coerceValue().