qmllint

qmllint ist ein im Lieferumfang von Qt enthaltenes Tool, das die syntaktische Gültigkeit von QML-Dateien überprüft. Sie können qmllint zur einfacheren Nutzung in Ihr Build-System integrieren. Es warnt zudem vor bestimmten QML-Anti-Patterns. Informationen zum Deaktivieren eines bestimmten Warnungstyps finden Sie unter „Konfigurieren von qmllint-Warnungen “.

Standardmäßig führen einige Probleme zu Warnungen, die ausgegeben werden. Wenn mehr Warnungen auftreten als ein mit --max-warnings konfigurierbares Limit zulässt, ist der Beendigungscode ungleich Null. Kleinere Probleme (wie beispielsweise ungenutzte Importe) werden standardmäßig jedoch nur als Informationsmeldungen ausgegeben und haben keinerlei Einfluss auf den Exit-Code. qmllint ist sehr flexibel konfigurierbar und ermöglicht es, Warnungen zu deaktivieren oder deren Behandlung anzupassen.

qmllint warnt vor:

• Unqualifizierte Zugriffe auf Eigenschaften
• Verwendung von Signal-Handlern ohne passendes Signal
• Verwendung von `with`-Anweisungen in QML
• Probleme im Zusammenhang mit der Kompilierung von QML-Code
• Ungenutzte Importe
• Veraltete Komponenten und Eigenschaften
• Und vieles mehr

Informationen zur Behebung von qmllint-Warnungen und -Fehlern finden Sie unter „QML Lint-Warnungen und -Fehler “.

Um eine Übersicht und Erläuterung aller verfügbaren Befehlszeilenoptionen zu erhalten, führen Sie „ qmllint --help “ aus.

Compiler-Warnungen

qmllint kann Sie auf Code hinweisen, der von qmlsc nicht kompiliert werden kann.

Diese Warnungen sind standardmäßig nicht aktiviert. Um sie zu aktivieren, konfigurieren Sie qmllint so, dass die Kategorie „Compiler-Warnungen“ verwendet wird.

Verwendung von qmllint mit CMake

Bei Projekten, die die CMake-API `qt_add_qml_module()` zum Erstellen von QML-Modulen verwenden, werden automatisch Komfortziele wie ` all_qmllint ` erstellt. Diese führen `qmllint` für alle QML-Dateien eines bestimmten Moduls oder des gesamten Projekts aus.

Automatisches Anwenden von Korrekturvorschlägen

Die Behebung von Warnungen, die von qmllint ausgegeben werden, kann einen erheblichen manuellen Bearbeitungs- und Überprüfungsaufwand erfordern. Einige der von qmllint ausgegebenen Warnungen enthalten einen zugehörigen Korrekturvorschlag, der ausgelöst werden kann, um die Warnung automatisch zu beheben. Um diese Korrekturen auszulösen, haben Sie folgende Möglichkeiten:

• --fix an qmllint übergeben.
• Aktivieren Sie die Korrekturen über Ihre IDE.

Das gleichzeitige Anwenden aller Korrekturvorschläge in Ihrem gesamten Projekt kann eine zu große Änderung darstellen. Daher wird empfohlen, die Arbeit in überschaubare Teile aufzuteilen. Sie können die Arbeit aufteilen, indem Sie nur eine Teilmenge der Dateien prüfen lassen oder nur bestimmte Kategorien ausführen.

qmllint --only-explicit-categories --ignore-settings --fix --unqualified=warning <files>

Dadurch werden die verfügbaren Korrekturen nur für unqualifizierte Zugriffe angewendet, indem alle anderen Warnkategorien mit ` --only-explicit-categories ` und ` --ignore-settings` deaktiviert werden.

Wenn Sie sich bei einer Änderung unsicher sind, verwenden Sie „ --dry-run “, um das Ergebnis eines Durchlaufs sicher anzuzeigen, ohne die Dateien tatsächlich zu ändern.

Komponenten und Eigenschaften als veraltet markieren

Mit qmllint können Sie sowohl Eigenschaften als auch Komponenten als veraltet markieren:

@Deprecated { reason: "Use NewCustomText instead" }
Text {
    @Deprecated { reason: "Use newProperty instead" }
    property int oldProperty
    property int newProperty
    Component.onCompleted: console.log(oldProperty);  // Warning: XY.qml:8:40: Property "oldProperty" is deprecated (Reason: Use newProperty instead)
}

Warnungen zur Veralterung von Komponenten werden jedes Mal angezeigt, wenn die Komponente erstellt wird.

Warnungen inline deaktivieren

Sie können Warnungen in einer Datei jederzeit vorübergehend mit ` // qmllint disable` deaktivieren.

Dies können Sie am Ende einer Zeile tun, wenn eine einzelne Zeile Warnungen auslöst:

Item {
    property string foo
    Item {
        property string bar: foo // qmllint disable unqualified
    }
}

Alternativ können Sie Kommentare für einen Zeilenblock deaktivieren, indem Sie den Kommentar in eine Zeile setzen, die ausschließlich „ // qmllint disable “ enthält, und den Block mit „ // qmllint enable “ beenden:

Item {
    property string foo
    Item {
        // qmllint disable unqualified
        property string bar: foo
        property string bar2: foo
        // qmllint enable unqualified
    }
}

qmllint interpretiert alle einzeiligen Kommentare, die mit „ qmllint “ beginnen, als Anweisungen. Daher sollten Sie einen Kommentar nicht auf diese Weise beginnen, es sei denn, Sie möchten Warnungen aktivieren oder deaktivieren.

Konfigurieren der qmllint-Warnungen

Sie können die von qmllint ausgegebenen Warnungen und deren Schweregrad konfigurieren. Diese Stufen können info, {warning}, error oder disable sein. Sie können die Warnungen über die Konfigurationsdatei „ .qmllint.ini “ oder durch Übergabe von Befehlszeilenoptionen an qmllint anpassen. Befehlszeilenoptionen haben Vorrang vor den Standardeinstellungen und der Konfigurationsdatei.

Um die Schwere einer Warnungskategorie über die Befehlszeile anzupassen, setzen Sie die entsprechende Befehlszeilenoption auf die gewünschte Stufe.

Um beispielsweise Warnungen zu veralteten Funktionen zu deaktivieren, rufen Sie qmllint mit der Option „ --deprecated=disable “ auf. Und um ungenutzte Importe als Fehler auszuweisen, übergeben Sie „ --unused-imports=error “.

Eine dauerhaftere Anpassung der Warnungen ist durch Ändern der Konfigurationsdatei möglich. Weitere Details finden Sie im folgenden Abschnitt über „ Settings “-Dateien.

Einstellungen

Zusätzlich zur Übergabe von Befehlszeilenoptionen können Sie qmllint auch über eine Konfigurationsdatei konfigurieren. Der Befehl „ --write-defaults “ erstellt eine solche Datei für Sie.

Einstellungsdateien tragen den Namen „ .qmllint.ini “ und sehen wie folgt aus:

[General]
DisableDefaultImports=false
MaxWarnings=-1

[Warnings]
AccessSingletonViaObject=warning
AliasCycle=warning
AssignmentInCondition=warning
AttachedPropertyReuse=disable
BadSignalHandlerParameters=warning
Comma=warning
CompilerWarnings=disable
ComponentChildrenCount=warning
ConfusingExpressionStatement=warning
ConfusingMinuses=warning
ConfusingPluses=warning
ContextProperties=warning
Deprecated=warning
DuplicateEnumEntries=warning
DuplicateImport=warning
DuplicateInlineComponent=warning
DuplicatePropertyBinding=warning
DuplicatedName=warning
EnumEntryMatchesEnum=warning
EnumsAreNotTypes=warning
EqualityTypeCoercion=warning
Eval=warning
FunctionUsedBeforeDeclaration=disable
ImportFailure=warning
IncompatibleType=warning
InheritanceCycle=warning
InvalidLintDirective=warning
LintPluginWarnings=disable
LiteralConstructor=warning
MissingEnumEntry=warning
MissingProperty=warning
MissingType=warning
MultilineStrings=info
NonListProperty=warning
NonRootEnum=warning
PreferNonVarProperties=warning
PrefixedImportType=warning
PropertyAliasCycles=warning
QtDesignStudio.FunctionsNotSupportedInQmlUi=warning
QtDesignStudio.ImperativeCodeNotEditableInVisualDesigner=warning
QtDesignStudio.InvalidIdeInVisualDesigner=warning
QtDesignStudio.ReferenceToParentItemNotSupportedByVisualDesigner=warning
QtDesignStudio.UnsupportedRootTypeInQmlUi=warning
QtDesignStudio.UnsupportedTypeInQmlUi=warning
Quick.Anchors=warning
Quick.AttachedPropertyReuse=disable
Quick.AttachedPropertyType=warning
Quick.Color=warning
Quick.ControlsAttachedPropertyReuse=disable
Quick.ControlsNativeCustomize=warning
Quick.LayoutsPositioning=warning
Quick.PropertyChangesParsed=warning
Quick.StateNoChildItem=warning
Quick.UnexpectedVarType=warning
ReadOnlyProperty=warning
RedundantOptionalChaining=warning
RequiredProperty=warning
RestrictedType=warning
StalePropertyRead=warning
TopLevelComponent=warning
TranslationFunctionMismatch=warning
UncreatableType=warning
UnintentionalEmptyBlock=warning
UnqualifiedAccess=warning
UnreachableCode=warning
UnresolvedAlias=warning
UnresolvedType=warning
UnterminatedCase=warning
UnusedImports=info
UseProperFunction=warning
VarUsedBeforeDeclaration=warning
Void=disable
WithStatement=warning

Die Warnstufen können genau wie bei den Befehlszeilenoptionen auf „ info “, „ warning “, „ error “ oder „ disable “ gesetzt werden.

qmllint sucht automatisch am Speicherort der zu prüfenden QML-Datei nach einer Einstellungsdatei. Dabei durchsucht es auch alle übergeordneten Verzeichnisse, um diese Datei zu finden, und wendet die darin enthaltenen Einstellungen automatisch an. Sie können dieses Verhalten deaktivieren, indem Sie „ --ignore-settings “ verwenden. Sie können diese Standardeinstellungen jederzeit überschreiben, indem Sie Befehlszeilenparameter angeben, die Vorrang vor den Warnstufen in den Einstellungen haben.

Einstellungen für Kontexteigenschaften

Kontext-Eigenschaften können in einer eigenen Einstellungsdatei namentlich definiert oder ignoriert werden. Die Einstellungen für Kontext-Eigenschaften ermöglichen einen feineren Ansatz zum Deaktivieren von Warnungen wegen unqualifizierter Zugriffe bei der Verwendung von Kontext-Eigenschaften, während „ .qmllint.ini “ lediglich die Deaktivierung aller Warnungen wegen unqualifizierter Zugriffe erlaubt, darunter möglicherweise auch solche, die nicht mit Kontext-Eigenschaften zusammenhängen.

Die Einstellungen für Kontexteigenschaften tragen den Namen „ .contextProperties.ini “ und sollten sich im Quellordner Ihres Projekts befinden. Sie sehen wie folgt aus:

[General]
disableUnqualifiedAccess = "myContextProperty1,myContextProperty2"
warnOnUsage = "myContextProperty3,myContextProperty4,myContextProperty5"
disableHeuristic = false

Um qmllint-Warnungen bezüglich des unqualifizierten Zugriffs auf einen Kontext-Eigenschaftsnamen zu deaktivieren, fügen Sie den Namen der Kontext-Eigenschaft zu „ disableUnqualifiedAccess “ hinzu. Trennen Sie mehrere Namen von Kontext-Eigenschaften durch ein Komma.

Um Warnungen bezüglich der Verwendung von Kontexteigenschaften zu erhalten, fügen Sie den Namen der Kontexteigenschaft zu „ warnOnUsage “ hinzu. Trennen Sie mehrere Namen von Kontexteigenschaften durch ein Komma.

Um die qmllint-Heuristik zu steuern, setzen Sie „ disableHeuristic “ auf „ true “ oder „ false “.

Skripting

qmllint kann über die Option „ --json <file> “ JSON schreiben oder ausgeben, wodurch gültiges JSON mit Warnmeldungen, Datei- und Zeilenangaben zu den Warnungen sowie deren Schweregrad zurückgegeben wird. Verwenden Sie den speziellen Dateinamen „-“ um anstelle einer Datei in die Standardausgabe (stdout) zu schreiben. Dies kann genutzt werden, um qmllint einfacher in Ihre Pre-Commit-Hooks oder CI-Tests zu integrieren.