Définition des ressources JavaScript dans QML

La logique d'une application QML peut être définie en JavaScript. Le code JavaScript peut être intégré directement dans les documents QML ou séparé dans des fichiers JavaScript (appelés « JavaScript Resources » en QML).

QML prend en charge deux types de ressources JavaScript : les fichiers d’implémentation « code-behind » et les fichiers partagés (bibliothèques). Ces deux types de ressources JavaScript peuvent être importés par d’autres ressources JavaScript ou inclus dans des modules QML.

Ressource d’implémentation « code-behind »

La plupart des fichiers JavaScript importés dans un document QML constituent des implémentations avec état pour le document QML qui les importe. Dans ces cas, chaque instance du type d’objet QML défini dans le document nécessite une copie distincte des objets JavaScript et de l’état pour fonctionner correctement.

Le comportement par défaut lors de l’importation de fichiers JavaScript consiste à fournir une copie unique et isolée pour chaque instance de composant QML. Si ce fichier JavaScript n’importe aucune ressource ni aucun module à l’aide d’une instruction ` .import `, son code s’exécutera dans la même portée que l’instance du composant QML et pourra donc accéder aux objets et propriétés déclarés dans ce composant QML et les manipuler. Dans le cas contraire, il disposera de sa propre portée unique, et les objets et propriétés du composant QML devront être transmis aux fonctions du fichier JavaScript en tant que paramètres s’ils sont nécessaires.

Voici un exemple de ressource d’implémentation « code-behind » :

// MyButton.qml
import QtQuick 2.0
import "my_button_impl.js" as Logic // A new instance of this JavaScript resource
                                    // is loaded for each instance of Button.qml.

Rectangle {
    id: rect
    width: 200
    height: 100
    color: "red"

    MouseArea {
        id: mousearea
        anchors.fill: parent
        onClicked: Logic.onClicked(rect)
    }
}

// my_button_impl.js
var clickCount = 0;   // this state is separate for each instance of MyButton
function onClicked(button) {
    clickCount += 1;
    if ((clickCount % 5) == 0) {
        button.color = Qt.rgba(1,0,0,1);
    } else {
        button.color = Qt.rgba(0,1,0,1);
    }
}

En général, la logique simple doit être définie en ligne dans le fichier QML, tandis que la logique plus complexe doit être séparée dans des ressources d’implémentation « code-behind » pour faciliter la maintenance et améliorer la lisibilité.

Ressources JavaScript partagées (bibliothèques)

Par défaut, les fichiers JavaScript importés depuis QML partagent leur contexte avec le composant QML. Cela signifie que les fichiers JavaScript ont accès aux mêmes objets QML et peuvent les modifier. Par conséquent, chaque importation doit disposer d'une copie unique de ces fichiers.

La section précédente traite des importations de fichiers JavaScript avec état. Cependant, certains fichiers JavaScript sont sans état et s’apparentent davantage à des bibliothèques réutilisables, dans la mesure où ils fournissent un ensemble de fonctions d’aide qui ne nécessitent aucune information provenant de l’endroit d’où ils ont été importés. Vous pouvez économiser une quantité importante de mémoire et accélérer l’instanciation des composants QML en marquant ces bibliothèques à l’aide d’un pragma spécial, comme le montre l’exemple suivant.

// factorial.js
.pragma library

var factorialCount = 0;

function factorial(a) {
    a = parseInt(a);

    // factorial recursion
    if (a > 0)
        return a * factorial(a - 1);

    // shared state
    factorialCount += 1;

    // recursion base-case.
    return 1;
}

function factorialCallCount() {
    return factorialCount;
}

La déclaration du pragma doit apparaître avant tout code JavaScript, à l’exception des commentaires.

Notez que plusieurs documents QML peuvent importer ` "factorial.js" ` et appeler les fonctions `factorial` et `factorialCallCount` qu’il fournit. L’état de l’importation JavaScript est partagé entre les documents QML qui l’importent ; par conséquent, la valeur de retour de la fonction `factorialCallCount` peut être différente de zéro lorsqu’elle est appelée dans un document QML qui n’appelle jamais la fonction `factorial`.

Par exemple :

// Calculator.qml
import QtQuick 2.0
import "factorial.js" as FactorialCalculator // This JavaScript resource is only
                                             // ever loaded once by the engine,
                                             // even if multiple instances of
                                             // Calculator.qml are created.

Text {
    width: 500
    height: 100
    property int input: 17
    text: "The factorial of " + input + " is: " + FactorialCalculator.factorial(input)
}

Comme ils sont partagés, les fichiers de bibliothèque .pragma ne peuvent pas accéder directement aux objets d’instance ou aux propriétés des composants QML, bien que des valeurs QML puissent être transmises en tant que paramètres de fonction.