QML-Codierungskonventionen

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

QML-Objekt-Deklarationen

In unserer Dokumentation und unseren 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

Wenn das Skript aus einem einzigen Ausdruck besteht, empfehlen wir, es inline zu schreiben:

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

Wenn das Skript nur ein paar Zeilen lang ist, verwenden wir im Allgemeinen einen Block:

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 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 auch, dass es empfehlenswert ist, Typ-Annotationen zu Ihrer Funktion hinzuzufügen, um Ihre Anwendung einfacher zu überdenken und zu refaktorisieren, da sowohl Parameter- als auch Rückgabetypen sofort 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);
    }
}

Best Practices für QML und Qt Quick

© 2025 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.