qmllint

qmllint ist ein Werkzeug, das mit Qt ausgeliefert wird und die syntaktische Gültigkeit von QML-Dateien prüft. Sie können qmllint in Ihr Build-System integrieren, um die Benutzung zu erleichtern. Es warnt auch vor einigen QML Anti-Patterns. Siehe {Konfiguration der qmllint-Warnungen} für die Deaktivierung eines bestimmten Warnungstyps.

Standardmäßig werden einige Probleme zu Warnungen führen, die gedruckt werden. Wenn es mehr Warnungen als ein Limit gibt, das mit --max-warnings konfiguriert werden kann, wird der Exit-Code ungleich Null sein. Geringfügige Probleme (wie z.B. unbenutzte Importe) werden standardmäßig nur als Informationsmeldungen ausgegeben und haben keinen Einfluss auf den Exit-Code. qmllint ist sehr konfigurierbar und erlaubt es, Warnungen zu deaktivieren oder zu ändern, wie sie behandelt werden.

qmllint warnt vor:

• Unqualifizierten Zugriffen auf Eigenschaften
• Verwendung von Signalhandlern ohne ein passendes Signal
• Verwendung von with-Anweisungen in QML
• Probleme im Zusammenhang mit der Kompilierung von QML-Code
• Unbenutzte Importe
• Veraltete Komponenten und Eigenschaften
• Und viele andere Dinge

Siehe QML Lint Warnungen und Fehler, um qmllint Warnungen und Fehler zu beheben.

Um eine Übersicht und Erklärung aller verfügbaren Kommandozeilenoptionen zu erhalten, führen Sie qmllint --help aus.

Compiler-Warnungen

qmllint kann Sie vor Code warnen, der von qmlsc nicht kompiliert werden kann.

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

Verwendung von qmllint mit CMake

Für Projekte, die die qt_add_qml_module() CMake API zur Erstellung von QML-Modulen verwenden, werden automatisch Convenience-Targets wie all_qmllint erstellt. Diese führen qmllint auf allen QML-Dateien eines bestimmten Moduls oder des Projekts aus.

Markieren von Komponenten und Eigenschaften als veraltet

qmllint erlaubt es Ihnen, sowohl Eigenschaften als auch Komponenten als veraltet zu 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)
}

Die Warnungen für veraltete Komponenten werden jedes Mal angezeigt, wenn die Komponente erstellt wird.

Deaktivieren von Warnungen inline

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

Sie können dies am Ende einer Zeile tun, wenn eine einzelne Zeile Warnungen erzeugt:

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 nur // 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 Direktiven. Sie dürfen also einen Kommentar nicht auf diese Weise beginnen, es sei denn, Sie möchten Warnungen aktivieren oder deaktivieren.

Konfigurieren von qmllint-Warnungen

Sie können die Warnungen, die qmllint ausgibt, und deren Schweregrad konfigurieren. Diese Stufen können info, {Warnung}, error oder disable sein. Sie können die Warnungen mit Hilfe der Einstellungsdatei .qmllint.ini oder durch Übergabe von Kommandozeilenoptionen an qmllint anpassen. Kommandozeilenoptionen setzen die Standardeinstellungen und die Einstellungsdatei außer Kraft.

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

Um z.B. Warnungen über Verwerfungen zu deaktivieren, rufen Sie qmllint mit der Option --deprecated=disable auf. Und um unbenutzte Importe in einen Fehler zu verwandeln, übergeben Sie --unused-imports=error.

Eine dauerhafte Anpassung der Warnungen kann durch Modifizierung der Einstellungsdatei erfolgen. Siehe den nächsten Abschnitt über Einstellungsdateien für weitere Details.

Einstellungen

Zusätzlich zur Übergabe von Kommandozeilenoptionen können Sie qmllint auch über eine Einstellungsdatei konfigurieren. Die Kommandozeile --write-defaults erzeugt eine solche Datei für Sie.

Einstellungsdateien heißen .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 auf info, warning, error oder disable gesetzt werden, genau wie bei den Kommandozeilenoptionen.

qmllint sucht automatisch nach einer Einstellungsdatei am Ort der qml-Datei, die gelintet werden soll. Es durchsucht auch alle übergeordneten Verzeichnisse, um diese Datei zu finden und wendet die darin enthaltenen Einstellungen automatisch an. Sie können dieses Verhalten durch die Verwendung von --ignore-settings deaktivieren. Sie können diese Standardeinstellungen jederzeit außer Kraft setzen, indem Sie Befehlszeilenparameter angeben, die Vorrang vor den Warnstufen in den Einstellungen haben.

Einstellungen für Kontexteigenschaften

Kontexteigenschaften können in einer eigenen Einstellungsdatei namentlich definiert oder ignoriert werden. Die Einstellungen für Kontexteigenschaften ermöglichen einen feineren Ansatz zur Deaktivierung unqualifizierter Zugriffswarnungen für die Verwendung von Kontexteigenschaften, während .qmllint.ini nur die Deaktivierung aller unqualifizierten Zugriffswarnungen ermöglicht, möglicherweise einschließlich derjenigen, die sich nicht auf Kontexteigenschaften beziehen.

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

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

Um qmllint-Warnungen über unqualifizierten Zugriff auf einen Kontexteigenschaftsnamen zu deaktivieren, fügen Sie den Kontexteigenschaftsnamen zu disableUnqualifiedAccess hinzu. Trennen Sie mehrere Kontexteigenschaftsnamen durch ein Komma.

Um vor der Verwendung von Kontexteigenschaften zu warnen, fügen Sie den Namen der Kontexteigenschaft zu warnOnUsage hinzu. Trennen Sie mehrere Kontexteigenschaftsnamen durch ein Komma.

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

Skripting

qmllint kann mit der Option --json <file> JSON schreiben oder ausgeben, das gültiges JSON mit Warnmeldungen, Datei- und Zeilenspeicherort der Warnungen und deren Schweregrad zurückgibt. Verwenden Sie den speziellen Dateinamen '-', um in stdout statt in eine Datei zu schreiben. Dies kann verwendet werden, um qmllint einfacher in Ihre Pre-Commit-Hooks oder CI-Tests zu integrieren.