Expressions JavaScript dans les documents QML

L'environnement hôte JavaScript fourni par QML peut exécuter des constructions JavaScript standard valides telles que les opérateurs conditionnels, les tableaux, la définition de variables et les boucles. Outre les propriétés JavaScript standard, l'objet global QML comprend un certain nombre de méthodes d'aide qui simplifient la construction d'interfaces utilisateur et l'interaction avec l'environnement QML.

L'environnement JavaScript fourni par QML est plus strict que celui d'un navigateur web. Par exemple, en QML, il n'est pas possible d'ajouter ou de modifier des membres de l'objet global JavaScript. En JavaScript normal, il est possible de le faire accidentellement en utilisant une variable sans la déclarer. En QML, une exception est levée, de sorte que toutes les variables locales doivent être explicitement déclarées. Voir Restrictions de l'environnement JavaScript pour une description complète des restrictions sur le code JavaScript exécuté à partir de QML.

Diverses parties des documents QML peuvent contenir du code JavaScript :

1. Le corps des liaisons de propriétés. Ces expressions JavaScript décrivent les relations entre les propriétés des objets QML. Lorsque les dépendances d' une propriété changent, la propriété est automatiquement mise à jour, conformément à la relation spécifiée.
2. Le corps des gestionnaires de signaux. Ces déclarations JavaScript sont automatiquement évaluées chaque fois qu'un objet QML émet le signal associé.
3. La définition des méthodes personnalisées. Les fonctions JavaScript définies dans le corps d'un objet QML deviennent des méthodes de cet objet.
4. Fichiers de ressources JavaScript autonomes (.js). Ces fichiers sont en fait distincts des documents QML, mais ils peuvent être importés dans les documents QML. Les fonctions et les variables définies dans les fichiers importés peuvent être utilisées dans les liaisons de propriétés, les gestionnaires de signaux et les méthodes personnalisées.

JavaScript dans les liaisons de propriétés

Dans l'exemple suivant, la propriété color de Rectangle dépend de la propriété pressed de TapHandler. Cette relation est décrite à l'aide d'une expression conditionnelle :

import QtQuick 2.12

Rectangle {
    id: colorbutton
    width: 200; height: 80;

    color: inputHandler.pressed ? "steelblue" : "lightsteelblue"

    TapHandler {
        id: inputHandler
    }
}

En fait, toute expression JavaScript (quelle que soit sa complexité) peut être utilisée dans une définition de liaison de propriété, tant que le résultat de l'expression est une valeur dont le type peut être affecté à la propriété. Cela inclut les effets de bord. Cependant, les liaisons complexes et les effets de bord sont déconseillés car ils peuvent réduire les performances, la lisibilité et la maintenabilité du code.

Il existe deux façons de définir une liaison de propriété : la plus courante est illustrée dans l'exemple précédent, dans l'initialisation d'une propriété. La seconde (beaucoup plus rare) consiste à affecter à la propriété une fonction renvoyée par la fonction Qt.binding(), à l'intérieur d'un code JavaScript impératif, comme illustré ci-dessous :

import QtQuick 2.12

Rectangle {
    id: colorbutton
    width: 200; height: 80;

    color: "red"

    TapHandler {
        id: inputHandler
    }

    Component.onCompleted: {
        color = Qt.binding(function() { return inputHandler.pressed ? "steelblue" : "lightsteelblue" });
    }
}

Voir la documentation sur les liaisons de propriétés pour plus d'informations sur la manière de définir les liaisons de propriétés, et voir la documentation sur l'affectation de propriétés par rapport à la liaison de propriétés pour des informations sur la manière dont les liaisons diffèrent des affectations de valeurs.

JavaScript dans les gestionnaires de signaux

Les types d'objets QML peuvent émettre des signaux en réaction à certains événements. Ces signaux peuvent être traités par des fonctions de gestion des signaux, qui peuvent être définies par les clients pour mettre en œuvre une logique de programme personnalisée.

Supposons qu'un bouton représenté par un type Rectangle possède une étiquette TapHandler et une étiquette Text. Le TapHandler émet son signal tapped lorsque l'utilisateur appuie sur le bouton. Les clients peuvent réagir au signal dans le gestionnaire onTapped à l'aide d'expressions JavaScript. Le moteur QML exécute ces expressions JavaScript définies dans le gestionnaire en fonction des besoins. En général, un gestionnaire de signal est lié à des expressions JavaScript pour déclencher d'autres événements ou pour attribuer des valeurs de propriété.

import QtQuick 2.12

Rectangle {
    id: button
    width: 200; height: 80; color: "lightsteelblue"

    TapHandler {
        id: inputHandler
        onTapped: {
            // arbitrary JavaScript expression
            console.log("Tapped!")
        }
    }

    Text {
        id: label
        anchors.centerIn: parent
        text: inputHandler.pressed ? "Pressed!" : "Press here!"
    }
}

Pour plus de détails sur les signaux et les gestionnaires de signaux, reportez-vous aux rubriques suivantes :

• Système d'événements des signaux et des gestionnaires
• Attributs des objets QML

JavaScript dans les fonctions autonomes

La logique du programme peut également être définie dans des fonctions JavaScript. Ces fonctions peuvent être définies en ligne dans les documents QML (en tant que méthodes personnalisées) ou en externe dans des fichiers JavaScript importés.

JavaScript dans les méthodes personnalisées

Les méthodes personnalisées peuvent être définies dans des documents QML et peuvent être appelées à partir de gestionnaires de signaux, de liaisons de propriétés ou de fonctions dans d'autres objets QML. Ces méthodes sont souvent appelées fonctions JavaScript en ligne, car leur mise en œuvre est incluse dans la définition du type d'objet QML (document QML), et non dans un fichier JavaScript externe.

Voici un exemple de méthode personnalisée en ligne :

import QtQuick 2.12

Item {
    function fibonacci(n){
        var arr = [0, 1];
        for (var i = 2; i < n + 1; i++)
            arr.push(arr[i - 2] + arr[i -1]);

        return arr;
    }
    TapHandler {
        onTapped: console.log(fibonacci(10))
    }
}

La fonction fibonacci est exécutée chaque fois que le site TapHandler émet un signal tapped.

Voir la documentation sur les attributs d'objets QML pour plus d'informations sur la définition de méthodes personnalisées en QML à l'aide de JavaScript.

Fonctions définies dans un fichier JavaScript

Il est préférable de séparer la logique de programme non triviale dans un fichier JavaScript distinct. Ce fichier peut être importé dans QML à l'aide d'une déclaration import, comme les modules QML.

Par exemple, la méthode fibonacci() de l'exemple précédent peut être déplacée dans un fichier externe nommé fib.js, et accessible comme suit :

import QtQuick 2.12
import "fib.js" as MathFunctions

Item {
    TapHandler {
        onTapped: console.log(MathFunctions.fibonacci(10))
    }
}

Pour plus d'informations sur le chargement de fichiers JavaScript externes dans QML, lisez la section sur l'importation de ressources JavaScript dans QML.

Connecter des signaux à des fonctions JavaScript

Les types d'objets QML qui émettent des signaux fournissent également des gestionnaires de signaux par défaut pour leurs signaux, comme décrit dans la section précédente. Parfois, cependant, un client souhaite déclencher une fonction définie dans un objet QML lorsqu'un autre objet QML émet un signal. De tels scénarios peuvent être gérés par une connexion de signal.

Un signal émis par un objet QML peut être connecté à une fonction JavaScript en appelant la méthode connect() du signal et en passant la fonction JavaScript en argument. Par exemple, le code suivant connecte le signal tapped de TapHandler au signal jsFunction() de script.js:

import QtQuick
import "script.js" as MyScript

Item {
    id: item
    width: 200; height: 200

    TapHandler {
        id: inputHandler
    }

    Component.onCompleted: {
        inputHandler.tapped.connect(MyScript.jsFunction)
    }
}

// script.js

function jsFunction() {
    console.log("Called JavaScript function!")
}

La méthode jsFunction() est appelée chaque fois que le signal tapped de TapHandler est émis.

Pour plus d'informations, voir Connecter des signaux à des méthodes et à des signaux.

JavaScript dans le code de démarrage de l'application

Il est parfois nécessaire d'exécuter du code impératif au démarrage de l'application (ou de l'instance de composant). Bien qu'il soit tentant d'inclure le script de démarrage en tant que code global dans un fichier script externe, cela peut avoir de sérieuses limitations car l'environnement QML peut ne pas avoir été complètement établi. Par exemple, certains objets peuvent ne pas avoir été créés ou certaines liaisons de propriétés peuvent ne pas avoir été établies. Voir les restrictions de l'environnement JavaScript pour connaître les limites exactes du code de script global.

Un objet QML émet le signal Component.completed attached lorsque son instanciation est terminée. Le code JavaScript du gestionnaire Component.onCompleted correspondant s'exécute après l'instanciation de l'objet. Ainsi, le meilleur endroit pour écrire le code de démarrage de l'application est dans le gestionnaire Component.onCompleted de l'objet de premier niveau, car cet objet émet Component.completed lorsque l'environnement QML est entièrement établi.

Par exemple, tout objet d'un fichier QML

import QtQuick 2.0

Rectangle {
    function startupFunction() {
        // ... startup code
    }

    Component.onCompleted: startupFunction();
}

Tout objet d'un fichier QML - y compris les objets imbriqués et les instances de composants QML imbriquées - peut utiliser cette propriété attachée. S'il y a plus d'un gestionnaire onCompleted() à exécuter au démarrage, ils sont exécutés séquentiellement dans un ordre non défini.

De même, chaque Component émet un signal destruction() juste avant d'être détruit.