Meilleures pratiques pour QML et Qt Quick Scalabilité

Conventions de codage QML

Ce document contient les conventions de codage QML que nous suivons dans notre documentation et nos exemples et que nous recommandons aux autres de suivre.

Déclarations d'objets QML

Dans notre documentation et 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 hypothétique objet QML 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 d'un groupe de propriétés, envisagez d'utiliser la notation de groupe au lieu de la notation par points si cela améliore la lisibilité.

Par exemple, this :

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 être écrit comme suit :

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, il convient de toujours référencer les propriétés des composants parents par leur identifiant de manière explicite :

Item {
    id: root

    property int rectangleWidth: 50

    Rectangle {
        width: root.rectangleWidth
    }
}

Propriétés requises

Lorsque vous avez besoin de données définies en dehors du composant, rendez-les explicites en utilisant les propriétés requises. Les propriétés requises doivent être définies, faute de quoi la création du composant échouera. Ces propriétés sont préférables aux recherches non qualifiées car elles sont plus performantes et permettent aux utilisateurs et aux outils de raisonner sur le type d'une propriété externe. En outre, elles éliminent les hypothèses qu'un composant doit faire sur l'environnement dans lequel il est créé.

Gestionnaires de signaux

Lorsque vous traitez des paramètres dans des gestionnaires de signaux, utilisez des fonctions qui les nomment explicitement :

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

Code JavaScript

Pour améliorer la lisibilité et la 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 de bloc :

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

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

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 le raisonnement et la refonte de votre application, puisque les types de paramètres et de retour sont immédiatement visibles à partir de la signature de la fonction.

Pour les longs scripts, nous placerons les fonctions dans leur propre fichier JavaScript et l'importerons comme suit :

import "myscript.js" as Script

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

Si le code dépasse une ligne et se trouve donc dans un bloc, nous utilisons des points-virgules pour indiquer la fin de chaque déclaration :

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

Meilleures pratiques pour QML et Qt Quick Scalabilité

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.