QML-Codierungskonventionen

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

QML-Objekt-Deklarationen

In unserer Dokumentation und in den Beispielen sind die QML-Objektattribute immer in der folgenden Reihenfolge aufgebaut:

• id
• Eigenschaftsdeklarationen
• Signal-Deklarationen
• JavaScript-Funktionen
• Objekt-Eigenschaften
• untergeordnete Objekte

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

Ein hypothetisches Foto-QML-Objekt würde zum Beispiel 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 verwenden, wenn dies die Lesbarkeit verbessert.

Zum Beispiel 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, referenzieren Sie Eigenschaften von übergeordneten Komponenten immer explizit mit ihrer ID:

Item {
    id: root

    property int rectangleWidth: 50

    Rectangle {
        width: root.rectangleWidth
    }
}

Erforderliche Eigenschaften

Wenn Sie Daten benötigen, die außerhalb der Komponente definiert sind, machen Sie dies durch die Verwendung von erforderlichen Eigenschaften deutlich. Erforderliche Eigenschaften müssen gesetzt werden, sonst schlägt die Erstellung der Komponente fehl. Diese sind unqualifizierten Lookups vorzuziehen, da sie leistungsfähiger sind und es sowohl den Benutzern als auch den Werkzeugen ermöglichen, Rückschlüsse auf den Typ einer externen Eigenschaft zu ziehen. Außerdem entfallen dadurch Annahmen, die eine Komponente ansonsten über die Umgebung, in der sie erstellt wird, machen muss.

Signal-Handler

Bei der Behandlung von Parametern in Signalhandlern sollten Funktionen verwendet werden, die diese explizit benennen:

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

JavaScript-Code

Zur besseren Lesbarkeit und Wartbarkeit deklarieren wir im Allgemeinen jede Eigenschaft in einer eigenen Zeile, auch bei einfachen Ausdrücken.

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

Für Skriptausdrücke, 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 sie so 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 auch, dass es empfehlenswert ist, Typ-Annotationen zu Ihrer Funktion hinzuzufügen, um Ihre Anwendung leichter zu überdenken und zu refaktorisieren, da sowohl Parameter- als auch Rückgabetypen unmittelbar aus der Funktionssignatur ersichtlich sind.

Bei langen Skripten legen wir die Funktionen in eine eigene JavaScript-Datei 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 innerhalb eines Blocks 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);
    }
}

Verwandte Informationen

• Best Practices für QML und Qt Quick