qmlformat

qmlformat ist ein Werkzeug, das QML-Dateien automatisch in Übereinstimmung mit den QML-Codierungskonventionen formatiert.

Verwendung:
qmlformat[Optionen] Argumente

Optionen und Einstellungen

qmlformat kann über Kommandozeilenoptionen konfiguriert werden. Es gibt zwei Gruppen von Optionen: Diejenigen, die sich direkt auf die Formatierung beziehen, und diejenigen, die das Verhalten des Werkzeugs steuern.

Die folgenden Optionen beeinflussen nur das Verhalten des Werkzeugs:

Befehlszeile Option	Beschreibung
`-h`, `--help`	Zeigt die Hilfe zu den Kommandozeilenoptionen an.
`--help-all`	Zeigt Hilfe an, einschließlich allgemeiner Qt-Optionen.
`-v`, `--version`	Zeigt Versionsinformationen an.
`-V`, `--verbose`	Ausführlicher Modus. Gibt detailliertere Informationen aus.
`--write-defaults`	Schreibt die Standardeinstellungen in die Datei .qmlformat.ini und beendet sich (Achtung: Dies überschreibt alle vorhandenen Einstellungen und Kommentare!)
`--output-options`		Gibt alle verfügbaren Optionen, ihren Standardwert und einen Hinweis auf Werte oder Typen aus
`--ignore-settings`	Ignoriert alle Einstellungsdateien und berücksichtigt nur die Kommandozeilenoptionen
`-i`, `--inplace`	Editiert die Datei an Ort und Stelle, anstatt sie auf stdout auszugeben.
`-f`, `--force`	Fortfahren, auch wenn ein Fehler aufgetreten ist.
`-F`, `--files <file>`	Alle in der Datei aufgelisteten Dateien an Ort und Stelle formatieren

Die nächste Gruppe von Optionen steuert, wie die Dateien formatiert werden sollen, und kann zusätzlich auch über eine Einstellungsdatei gesteuert werden:

Kommandozeilenoption	Einstellung Name	Standardzustand/Wert	Beschreibung
`-t`, `--tabs`	Tabs verwenden	deaktiviert/false	Tabulatoren anstelle von Leerzeichen verwenden. In einem Kommandozeilenaufruf kann das Verhalten durch Übergabe des Flags aktiviert werden. In einer Einstellungsdatei kann das Verhalten aktiviert werden, indem die entsprechende Variable auf "true" gesetzt wird.
`-w`, `--indent-width <width>`	Einzugsbreite	4	Wie viele Leerzeichen beim Einrücken verwendet werden.
`-W`, `--column-width <width>`	MaxColumnWidth	-1	Bricht die Zeile in mehrere Zeilen um, wenn sie die angegebene Breite überschreitet. Verwenden Sie -1, um den Zeilenumbruch zu deaktivieren. (Voreinstellung).
`-n`, `--normalize`	NormalizeOrder	deaktiviert/false	Ordnet die Attribute der Objekte gemäß den QML Coding Guidelines neu an. In einem Kommandozeilenaufruf kann das Verhalten durch Übergabe des Flags aktiviert werden. In einer Einstellungsdatei kann das Verhalten aktiviert werden, indem die entsprechende Variable auf "true" gesetzt wird.
`-l`, `--newline <newline>`	ZeilenumbruchTyp	nativ	Setzt das zu verwendende Zeilenumbruchformat außer Kraft (`native`, `macos`, `unix`, `windows`).
`-S`, `--sort-imports`	SortImports	deaktiviert/false	Sortiert Importe alphabetisch (Achtung: Dies kann die Semantik verändern, wenn ein bestimmter Name Typen in mehreren Modulen identifiziert!) In einem Befehlszeilenaufruf kann das Verhalten durch Übergabe des Flags aktiviert werden. In einer Einstellungsdatei kann das Verhalten aktiviert werden, indem die entsprechende Variable auf "true" gesetzt wird.
`--objects-spacing`	ObjekteAbstand	deaktiviert/false	Leerzeichen zwischen den Objekten sicherstellen (funktioniert nur mit `normalize`). In einem Befehlszeilenaufruf kann das Verhalten durch Übergabe des Flags aktiviert werden. In einer Einstellungsdatei kann das Verhalten aktiviert werden, indem die entsprechende Variable auf "true" gesetzt wird.
`--functions-spacing`	FunktionenAbstand	deaktiviert/false	Leerzeichen zwischen Funktionen sicherstellen (funktioniert nur mit `normalize`). In einem Befehlszeilenaufruf kann das Verhalten durch Übergabe des Flags aktiviert werden. In einer Einstellungsdatei kann das Verhalten aktiviert werden, indem die entsprechende Variable auf "true" gesetzt wird.
`--group-attributes-together`	GroupAttributesTogether	deaktiviert/false	Ordnet und gruppiert die Attribute der Objekte gemäß den QML-Codierrichtlinien neu. Impliziert `--normalize`. In einem Kommandozeilenaufruf kann das Verhalten durch Übergabe des Flags aktiviert werden. In einer Einstellungsdatei kann das Verhalten aktiviert werden, indem die entsprechende Variable auf "true" gesetzt wird.
`--single-line-empty-objects`	SingleLineEmptyObjects	deaktiviert/false	Leere Objekte in eine einzige Zeile schreiben (funktioniert nur mit `normalize`). In einem Befehlszeilenaufruf kann das Verhalten durch Übergabe des Flags aktiviert werden. In einer Einstellungsdatei kann das Verhalten aktiviert werden, indem die entsprechende Variable auf "true" gesetzt wird.
`--semicolon-rule`	SemikolonRegel	immer	Passt das Hinzufügen von Semikolons am Ende von JS-Anweisungen an (`always`, `essential`). Hinweis: Siehe Semikolon-Regel für weitere Einzelheiten.

Argumente

Argumente:
Dateinamen

Einzelheiten

qmlformat ist flexibel und kann nach Ihren Bedürfnissen konfiguriert werden.

Ausgabe

qmlformat schreibt die formatierte Version der Datei auf stdout. Wenn Sie möchten, dass Ihre Datei an Ort und Stelle aktualisiert wird, geben Sie das Flag -i an.

Gruppierung von Eigenschaften, Funktionen und Signalen

Mit dem Flag -n oder --normalize gruppiert qmlformat alle Eigenschaften, Funktionen und Signale zusammen, anstatt die von Ihnen angegebene Reihenfolge beizubehalten.

Einstellungsdatei

Sie können qmlformat konfigurieren, indem Sie eine Einstellungsdatei .qmlformat.ini in Ihren Projektquelltext oder in die übergeordneten Verzeichnisse Ihres Projektquelltextordners einfügen. Eine Standard-Einstellungsdatei kann durch die Übergabe des Flags --write-defaults erhalten werden. Dies erzeugt die Datei .qmlformat.ini im aktuellen Arbeitsverzeichnis.

Achtung: --write-defaults überschreibt alle vorhandenen Einstellungen und Kommentare!

Formatierung einer Liste von Dateien

Während Sie eine Liste von Dateien, die formatiert werden sollen, als Argumente übergeben können, bietet qmlformat -F die Möglichkeit, eine Gruppe von Dateien zu formatieren, die in einer Datei gespeichert sind. In diesem Fall wird die Formatierung an Ort und Stelle durchgeführt.

// FileList.txt
main.qml
mycomponent.qml

Dann verwenden Sie es wie

qmlformat -F FileList.txt

Hinweis: Wenn die Datei einen ungültigen Eintrag enthält, z. B. einen Dateipfad, der nicht existiert, oder einen gültigen Dateipfad, aber der Inhalt ist ein ungültiges qml-Dokument, dann wird qmlformat für diesen bestimmten Eintrag einen Fehler anzeigen. Die gültigen Dateieinträge werden jedoch weiterhin formatiert.

Warnung: Wenn Sie die Option -F angeben, ignoriert qmlformat die Positionsargumente.

Semikolon-Regel

Mit der Option --semicolon-rule können Sie das Hinzufügen von Semikolons am Ende von JS-Anweisungen anpassen. Die folgenden Werte werden akzeptiert:

always - Immer Semikolons hinzufügen (Standard).
essential - Entfernen Sie Semikolons, es sei denn, ihr Weglassen würde Probleme verursachen.

Deaktivieren der Formatierung mit Kommentaren

Sie können qmlformat vorübergehend durch spezielle Kommentare deaktivieren.

// qmlformat off schaltet die Formatierung von dieser Zeile an aus
// qmlformat on schaltet die Formatierung ein, nachdem Sie sie ausgeschaltet haben

Auf diese Weise können Sie handoptimierten Code oder komplexe Strukturen beibehalten, ohne qmlformat ihr Layout zu verändern. Die Formatierung bleibt bis zum nächsten // qmlformat on Kommentar ausgeschaltet, oder bis zum Ende der Datei, wenn keine Wiedereinschaltung gefunden wird.

Hinweis: Direktiven müssen in einer eigenen Zeile stehen.

Hinweis: Verschachtelte Direktiven werden nicht unterstützt. Nur die erste // qmlformat off und die nächste // qmlformat on werden berücksichtigt. Alle weiteren Direktiven innerhalb eines deaktivierten Bereichs werden ignoriert.

Hinweis: Die Direktiven werden im normalisierten Formatierungsmodus ignoriert, wenn sortImports aktiviert ist, oder wenn eine Option verwendet wird, die das Originaldokument neu anordnet. In diesen Fällen wird die Formatierung immer angewendet.

qmltc qmltyperegistrar

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