Importation de ressources JavaScript dans QML

Les ressources 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 déterminé par rapport à celui du document QML ou de la ressource JavaScript contenant l’importation. Si le fichier de script n’est pas accessible, une erreur se produit. Si le code JavaScript doit être récupéré à partir d’une ressource réseau, la propriété « 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 au sein d’une ressource JavaScript diffère légèrement de celle d’une instruction d’importation au sein d’un document QML ; elle est décrite en détail ci-dessous.

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

Un document QML peut importer une ressource JavaScript à l’aide de 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 qualificateur des ressources JavaScript doit commencer par une majuscule et être unique, de sorte qu’il existe toujours une correspondance biunivoque entre les qualificateurs et les fichiers JavaScript. (Cela signifie également que les qualificateurs ne peuvent pas porter le même nom que des 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 qui les importe, 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 de type objet QML, ainsi que les types JavaScript habituels. Les règles habituelles de conversion des types de données s'appliquent aux paramètres et aux valeurs de retour lors de l'appel de ces fonctions depuis QML.

Importations au sein des ressources JavaScript

Dans ` QtQuick 2.0`, une prise en charge a été ajoutée pour permettre aux ressources JavaScript d’importer d’autres ressources JavaScript ainsi que des espaces de noms de type QML à l’aide d’une variante de la syntaxe d’importation QML standard (où toutes les règles et conditions décrites précédemment s’appliquent).

En raison de la capacité d’une ressource JavaScript à importer un autre script ou module QML de cette manière dans la version QtQuick 2.0, certaines règles sémantiques supplémentaires ont été définies :

• un script contenant des instructions 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 instructions 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 .pragma library) 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 règle est conceptuellement correcte, étant donné qu’un script donné peut être importé par un nombre indéfini de fichiers QML. La deuxième règle 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 de figure (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’au sein de modules ECMAScript, comme l’indique l’extension de fichier mjs. La seconde est une extension de JavaScript fournie par le moteur QML et fonctionne également avec des éléments non modulaires. En tant qu’extension supplantée par la norme ECMAScript, son utilisation est déconseillée.

Lorsqu’un fichier JavaScript est importé de cette manière, il l’est avec un qualificateur. Les fonctions de ce fichier sont alors accessibles depuis le script importateur via ce qualificateur (c’est-à-dire sous la forme Qualifier.functionName(params)).

Il est parfois souhaitable que les fonctions soient disponibles dans le contexte d’importation sans avoir à les qualifier. Dans ce cas, il convient d’utiliser les modules ECMAScript et l’instruction JavaScript ` import ` sans le qualificateur ` as `.

Par exemple, le code QML ci-dessous à gauche appelle ` showCalculations() ` dans ` script.mjs`, qui peut à son tour appeler ` factorial() ` dans ` factorial.mjs`, car il a inclus ` factorial.mjs ` à l’aide de ` 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 les 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 courant, mais ignore tous les pragmas et toutes les 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 obsolète et doit être évité. Il sera supprimé dans une future version de Qt.

Importation d'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

Cela peut notamment s’avérer utile pour accéder à des fonctionnalités fournies via un type singleton ; consultez 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 celui-ci est déclaré comme bibliothèque sans état (à l’aide de ` .pragma library`) ou s’il contient une instruction ` .import ` explicite.