Importation de ressources JavaScript en QML

Lesressources JavaScript peuvent être importées par des documents QML et d'autres ressources JavaScript. Les ressources JavaScript peuvent être importées via des URL relatives ou absolues. Dans le cas d'une URL relative, l'emplacement est résolu par rapport à l'emplacement du document QML ou de la ressource JavaScript qui contient l'importation. Si le fichier script n'est pas accessible, une erreur se produit. Si le JavaScript doit être récupéré à partir d'une ressource réseau, l'adresse status du composant est définie sur "Loading" jusqu'à ce que le script ait été téléchargé.

Les ressources JavaScript peuvent également importer des modules QML et d'autres ressources JavaScript. La syntaxe d'une instruction d'importation dans une ressource JavaScript diffère légèrement de celle d'une instruction d'importation dans un document QML, qui est documentée en détail ci-dessous.

Importation d'une ressource JavaScript à partir d'un document QML

Un document QML peut importer une ressource JavaScript avec la syntaxe suivante :

import "ResourceURL" as Qualifier

Par exemple :

import "jsfile.js" as Logic

Les ressources JavaScript importées sont toujours qualifiées à l'aide du mot-clé "as". Le qualificatif des ressources JavaScript doit commencer par une lettre majuscule et doit être unique, de sorte qu'il existe toujours une correspondance univoque entre les qualificatifs et les fichiers JavaScript. (Cela signifie également que les qualificateurs ne peuvent pas être nommés de la même manière que les objets JavaScript intégrés tels que Date et Math).

Les fonctions définies dans un fichier JavaScript importé sont accessibles aux objets définis dans le document QML importé, via la syntaxe "Qualifier.functionName(params)". Les fonctions des ressources JavaScript peuvent prendre des paramètres dont les types peuvent être n'importe quel type de valeur ou d'objet QML, ainsi que des types JavaScript normaux. Les règles normales de conversion des types de données s'appliquent aux paramètres et aux valeurs de retour lors de l'appel de ces fonctions à partir de QML.

Importations au sein des ressources JavaScript

Sur le site QtQuick 2.0, un support a été ajouté pour permettre aux ressources JavaScript d'importer d'autres ressources JavaScript ainsi que des espaces de noms de types QML en utilisant une variante de la syntaxe d'importation QML standard (où toutes les règles et qualifications décrites précédemment s'appliquent).

Étant donné qu'une ressource JavaScript peut importer un autre script ou un module QML de cette manière dans QtQuick 2.0, certaines sémantiques supplémentaires sont définies :

• un script contenant des déclarations d'importation n'héritera pas des importations du document QML qui l'a importé (l'accès à Component.errorString échouera, par exemple)
• un script sans instruction d'importation héritera des importations du document QML qui l'a importé (l'accès à Component.errorString réussira, par exemple).
• un script partagé (défini comme une bibliothèque .pragma) n'héritera pas des importations des documents QML, même si le script n'importe pas d'autres scripts ou modules.

La première sémantique est conceptuellement correcte, étant donné qu'un script particulier peut être importé par un nombre quelconque de fichiers QML. La deuxième sémantique est conservée à des fins de compatibilité ascendante. La troisième sémantique reste inchangée par rapport à la sémantique actuelle pour les scripts partagés, mais elle est clarifiée ici en ce qui concerne le nouveau cas possible (où le script importe d'autres scripts ou modules).

Importation d'une ressource JavaScript à partir d'une autre ressource JavaScript

Une ressource JavaScript peut en importer une autre de la manière suivante :

import * as MathFunctions from "factorial.mjs";

Ou :

.import "filename.js" as Qualifier

La première est la syntaxe ECMAScript standard pour l'importation de modules ECMAScript, et ne fonctionne qu'à l'intérieur des modules ECMAScript, comme indiqué par l'extension de fichier mjs. La seconde est une extension de JavaScript fournie par le moteur QML et fonctionnera également avec les modules non-modulaires. Comme il s'agit d'une extension remplacée par la norme ECMAScript, son utilisation est déconseillée.

Lorsqu'un fichier JavaScript est importé de cette manière, il est importé avec un qualificatif. Les fonctions de ce fichier sont alors accessibles à partir du script d'importation via le qualificateur (c'est-à-dire en tant que Qualifier.functionName(params)).

Il est parfois souhaitable que les fonctions soient disponibles dans le contexte d'importation sans qu'il soit nécessaire de les qualifier. Dans ce cas, les modules ECMAScript et l'instruction JavaScript import doivent être utilisés sans le qualificatif as.

Par exemple, le code QML ci-dessous appelle showCalculations() dans script.mjs, qui peut à son tour appeler factorial() dans factorial.mjs, car il a inclus factorial.mjs en utilisant import.

import QtQuick
import "script.mjs" as MyScript

Item {
    width: 100; height: 100

    MouseArea {
        anchors.fill: parent
        onClicked: {
            MyScript.showCalculations(10)
            console.log("Call factorial() from QML:",
                MyScript.factorial(10))
        }
    }
}

// script.mjs
import { factorial } from "factorial.mjs"
export { factorial }

export function showCalculations(value) {
    console.log(
        "Call factorial() from script.js:",
        factorial(value));
}

// factorial.mjs
export function factorial(a) {
    a = parseInt(a);
    if (a <= 0)
        return 1;
    else
        return a * factorial(a - 1);
}

La fonction Qt.include() inclut un fichier JavaScript à partir d'un autre sans utiliser de modules ECMAScript et sans qualifier l'importation. Elle rend toutes les fonctions et variables de l'autre fichier disponibles dans l'espace de noms du fichier actuel, mais ignore tous les pragmas et importations définis dans ce fichier. Ce n'est pas une bonne idée, car un appel de fonction ne devrait jamais modifier le contexte de l'appelant.

Qt.include() est déprécié et doit être évité. Il sera supprimé dans une prochaine version de Qt.

Importer un module QML à partir d'une ressource JavaScript

Une ressource JavaScript peut importer un module QML de la manière suivante :

.import TypeNamespace MajorVersion.MinorVersion as Qualifier

Vous trouverez ci-dessous un exemple qui montre également comment utiliser les types QML d'un module importé en javascript :

.import Qt.test 1.0 as JsQtTest

var importedEnumValue = JsQtTest.MyQmlObject.EnumValue3

En particulier, cela peut être utile pour accéder à une fonctionnalité fournie par un type singleton ; voir QML_SINGLETON pour plus d'informations.

Par défaut, votre ressource JavaScript peut accéder à toutes les importations du composant qui importe la ressource. Elle n'a pas accès aux importations du composant si elle est déclarée comme une bibliothèque sans état (à l'aide de .pragma library) ou si elle contient une déclaration explicite .import.