QJSEngine Class

Documentation des fonctions membres

QJSEngine::QJSEngine()

Crée un objet QJSEngine.

L'globalObject() est initialisé pour disposer des propriétés décrites dans la norme ECMA-262, section 15.1.

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

Crée un objet QJSEngine avec l'parent fournie.

L'globalObject() est initialisé de manière à posséder les propriétés décrites dans la section 15.1 de la norme ECMA-262.

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

Détruit cette QJSEngine.

Le ramasse-miettes ne récupère pas les objets du tas JS persistant lors de la destruction de l'QJSEngine. Si vous souhaitez libérer toute la mémoire, appelez manuellement la fonction collectGarbage() juste avant de détruire l'QJSEngine.

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

Si une exception est actuellement en attente, cette méthode la capture et la renvoie sous la forme d'un objet ` QJSValue`. Sinon, elle renvoie la valeur indéfinie ` QJSValue`. Après l'appel de cette méthode, ` hasError()` renvoie ` false`.

Cette fonction a été introduite dans Qt 6.1.

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

Renvoie l'from donné converti vers le type de modèle To. La conversion s'effectue selon la sémantique JavaScript. Celle-ci diffère de la sémantique de qvariant_cast. Il existe un certain nombre de conversions implicites entre des types équivalents en JavaScript qui ne sont pas effectuées par défaut par qvariant_cast. Cette méthode est une généralisation de toutes les autres méthodes de conversion de cette classe.

Voir également fromVariant(), qvariant_cast(), fromScriptValue() et toScriptValue().

void QJSEngine::collectGarbage()

Lance le ramasse-miettes.

Le ramasse-miettes tentera de libérer de la mémoire en localisant et en supprimant les objets qui ne sont plus accessibles dans l’environnement du script.

Normalement, vous n’avez pas besoin d’appeler cette fonction ; le ramasse-miettes sera automatiquement invoqué lorsque l’ QJSEngine ur décidera qu’il est judicieux de le faire (c’est-à-dire lorsqu’un certain nombre de nouveaux objets auront été créés). Cependant, vous pouvez appeler cette fonction pour demander explicitement que le ramasse-miettes soit exécuté dès que possible.

Voir également «Garbage Collection » et « gc() ».

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

Évalue ` program`, en utilisant ` lineNumber ` comme nombre de référence, et renvoie le résultat de l'évaluation.

Le code du script sera évalué dans le contexte de l'objet global.

L’évaluation de ` program ` peut provoquer une exception ` exception ` dans le moteur ; dans ce cas, la valeur renvoyée sera l’exception levée (généralement un objet ` Error ` ; voir ` QJSValue::isError()`).

lineNumber est utilisé pour spécifier un numéro de ligne de départ pour program; les informations relatives au numéro de ligne fournies par le moteur concernant cette évaluation seront basées sur cet argument. Par exemple, si program se compose de deux lignes de code et que l’instruction de la deuxième ligne provoque une exception de script, le numéro de ligne de l’exception correspondra à lineNumber plus un. Lorsqu’aucun numéro de ligne de départ n’est spécifié, la numérotation des lignes commence à 1.

fileName est utilisé pour le rapport d’erreurs. Par exemple, dans les objets d’erreur, le nom du fichier est accessible via la propriété « fileName » s’il est fourni à cette fonction.

exceptionStackTrace est utilisée pour signaler si une exception non gérée a été levée. Si vous lui transmettez un pointeur non nul vers une instance de ` QStringList `, elle le remplira avec une liste de « messages de cadre de pile » si le script a levé une exception non gérée, ou avec une liste vide dans le cas contraire. Un message de cadre de pile a le format suivant : nom de la fonction : numéro de ligne : colonne : nom de fichier

Voir également QQmlExpression::evaluate.

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

Renvoie l'value donné converti en type de modèle T.

Voir également ` toManagedValue()` et ` coerceValue()`.

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

Renvoie l'value donné converti en type de modèle T.

Étant donné que ` QJSPrimitiveValue ` ne peut contenir que des valeurs de type `int`, `bool`, `double`, ` QString`, ainsi que les équivalents JavaScript de ` null ` et ` undefined`, la valeur sera convertie de manière agressive si vous demandez un autre type.

Voir également toPrimitiveValue() et coerceValue().

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

Renvoie l'value donné converti en type de modèle T.

Voir également toScriptValue() et coerceValue().

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

Renvoie l'value donné converti au type de modèle T. La conversion est effectuée selon la sémantique JavaScript. Celle-ci diffère de la sémantique de qvariant_cast. Il existe un certain nombre de conversions implicites entre des types équivalents en JavaScript qui ne sont pas effectuées par défaut par qvariant_cast.

Voir également coerceValue(), fromScriptValue() et qvariant_cast().

QJSValue QJSEngine::globalObject() const

Renvoie l'objet global de ce moteur.

Par défaut, l’objet global contient les objets intégrés faisant partie de la norme ECMA-262, tels que Math, Date et String. De plus, vous pouvez définir des propriétés de l’objet global afin de rendre vos propres extensions accessibles à l’ensemble du code de script. Les variables non locales du code de script seront créées en tant que propriétés de l'objet global, tout comme les variables locales du code global.

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

Renvoie ` true ` si la dernière exécution JavaScript a généré une exception ou si la fonction ` throwError()` a été appelée. Dans le cas contraire, renvoie ` false`. Notez que la fonction ` evaluate()` intercepte toutes les exceptions levées dans le code évalué.

Cette fonction a été introduite dans Qt 6.1.

QJSValue QJSEngine::importModule(const QString &fileName)

Importe le module situé à l'adresse fileName et renvoie un objet d'espace de noms de module contenant toutes les variables, constantes et fonctions exportées en tant que propriétés.

Si c'est la première fois que le module est importé dans le moteur, le fichier est chargé à partir de l'emplacement spécifié, soit dans le système de fichiers local, soit dans le système de ressources Qt, puis évalué en tant que module ECMAScript. Le fichier doit être encodé en texte UTF-8.

Les importations suivantes du même module renverront l’instance précédemment importée. Les modules sont des singletons et persistent jusqu’à la destruction du moteur.

L'fileName e spécifié sera normalisé en interne à l'aide de la fonction ` QFileInfo::canonicalFilePath()`. Cela signifie que plusieurs importations du même fichier sur le disque, utilisant des chemins relatifs différents, ne chargeront le fichier qu'une seule fois.

Voir également registerModule().

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

Installe des extensions JavaScript extensions afin d'ajouter des fonctionnalités qui ne sont pas disponibles dans une implémentation standard d'ECMAScript.

Les extensions sont installées sur l'object spécifié, ou sur l'Global Object si aucun objet n'est spécifié.

Plusieurs extensions peuvent être installées simultanément en utilisant la méthode ` OR` avec les valeurs de l'énumération :

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

Voir également ` Extension`.

bool QJSEngine::isInterrupted() const

Indique si l'exécution de JavaScript est actuellement interrompue.

Voir également setInterrupted().

QJSValue QJSEngine::newArray(uint length = 0)

Crée un objet JavaScript de classe `Array` à partir de l'length` fournie.

Voir aussi newObject().

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

Crée un objet JavaScript de classe « Error », avec « message » comme message d'erreur.

Le prototype de l'objet créé sera errorType.

Voir également newObject(), throwError() et QJSValue::isError().

QJSValue QJSEngine::newObject()

Crée un objet JavaScript de la classe `Object`.

Le prototype de l'objet créé sera l'objet prototype Object.

Voir également newArray() et QJSValue::setProperty().

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

Crée un objet JavaScript qui encapsule la méthode statique ` QMetaObject ` associée à la classe ` T`.

Voir également newQObject() et QObject Integration.

QJSValue QJSEngine::newQMetaObject(const QMetaObject *metaObject)

Crée un objet JavaScript qui encapsule l'QMetaObject fournie. L'metaObject doit survivre au moteur de script. Il est recommandé de n'utiliser cette méthode qu'avec des méta-objets statiques.

Lorsqu’elle est appelée en tant que constructeur, une nouvelle instance de la classe est créée. Seuls les constructeurs exposés par ` Q_INVOKABLE ` seront visibles depuis le moteur de script.

Voir également newQObject() et QObject Integration.

QJSValue QJSEngine::newQObject(QObject *object)

Crée un objet JavaScript qui encapsule l'QObject object fourni, en utilisant JavaScriptOwnership.

Les signaux et slots, ainsi que les propriétés et les éléments enfants de ` object ` sont disponibles en tant que propriétés de l'objet ` QJSValue` créé.

Si ` object ` est un pointeur nul, cette fonction renvoie une valeur nulle. Il en va de même si ` object ` a été marqué pour suppression ou si son destructeur est déjà en cours d’exécution.

Si un prototype par défaut a été enregistré pour la classe de l’ object(ou sa superclasse, de manière récursive), le prototype du nouvel objet script sera défini comme étant ce prototype par défaut.

Si l’ object donné est supprimé hors du contrôle du moteur, toute tentative d’accès aux membres de l’ QObject supprimé via l’objet wrapper JavaScript (que ce soit par du code de script ou en C++) entraînera une exception « script exception ».

Voir également QJSValue::toQObject().

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

Crée un objet JavaScript de classe Symbol, dont la valeur est « name ».

Le prototype de l'objet créé sera l'objet prototype Symbol.

Cette fonction a été introduite dans Qt 6.2.

Voir aussi newObject().

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

Renvoie le propriétaire de object.

Voir également setObjectOwnership() et QJSEngine::ObjectOwnership.

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

Enregistre une QJSValue pour qu’elle serve de module. Une fois cette fonction appelée, tous les modules qui importent moduleName importeront la valeur de value au lieu de charger moduleName depuis le système de fichiers.

Toute QJSValue valide peut être enregistrée, mais les exportations nommées (par exemple import { name } from "info") sont traitées comme des membres d'un objet ; l'exportation par défaut doit donc être créée à l'aide de l'une des méthodes newXYZ de QJSEngine.

Comme cela permet d’importer des modules qui n’existent pas sur le système de fichiers, les applications de script peuvent s’en servir pour fournir des modules intégrés, à l’instar de Node.js.

Renvoie ` true ` en cas de succès, ` false ` dans le cas contraire.

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

Voir également importModule().

void QJSEngine::setInterrupted(bool interrupted)

Interrompt ou réactive l'exécution de JavaScript.

Si interrupted est défini sur true, tout code JavaScript exécuté par ce moteur est immédiatement interrompu et renvoie un objet d'erreur jusqu'à ce que cette fonction soit à nouveau appelée avec une valeur de false pour interrupted.

Cette fonction est sûre pour les threads. Vous pouvez l’appeler depuis un autre thread afin d’interrompre, par exemple, une boucle infinie en JavaScript.

Voir également isInterrupted().

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

Définit l'ownership de object.

Un objet doté de l'JavaScriptOwnership n'est pas récupéré par le ramasse-miettes tant qu'il possède encore un parent, même s'il n'y a aucune référence vers lui.

Voir également ` objectOwnership()` et ` QJSEngine::ObjectOwnership`.

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

Génère une erreur d'exécution (exception) avec l'message spécifiée.

Cette méthode est l’équivalent en C++ d’une expression ` throw() ` en JavaScript. Elle permet au code C++ de signaler des erreurs d’exécution à ` QJSEngine`. Elle ne doit donc être appelée qu’à partir de code C++ qui a été invoqué par une fonction JavaScript via ` QJSEngine`.

Lors du retour depuis le C++, le moteur interrompt le flux d’exécution normal et appelle le gestionnaire d’exceptions préenregistré suivant avec un objet d’erreur contenant l’ message donné. L’objet d’erreur pointe vers l’emplacement du contexte le plus haut dans la pile d’appel JavaScript ; plus précisément, il possède les propriétés lineNumber, fileName et stack. Ces propriétés sont décrites dans Script Exceptions.

Dans l’exemple suivant, une méthode C++ dans FileAccess.cpp lève une erreur dans qmlFile.qml à l’endroit où readFileAsText() est appelé :

// 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;
}

Il est également possible d’intercepter l’erreur levée en JavaScript :

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

Si vous avez besoin d’une erreur d’exécution plus spécifique pour décrire une exception, vous pouvez utiliser la surcharge de la fonction throwError(QJSValue::ErrorType errorType, const QString &message).

Cette fonction a été introduite dans Qt 5.12.

Voir également Script Exceptions.

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

Lance une exception « error » prédéfinie. Cela vous permet d'utiliser la méthode ` newErrorObject()` pour créer l'erreur et la personnaliser selon vos besoins.

Cette fonction a été introduite dans Qt 6.1.

Voir également Script Exceptions et newErrorObject().

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

Génère une erreur d'exécution (exception) avec les paramètres ` errorType ` et ` message` fournis.

// 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");
  }
  ...
}

Cette fonction a été introduite dans Qt 5.12.

Voir également Script Exceptions et newErrorObject().

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

Crée un objet ` QJSManagedValue ` avec la ` value` indiquée.

Voir également fromManagedValue() et coerceValue().

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

Crée un ` QJSPrimitiveValue ` avec l'value` spécifiée.

Étant donné qu’une QJSPrimitiveValue ne peut contenir que des valeurs de type int, bool, double, QString, ainsi que les équivalents JavaScript de null et undefined, la valeur sera convertie de manière agressive si vous passez un autre type.

Voir également fromPrimitiveValue() et coerceValue().

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

Crée un objet ` QJSValue ` avec l'value` indiquée.

Voir également fromScriptValue() et coerceValue().