qmllint

qmllint est un outil fourni avec Qt, qui vérifie la validité syntaxique des fichiers QML. Vous pouvez intégrer qmllint dans votre système de construction pour en faciliter l'utilisation. Il vous avertit également de l'existence de certains anti-modèles QML. Si vous souhaitez désactiver un type d'avertissement spécifique, vous pouvez trouver le drapeau approprié en passant --help sur la ligne de commande.

Par défaut, certains problèmes donneront lieu à des avertissements qui seront imprimés. S'il y a plus d'avertissements qu'une limite qui peut être configurée avec --max-warnings, le code de sortie sera différent de zéro. Les problèmes mineurs (tels que les importations inutilisées) ne sont que des messages d'information par défaut et n'affecteront jamais le code de sortie. qmllint est très configurable et permet de désactiver les avertissements ou de modifier la façon dont ils sont traités. Les utilisateurs peuvent librement transformer n'importe quel problème en avertissement, en message d'information, ou les désactiver complètement.

qmllint émet des avertissements à propos de :

  • Accès non qualifié aux propriétés
  • L'utilisation de gestionnaires de signaux sans signal correspondant
  • L'utilisation d'instructions "with" en QML
  • Problèmes liés à la compilation du code QML
  • Importations non utilisées
  • Composants et propriétés obsolètes
  • Et bien d'autres choses encore

Voir Avertissements et erreurs de QML Lint pour savoir comment corriger les avertissements et les erreurs de qmllint.

Note : Pour que qmllint fonctionne correctement, il a besoin d'informations sur les types. Ces informations sont fournies par les modules QML dans les chemins d'importation. Le répertoire actuel, ainsi que les chemins d'importation pour les types intégrés de Qt, sont utilisés par défaut comme chemins d'importation. Pour ajouter d'autres chemins d'importation qui ne sont pas inclus par défaut, ajoutez-les via le drapeau -I.

Pour obtenir une vue d'ensemble et une explication de toutes les options de ligne de commande disponibles, exécutez qmllint --help.

Avertissements du compilateur

qmllint peut vous avertir de la présence de code qui ne peut pas être compilé par qmlsc.

Ces avertissements ne sont pas activés par défaut. Pour les activer, spécifiez --compiler warning ou ajustez votre fichier de configuration en conséquence.

Utiliser qmllint avec CMake

Pour les projets utilisant l'API CMake qt_add_qml_module() pour créer des modules QML, des cibles de commodité telles que all_qmllint sont créées automatiquement. Celles-ci exécutent qmllint sur tous les fichiers QML d'un module spécifique ou du projet.

Marquer les composants et les propriétés comme étant obsolètes

qmllint vous permet de marquer les propriétés et les composants comme obsolètes :

@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)
}

Les avertissements de dépréciation pour les composants seront affichés à chaque fois que le composant est créé.

Désactivation des avertissements en ligne

Vous pouvez à tout moment désactiver temporairement les avertissements dans un fichier en utilisant // qmllint disable.

Vous pouvez le faire à la fin d'une ligne lorsqu'une seule ligne produit des avertissements :

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

Vous pouvez également désactiver les commentaires pour un bloc de lignes en plaçant le commentaire dans une ligne contenant uniquement // qmllint disable, en terminant le bloc par // qmllint enable:

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

qmllint interprète tous les commentaires d'une seule ligne commençant par qmllint comme des directives. Vous ne pouvez donc pas commencer un commentaire de cette manière, à moins que vous ne souhaitiez activer ou désactiver les avertissements.

Note : Comme dans les exemples ci-dessus, il est préférable de spécifier explicitement l'avertissement ou une liste d'avertissements que vous souhaitez désactiver plutôt que de désactiver tous les avertissements. Pour ce faire, il suffit d'énumérer les catégories d'avertissements après qmllint disable (les noms sont les mêmes que ceux des options énumérées dans --help).

Paramètres

Outre les options de la ligne de commande, vous pouvez également configurer qmllint à l'aide d'un fichier de configuration. La ligne de commande --write-defaults en génère un pour vous.

Les fichiers de configuration sont nommés .qmllint.ini et ressemblent à ceci :

[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

Les niveaux d'avertissement peuvent être fixés à info, warning ou disable comme pour les options de la ligne de commande.

qmllint recherche automatiquement un fichier de configuration à l'emplacement du fichier qml en cours d'analyse. Il recherche également ce fichier dans tous les répertoires parents et applique automatiquement les paramètres qu'il contient. Vous pouvez désactiver ce comportement en utilisant --ignore-settings. Vous pouvez toujours ignorer ces valeurs par défaut en spécifiant des paramètres de ligne de commande qui ont la priorité sur les niveaux d'avertissement dans les paramètres.

Script

qmllint peut écrire ou produire du JSON via l'option --json <file> qui renverra du JSON valide avec les messages d'avertissement, l'emplacement du fichier et de la ligne des avertissements, et leur niveau de gravité. Utilisez le nom de fichier spécial '-' pour écrire sur stdout au lieu d'un fichier. Ceci peut être utilisé pour intégrer plus facilement qmllint dans vos hooks pre-commit ou vos tests CI.

Voir aussi Fichiers de description de type et Qt Quick Outils et utilitaires.

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