QML Coding Conventions

code style convention.

Article lu fois.

L'auteur

The Qt Company Ltd.

L'article

Publié le 27 décembre 2024 - Mis à jour le 27 décembre 2024

Liens sociaux

QML Coding Conventions▲

This document contains the QML coding conventions that we follow in our documentation and examples and recommend that others follow.

QML Object Declarations▲

Throughout our documentation and examples, QML object attributes are always structured in the following order:

id
property declarations
signal declarations
JavaScript functions
object properties
child objects
states
transitions

For better readability, we separate these different parts with an empty line.

For example, a hypothetical photo QML object would look like this:

Sélectionnez

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 &gt; 200) {
            photoImage.width;
        } else {
            200;
        }
    }

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

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

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

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

Grouped Properties▲

If using multiple properties from a group of properties, consider using group notation instead of dot notation if it improves readability.

For example, this:

Sélectionnez

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
}

could be written like this:

Sélectionnez

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 }
}

Lists▲

If a list contains only one element, we generally omit the square brackets.

For example, it is very common for a component to only have one state.

In this case, instead of:

Sélectionnez

states: [
    State {
        name: "open"
        PropertyChanges { target: container; width: 200 }
    }
]

we will write this:

Sélectionnez

states: State {
    name: "open"
    PropertyChanges { target: container; width: 200 }
}

JavaScript Code▲

If the script is a single expression, we recommend writing it inline:

Sélectionnez

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

If the script is only a couple of lines long, we generally use a block:

Sélectionnez

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

If the script is more than a couple of lines long or can be used by different objects, we recommend creating a function and calling it like this:

Sélectionnez

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

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

For long scripts, we will put the functions in their own JavaScript file and import it like this:

Sélectionnez

import "myscript.js" as Script

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

If the code is longer than one line and hence within a block, we use semicolons to indicate the end of each statement:

Sélectionnez

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

Related Information▲

Vous avez aimé ce tutoriel ? Alors partagez-le en cliquant sur les boutons suivants :