Environnement hôte JavaScript

QML fournit un environnement hôte JavaScript adapté à l'écriture d'applications QML. Cet environnement est différent de l'environnement hôte fourni par un navigateur ou un environnement JavaScript côté serveur tel que Node.js. Par exemple, QML ne fournit pas d'objet window ou DOM API, comme c'est généralement le cas dans un environnement de navigateur.

Base commune

Comme un navigateur ou un environnement JavaScript côté serveur, le Runtime QML met en œuvre la norme de 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 met en œuvre la 7e édition de la norme.

Nullish Coalescing (??) (depuis Qt 5.15) et Optional Chaining (?.) (depuis Qt 6.2) sont également implémentés dans le runtime QML.

De plus, les séparateurs littéraux numériques (les underscores dans 1_000_000) sont supportés depuis Qt 6.8.

Les modules ECMAScript standard ne sont pas explicitement décrits dans la documentation QML. Pour plus d'informations sur leur utilisation, veuillez vous référer à la norme ECMA-262 7e édition ou à l'un des nombreux sites de référence et de tutorat JavaScript en ligne, tels que la référence JavaScript de W3Schools (section Référence des objets JavaScript). De nombreux sites se concentrent sur le JavaScript dans le navigateur, de sorte que dans certains cas, vous devrez vérifier la spécification pour déterminer si une fonction ou un objet donné fait partie de l'ECMAScript standard 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 au navigateur (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'annoter le type de retour. La fonction suivante prend un paramètre int et un paramètre string, et renvoie un paramètre QtObject:

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

Les annotations de type permettent à des outils tels que Qt Creator et qmllint à comprendre le code et à fournir de meilleurs diagnostics. En outre, elles facilitent l'utilisation des fonctions en C++. Voir Interagir avec les objets QML à partir de C++ pour plus d'informations.

L'exception à cette règle concerne les fonctions affectées aux gestionnaires de signaux : Dans ce cas, les annotations de type sont interdites afin d'éviter une éventuelle incompatibilité avec les types du signal. Cela ne pose pas de problème pour l'outillage, 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 autre type d'objet. Si l'objet est effectivement du type donné, l'assertion de type renvoie le même objet. Dans le cas contraire, elle renvoie null. Dans l'extrait suivant, nous affirmons que l'objet parent est un Rectangle avant d'accéder à un membre spécifique de cet objet.

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

Le chaînage optionnel (?.) permet d'éviter de lever une exception si le parent n'est 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 contraintes 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 conduire à des différences de comportement dans certains cas particuliers. Afin de demander explicitement l'ancien comportement de l'interpréteur et du compilateur JIT, vous pouvez ajouter ce qui suit à votre document QML :

pragma FunctionSignatureBehavior: Ignored

Objet global QML

L'environnement hôte JavaScript QML met en œuvre un certain nombre d'objets et de fonctions hôtes, comme indiqué dans la documentation QML Global Object.

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

Objets et fonctions JavaScript

La liste des objets, fonctions et propriétés JavaScript pris en charge par le moteur QML se trouve 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 spécificités locales sont ajoutées aux prototypes Date et Nombre.

Voir aussi :

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

En outre, QML étend également le comportement de la fonction instanceof pour permettre la vérification de type 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 met en œuvre les restrictions suivantes pour le 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 lorsqu'il sera importé.

  En QML, l'objet global est constant - les propriétés existantes ne peuvent pas être modifiées ou 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 en 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 trivialement modifié en ce code légal.

  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 - que ce soit implicitement ou explicitement - provoquera une exception. Si celle-ci n'est pas détectée, un avertissement sera imprimé, indiquant le numéro de fichier et de ligne du code incriminé.

• Le code global est exécuté dans un périmètre réduit.

  Au cours du démarrage, si un fichier QML comprend un fichier JavaScript externe avec 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. En d'autres termes, il n'aura pas accès aux objets et propriétés QML qu'il devrait normalement avoir.

  Le code global qui n'accède qu'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 aux 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 totalement établi. Pour exécuter du code après l'installation de l'environnement, voir JavaScript dans le code de démarrage de l'application.

• La valeur de this n'est pas définie en QML dans la majorité 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 QML, this fait référence à l'objet scope. Dans toutes les autres situations, la valeur de this n'est pas définie dans QML.

  Pour faire référence à un objet spécifique, il convient de fournir un 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)
      }
  }