qmlformat

qmlformat ist ein Tool, das QML-Dateien automatisch gemäß den QML-Codierungskonventionen formatiert.

Optionen und Einstellungen

Sie können qmlformat mit Befehlszeilenoptionen konfigurieren. Es gibt zwei Gruppen von Optionen: solche, die direkt mit der Formatierung zusammenhängen, und solche, die das Verhalten des Tools steuern.

Die folgenden Optionen wirken sich ausschließlich auf das Verhalten des Tools aus:

Die nächste Gruppe von Optionen legt fest, wie Dateien formatiert werden sollen, und kann auch über eine Einstellungsdatei gesteuert werden.

Bei booleschen Optionen übergeben Sie das Flag über die Befehlszeile oder setzen Sie die Variable in der Einstellungsdatei auf „ true “, um das Verhalten zu aktivieren.

Argumente

Verwendung

qmlformat ist flexibel und lässt sich an Ihre Bedürfnisse anpassen. qmlformat sollte in einer Sandbox, einem Container oder einer anderen sicheren Umgebung eingesetzt werden, wenn es mit nicht vertrauenswürdigem Code ausgeführt wird, beispielsweise beim Formatieren von QML-Dateien während des Testens in einer öffentlichen CI-Umgebung.

Ausgabe

qmlformat schreibt die formatierte Version der Datei in die Standardausgabe (stdout). Um Ihre Datei direkt zu aktualisieren, geben Sie das Flag „ -i “ an.

Eigenschaften, Funktionen und Signale gruppieren

Mit dem Flag „ -n “ oder „ --normalize “ gruppiert und sortiert `qmlformat` alle Eigenschaften, Funktionen und Signale nach Namen, anstatt die bestehende Reihenfolge beizubehalten.

Beispiel:

import QtQuick

QtObject {
    signal s2()
    property int h
    function z() {}
    property int w
    function y() {}
    id: asdf
    signal s1()

    property Item myItem2: Item {
        TextEdit {}
        Rectangle {}
    }
    property Item myItem: Item {
        Rectangle {}
        TextEdit {}
    }
}

wird wie folgt formatiert:

import QtQuick

QtObject {
    id: asdf

    property int h
    property Item myItem: Item {
        Rectangle {
        }
        TextEdit {
        }
    }
    property Item myItem2: Item {
        TextEdit {
        }
        Rectangle {
        }
    }
    property int w

    signal s1
    signal s2

    function y() {
    }
    function z() {
    }
}

Um die Attribute zu gruppieren, ohne nach Namen zu sortieren, verwenden Sie stattdessen „ --group-attributes-together “.

Dadurch wird der vorherige Codeausschnitt wie folgt formatiert:

import QtQuick

QtObject {
    id: asdf

    property int h
    property int w
    property Item myItem2: Item {
        TextEdit {
        }
        Rectangle {
        }
    }
    property Item myItem: Item {
        Rectangle {
        }
        TextEdit {
        }
    }

    signal s2
    signal s1

    function z() {
    }
    function y() {
    }
}

Diese Option hat Vorrang vor „ --normalize “.

Einstellungsdatei

Sie können qmlformat konfigurieren, indem Sie eine Einstellungsdatei (.qmlformat.ini) in Ihren Projektquellcode oder in die übergeordneten Verzeichnisse Ihres Projektquellordners einbinden. Eine Standard-Einstellungsdatei erhalten Sie, indem Sie das Flag „ --write-defaults “ übergeben. Dadurch wird die Datei „ .qmlformat.ini “ im aktuellen Arbeitsverzeichnis generiert.

Formatieren einer Dateiliste

Sie können zwar eine Liste der zu formatierenden Dateien als Argumente übergeben, qmlformat bietet jedoch die Option „ -F “, um eine Reihe von Dateien zu formatieren, die in einer Datei gespeichert sind. In diesem Fall erfolgt die Formatierung an Ort und Stelle.

// FileList.txt
main.qml
mycomponent.qml

So verwenden Sie diese Liste:

qmlformat -F FileList.txt

Semikolon-Regel

Mit der Option „ --semicolon-rule “ können Sie das Hinzufügen von Semikolons am Ende von JS-Anweisungen individuell anpassen.

Folgende Werte sind zulässig:

• always - Immer Semikolons hinzufügen (Standard).
• essential - Semikolons entfernen, es sei denn, deren Weglassen würde zu Problemen führen.

Deaktivieren der Formatierung mit Kommentaren

Sie können `qmlformat` mithilfe spezieller Kommentare vorübergehend deaktivieren.

• // qmlformat off Deaktiviert die Formatierung ab dieser Zeile.
• // qmlformat on Schaltet die Formatierung wieder ein, nachdem Sie sie deaktiviert haben.

Auf diese Weise können Sie manuell angepassten Code oder komplexe Strukturen beibehalten, ohne dass qmlformat deren Layout verändert. Die Formatierung bleibt deaktiviert, bis der nächste Kommentar „ // qmlformat on “ auftritt oder bis zum Ende der Datei, falls kein „re-enable“ gefunden wird.

Beachten Sie bei der Verwendung von Formatierungsanweisungen Folgendes:

• Anweisungen müssen in einer eigenen Zeile stehen.
• Verschachtelte Anweisungen werden nicht unterstützt. Es werden nur das erste ` // qmlformat off ` und das darauf folgende ` // qmlformat on ` berücksichtigt. Alle weiteren Anweisungen innerhalb eines deaktivierten Bereichs werden ignoriert.
• Anweisungen werden im normalisierten Formatierungsmodus ignoriert, wenn „ sortImports “ aktiviert ist oder wenn eine Option verwendet wird, die die Reihenfolge des Originaldokuments ändert. In diesen Fällen wird die Formatierung immer angewendet.