Environnement d'exécution JavaScript

QML fournit un environnement d'exécution JavaScript spécialement conçu pour l'écriture d'applications QML. Cet environnement diffère de celui fourni par un navigateur ou d'un environnement JavaScript côté serveur tel que Node.js. Par exemple, QML ne fournit pas d'objet ` window ` ni de ` DOM API `, comme on en trouve couramment dans un environnement de navigateur.

Base commune

À l’instar d’un navigateur ou d’un environnement JavaScript côté serveur, le QML Runtime implémente la spécification du langage ECMAScript. Cela permet d’accéder à tous les types et fonctions intégrés définis par la norme, tels que `Object`, `Array` et `Math`. Le QML Runtime implémente la 7e édition de la norme.

La coalescence nullish (??) (depuis Qt 5.15) et le chaînage optionnel (?.) (depuis Qt 6.2) sont également implémentés dans le QML Runtime.

De plus, les séparateurs de littéraux numériques (les traits de soulignement dans 1_000_000) sont pris en charge depuis Qt 6.8.

Les fonctions intégrées standard d’ECMAScript ne sont pas explicitement documentées dans la documentation QML. Pour plus d’informations sur leur utilisation, veuillez vous reporter à la norme ECMA-262, 7e édition, ou à l’un des nombreux sites de référence et tutoriels JavaScript en ligne, tels que la référence JavaScript de W3Schools (section « JavaScript Objects Reference »). De nombreux sites se concentrent sur le JavaScript dans le navigateur ; dans certains cas, vous devrez donc peut-être vérifier la spécification pour déterminer si une fonction ou un objet donné fait partie de la norme ECMAScript ou s’il est spécifique à l’environnement du navigateur. Dans le cas du lien W3Schools ci-dessus, la section « JavaScript Objects Reference » couvre généralement la norme, tandis que les sections « Browser Objects Reference » et « HTML DOM Objects Reference » sont spécifiques aux navigateurs (et ne s’appliquent donc pas à QML).

Annotations de type et assertions

Les déclarations de fonctions dans les documents QML peuvent, et doivent, contenir des annotations de type. Les annotations de type sont ajoutées à la déclaration des arguments et à la fonction elle-même, afin d’indiquer le type de retour. La fonction suivante prend un paramètre de type « int » et un paramètre de type « string », et renvoie un objet de type « QtObject » :

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

Les annotations de type aident des outils tels que Qt Creator et qmllint à comprendre le code et à fournir de meilleurs diagnostics. De plus, elles facilitent l’utilisation des fonctions depuis le C++. Voir Interagir avec des objets QML depuis le C++ pour plus d’informations.

Les fonctions attribuées à des gestionnaires de signaux font exception à cette règle : dans ce cas, les annotations de type sont interdites afin d’éviter tout décalage potentiel avec les types du signal. Cela ne pose aucun problème pour les outils, car le signal fournit déjà les informations nécessaires.

Les assertions de type (parfois appelées « as-casts ») peuvent également être utilisées pour convertir un objet en un type d’objet différent. Si l’objet est effectivement du type indiqué, l’assertion de type renvoie le même objet. Dans le cas contraire, elle renvoie ` null`. Dans l’extrait de code suivant, nous vérifions que l’objet ` parent ` est bien un ` Rectangle ` avant d’accéder à l’un de ses membres spécifiques.

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

Le chaînage optionnel (?.) évite de lever une exception si le parent n’est en réalité pas un rectangle. Dans ce cas, « red » est choisi comme parentColor.

Depuis Qt 6.7, les annotations de type sont toujours appliquées lors de l’appel de fonctions. Les valeurs sont converties aux types requis si nécessaire. Auparavant, les annotations de type étaient ignorées par l’interpréteur et le compilateur JIT, mais appliquées par qmlcachegen et qmlsc lors de la compilation en C++. Cela pouvait entraîner des différences de comportement dans certains cas particuliers. Afin de demander explicitement l’ancien comportement de l’interpréteur et du JIT, vous pouvez ajouter ce qui suit à votre document QML :

pragma FunctionSignatureBehavior: Ignored

Objet global QML

L’environnement hôte JavaScript de QML implémente un certain nombre d’objets et de fonctions hôtes, comme détaillé dans la documentation sur les objets globaux QML.

Ces objets et fonctions hôtes sont toujours disponibles, que des modules aient été importés ou non.

Objets et fonctions JavaScript

Une liste des objets, fonctions et propriétés JavaScript pris en charge par le moteur QML est disponible dans la Liste des objets et fonctions JavaScript.

Notez que QML apporte les modifications suivantes aux objets natifs :

• Une fonction ` arg() ` est ajoutée au prototype ` String `.
• Des fonctions de conversion tenant compte des paramètres régionaux sont ajoutées aux prototypes ` Date ` et ` Number `.

Voir aussi :

• Number - L'objet JavaScript Number
• Date - L'objet JavaScript Date
• XMLHttpRequest - L'objet JavaScript XMLHttpRequest

De plus, QML étend également le comportement de la fonction `instanceof` pour permettre la vérification des types par rapport aux types QML. Cela signifie que vous pouvez l'utiliser pour vérifier qu'une variable est bien du type attendu, par exemple :

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

...

Restrictions de l'environnement JavaScript

QML applique les restrictions suivantes au code JavaScript :

• Le code JavaScript écrit dans un fichier « .qml » ne peut pas modifier l’objet global. Le code JavaScript contenu dans un fichier .js peut modifier l’objet global, et ces modifications seront visibles dans le fichier .qml lors de son importation.

  En QML, l’objet global est constant : les propriétés existantes ne peuvent être ni modifiées ni supprimées, et aucune nouvelle propriété ne peut être créée.

  La plupart des programmes JavaScript ne modifient pas intentionnellement l'objet global. Cependant, la création automatique par JavaScript de variables non déclarées constitue une modification implicite de l'objet global et est interdite dans QML.

  En supposant que la variable ` a ` n'existe pas dans la chaîne de portée, le code suivant est illégal en QML :

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

  Il peut être facilement modifié pour devenir ce code valide.

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

  Toute tentative de modification de l’objet global — qu’elle soit implicite ou explicite — provoquera une exception. Si celle-ci n’est pas interceptée, un avertissement s’affichera, indiquant le nom du fichier et le numéro de ligne du code incriminé.

• Le code global s'exécute dans une portée restreinte.

  Au démarrage, si un fichier QML inclut un fichier JavaScript externe contenant du code « global », celui-ci est exécuté dans une portée qui ne contient que le fichier externe lui-même et l’objet global. Autrement dit, il n’aura pas accès aux objets et propriétés QML auxquels il aurait normalement accès.

  Le code global qui accède uniquement aux variables locales du script est autorisé. Voici un exemple de code global valide.

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

  Le code global qui accède à des objets QML ne s'exécutera pas correctement.

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

  Cette restriction existe car l'environnement QML n'est pas encore entièrement configuré. Pour exécuter du code une fois la configuration de l'environnement terminée, consultez la section « JavaScript dans le code de démarrage de l'application ».

• La valeur de ` this ` est indéfinie en QML dans la plupart des contextes.

  Le mot-clé « this » est pris en charge lors de la liaison de propriétés à partir de JavaScript. Dans les expressions de liaison QML, les gestionnaires de signaux QML et les fonctions déclarées en QML, « this » fait référence à l’objet de portée. Dans toutes les autres situations, la valeur de « this » est indéfinie en QML.

  Pour faire référence à un objet spécifique, utilisez ` id`. Par exemple :

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