QML-Codierungskonventionen

Dieses Dokument enthält die QML-Codierungskonventionen, an die wir uns in unserer Dokumentation und unseren Beispielen halten und deren Einhaltung wir auch anderen empfehlen.

QML-Objektdeklarationen

In unserer gesamten Dokumentation und unseren Beispielen sind die Attribute von QML-Objekten stets in der folgenden Reihenfolge angeordnet:

• id
• Eigenschaftsdeklarationen
• Signaldeklarationen
• JavaScript-Funktionen
• Objekteigenschaften
• untergeordnete Objekte

Zur besseren Lesbarkeit trennen wir diese verschiedenen Teile durch eine Leerzeile.

Ein hypothetisches QML-Objekt für ein Foto würde beispielsweise so aussehen:

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

Gruppierte Eigenschaften

Wenn Sie mehrere Eigenschaften aus einer Gruppe von Eigenschaften verwenden, sollten Sie die Gruppennotation anstelle der Punktnotation in Betracht ziehen, sofern dies die Lesbarkeit verbessert.

Beispielsweise könnte dies:

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
}

könnte wie folgt geschrieben werden:

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

Unqualifizierter Zugriff

Um die Lesbarkeit und Leistung zu verbessern, sollten Sie Eigenschaften von übergeordneten Komponenten stets explizit über deren ID referenzieren:

Item {
    id: root

    property int rectangleWidth: 50

    Rectangle {
        width: root.rectangleWidth
    }
}

Erforderliche Eigenschaften

Wenn Daten benötigt werden, die außerhalb der Komponente definiert sind, machen Sie dies durch die Verwendung von „Erforderliche Eigenschaften“ explizit. Erforderliche Eigenschaften müssen gesetzt werden, andernfalls schlägt die Erstellung der Komponente fehl. Diese sind unqualifizierten Abfragen vorzuziehen, da sie leistungsfähiger sind und es sowohl Benutzern als auch Tools ermöglichen, den Typ einer externen Eigenschaft zu ermitteln. Zudem beseitigen sie Annahmen, die eine Komponente andernfalls über die Umgebung treffen müsste, in der sie erstellt wird.

Signal-Handler

Verwenden Sie bei der Verarbeitung von Parametern in Signal-Handlern Funktionen, die diese explizit benennen:

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

JavaScript-Code

Zur besseren Lesbarkeit und Wartbarkeit deklarieren wir jede Eigenschaft in der Regel in einer eigenen Zeile, selbst bei einfachen Ausdrücken.

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

Bei Skript-Ausdrücken, die sich über mehrere Zeilen erstrecken, verwenden wir ein Blockformat:

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

Wenn das Skript mehr als ein paar Zeilen lang ist oder von verschiedenen Objekten verwendet werden kann, empfehlen wir, eine Funktion zu erstellen und diese wie folgt aufzurufen:

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

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

Beachten Sie außerdem, dass es empfehlenswert ist, Ihrer Funktion Typangaben hinzuzufügen, um die Anwendung leichter zu verstehen und umzugestalten, da sowohl die Parameter- als auch die Rückgabetypen direkt aus der Funktionssignatur ersichtlich sind.

Bei langen Skripten legen wir die Funktionen in einer eigenen JavaScript-Datei ab und importieren sie wie folgt:

import "myscript.js" as Script

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

Wenn der Code länger als eine Zeile ist und somit in einem Block steht, verwenden wir Semikolons, um das Ende jeder Anweisung zu kennzeichnen:

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