Définition des ressources JavaScript dans QML

La logique du programme d'une application QML peut être définie en JavaScript. Le code JavaScript peut être défini en ligne dans les documents QML ou séparé en fichiers JavaScript (connus sous le nom de JavaScript Resources en QML).

Deux types de ressources JavaScript sont pris en charge par QML : les fichiers d'implémentation de 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 de code-behind

La plupart des fichiers JavaScript importés dans un document QML sont des implémentations avec état pour le document QML qui les importe. Dans ce 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 se comporter correctement.

Le comportement par défaut lors de l'importation de fichiers JavaScript est de fournir une copie unique et isolée pour chaque instance de composant QML. Si ce fichier JavaScript n'importe aucune ressource ou module avec une déclaration .import, son code s'exécutera dans la même portée que l'instance du composant QML et pourra donc accéder et manipuler les objets et propriétés déclarés dans ce composant QML. Dans le cas contraire, il aura sa propre portée, 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.

Un exemple de ressource de mise en œuvre de code-behind suit :

// 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, mais la logique plus complexe doit être séparée dans des ressources d'implémentation de code-behind pour des raisons de maintenabilité et de lisibilité.

Ressources JavaScript partagées (bibliothèques)

Par défaut, les fichiers JavaScript importés de 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 couvre les importations de fichiers JavaScript avec état. Cependant, certains fichiers JavaScript sont sans état et agissent davantage comme des bibliothèques réutilisables, dans le sens où ils fournissent un ensemble de fonctions d'aide qui ne requièrent rien de l'endroit d'où ils ont été importés. Vous pouvez économiser des quantités importantes de mémoire et accélérer l'instanciation des composants QML si vous marquez ces bibliothèques avec 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 de pragma doit apparaître avant tout code JavaScript, à l'exclusion 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, et la valeur de retour de la fonction factorialCallCount peut donc être différente de zéro lorsqu'elle est appelée dans un document QML qui n'appelle jamais la fonction factorielle.

A titre d'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 la bibliothèque .pragma ne peuvent pas accéder directement aux objets d'instance ou aux propriétés des composants QML, bien que les valeurs QML puissent être transmises en tant que paramètres de fonction.