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 création 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, vous ne pouvez ni ajouter ni modifier des membres de l'objet global JavaScript. En JavaScript standard, il est possible de le faire accidentellement en utilisant une variable sans la déclarer. En QML, cela provoquera une exception ; toutes les variables locales doivent donc être explicitement déclarées. Consultez la section « Restrictions de l’environnement JavaScript » pour une description complète des restrictions applicables au code JavaScript exécuté à partir de QML.

Différentes 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, celle-ci est automatiquement mise à jour, conformément à la relation spécifiée.
2. Le corps des gestionnaires de signaux. Ces instructions 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. Les fichiers de ressources JavaScript autonomes (.js). Ces fichiers sont en réalité distincts des documents QML, mais ils peuvent être importés dans ces derniers. Les fonctions et 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 réalité, toute expression JavaScript (aussi complexe soit-elle) peut être utilisée dans la définition d’un lien de propriété, à condition que le résultat de l’expression soit une valeur dont le type puisse être assigné à la propriété. Cela inclut les effets secondaires. Cependant, les liens complexes et les effets secondaires sont déconseillés car ils peuvent nuire aux 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, lors de l’initialisation d’une propriété. La seconde (et bien plus rare) consiste à attribuer à la propriété une fonction renvoyée par la fonction ` Qt.binding()`, à partir 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" });
    }
}

Consultez la documentation sur les liaisons de propriétés pour plus d’informations sur la manière de définir des liaisons de propriétés, et consultez la documentation sur l’affectation de propriétés par rapport à la liaison de propriétés pour savoir en quoi 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 gérés par des fonctions de gestion de signaux, qui peuvent être définies par les clients pour implémenter une logique de programme personnalisée.

Supposons qu’un bouton représenté par un type Rectangle comporte une propriété « TapHandler » et une étiquette « Text ». La propriété « TapHandler » émet son signal « tapped » lorsque l’utilisateur appuie sur le bouton. Les clients peuvent réagir à ce signal dans le gestionnaire « onTapped » à l’aide d’expressions JavaScript. Le moteur QML exécute ces expressions JavaScript définies dans le gestionnaire selon les 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 à des propriétés.

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 « signal et gestionnaire »
• Attributs d’objet QML

JavaScript dans des fonctions autonomes

La logique de programme peut également être définie dans des fonctions JavaScript. Ces fonctions peuvent être définies en ligne dans des 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 implémentation est incluse dans la définition du type d’objet QML (document QML), plutôt que dans un fichier JavaScript externe.

Voici un exemple de méthode personnalisée intégrée :

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 l’ TapHandler émet un signal « tapped ».

Consultez la documentation sur les attributs d’objet 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 instruction ` import `, à l'instar des modules QML.

Par exemple, la méthode ` fibonacci() ` de l’exemple précédent pourrait être déplacée dans un fichier externe nommé ` fib.js` et être appelée 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, consultez la section consacrée à l’importation de ressources JavaScript dans QML.

Connexion de 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. Il arrive cependant parfois qu’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 lui passant la fonction JavaScript en argument. Par exemple, le code suivant connecte le signal ` tapped ` de l’objet ` TapHandler` à la fonction ` jsFunction() ` définie dans ` 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, consultez la section « Connexion de 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 d’une instance de composant). Bien qu’il soit tentant d’inclure simplement le script de démarrage en tant que code global dans un fichier de script externe, cela peut présenter de sérieuses limitations, car l’environnement QML n’est peut-être pas encore entièrement é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. Consultez la section « Restrictions de l’environnement JavaScript » pour connaître les limitations exactes du code de script global.

Un objet QML émet le signal « Component.completed » une fois son instanciation 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 le gestionnaire « Component.onCompleted » de l’objet de niveau supérieur, car cet objet émet le signal « Component.completed » lorsque l’environnement QML est entièrement établi.

Par exemple :

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é associée. S’il existe plusieurs gestionnaires onCompleted() à exécuter au démarrage, ceux-ci sont exécutés séquentiellement dans un ordre indéfini.

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