Conventions de codage QML

Ce document présente les conventions de codage QML que nous appliquons dans notre documentation et nos exemples, et que nous recommandons à d'autres de suivre.

Déclarations d’objets QML

Dans l'ensemble de notre documentation et de nos exemples, les attributs des objets QML sont toujours structurés dans l'ordre suivant :

• id
• déclarations de propriétés
• déclarations de signaux
• fonctions JavaScript
• propriétés de l'objet
• objets enfants

Pour une meilleure lisibilité, nous séparons ces différentes parties par une ligne vide.

Par exemple, un objet QML hypothétique de type « photo » ressemblerait à ceci :

Rectangle {
    id: photo                                               // id on the first line makes it easy to find an object

    property bool thumbnail: false                          // property declarations
    property alias image: photoImage.source

    signal clicked                                          // signal declarations

    function doSomething(x)                                 // javascript functions
    {
        return x + photoImage.width;
    }

    color: "gray"                                           // object properties
    x: 20                                                   // try to group related properties together
    y: 20
    height: 150
    width: {                                                // large bindings
        if (photoImage.width > 200) {
            photoImage.width;
        } else {
            200;
        }
    }

    states: [
        State {
            name: "selected"
            PropertyChanges { target: border; color: "red" }
        }
    ]

    transitions: [
        Transition {
            from: ""
            to: "selected"
            ColorAnimation { target: border; duration: 200 }
        }
    ]

    Rectangle {                                             // child objects
        id: border
        anchors.centerIn: parent
        color: "white"

        Image {
            id: photoImage
            anchors.centerIn: parent
        }
    }
}

Propriétés groupées

Si vous utilisez plusieurs propriétés issues d’un groupe de propriétés, pensez à utiliser la notation de groupe plutôt que la notation par points si cela améliore la lisibilité.

Par exemple, ceci :

Rectangle {
    anchors.left: parent.left; anchors.top: parent.top; anchors.right: parent.right; anchors.leftMargin: 20
}

Text {
    text: "hello"
    font.bold: true; font.italic: true; font.pixelSize: 20; font.capitalization: Font.AllUppercase
}

pourrait s'écrire ainsi :

Rectangle {
    anchors { left: parent.left; top: parent.top; right: parent.right; leftMargin: 20 }
}

Text {
    text: "hello"
    font { bold: true; italic: true; pixelSize: 20; capitalization: Font.AllUppercase }
}

Accès non qualifié

Afin d'améliorer la lisibilité et les performances, référencez toujours explicitement les propriétés des composants parents par leur identifiant :

Item {
    id: root

    property int rectangleWidth: 50

    Rectangle {
        width: root.rectangleWidth
    }
}

Propriétés obligatoires

Lorsque vous avez besoin de données définies en dehors du composant, indiquez-le explicitement à l’aide des propriétés obligatoires. Les propriétés obligatoires doivent être définies, sinon la création du composant échouera. Elles sont préférables aux recherches non qualifiées, car elles sont plus performantes et permettent à la fois aux utilisateurs et aux outils de déterminer le type d’une propriété externe. De plus, elles éliminent les hypothèses qu’un composant devrait autrement formuler concernant l’environnement dans lequel il est créé.

Gestionnaires de signaux

Lors du traitement des paramètres dans les gestionnaires de signaux, utilisez des fonctions qui les nomment explicitement :

MouseArea {
    onClicked: event => { console.log(`${event.x},${event.y}`); }
}

Code JavaScript

Pour une meilleure lisibilité et une meilleure maintenabilité, nous déclarons généralement chaque propriété sur une ligne distincte, même pour les expressions simples.

Rectangle {
    color: "blue"
    width: parent.width / 3
}

Pour les expressions de script s'étendant sur plusieurs lignes, nous utilisons un format en bloc :

Rectangle {
    color: "blue"
    width: {
        var w = parent.width / 3;
        console.debug(w);
        return w;
    }
}

Si le script comporte plus de quelques lignes ou s'il peut être utilisé par différents objets, nous recommandons de créer une fonction et de l'appeler comme suit :

function calculateWidth(object : Item) : double
{
    var w = object.width / 3;
    // ...
    // more javascript code
    // ...
    console.debug(w);
    return w;
}

Rectangle {
    color: "blue"
    width: calculateWidth(parent)
}

Notez également qu’il est recommandé d’ajouter des annotations de type à votre fonction afin de faciliter la compréhension et la refactorisation de votre application, car les types des paramètres et des valeurs de retour sont immédiatement visibles dans la signature de la fonction.

Pour les scripts longs, nous plaçons les fonctions dans leur propre fichier JavaScript et les importons comme suit :

import "myscript.js" as Script

Rectangle { color: "blue"; width: Script.calculateWidth(parent) }

Si le code comporte plus d’une ligne et se trouve donc dans un bloc, nous utilisons des points-virgules pour indiquer la fin de chaque instruction :

MouseArea {
    anchors.fill: parent
    onClicked: event => {
        var scenePos = mapToItem(null, event.x, event.y);
        console.log("MouseArea was clicked at scene pos " + scenePos);
    }
}