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. Voir {Configuration des avertissements qmllint} pour savoir comment désactiver un type d'avertissement spécifique.

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.

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.

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, configurez qmllint pour qu'il utilise la catégorie des avertissements du compilateur.

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.

Configuration des avertissements de qmllint

Vous pouvez configurer les avertissements que qmllint émet et leur niveau de gravité. Ces niveaux peuvent être info, {avertissement}, error, ou disable. Vous pouvez personnaliser les avertissements en utilisant le fichier de configuration .qmllint.ini ou en passant des options de ligne de commande à qmllint. Les options de ligne de commande remplacent la valeur par défaut et le fichier de configuration.

Pour personnaliser le niveau d'une catégorie d'avertissement via la ligne de commande, définissez l'option de ligne de commande correspondante au niveau souhaité.

Par exemple, pour désactiver les avertissements concernant les dépréciations, appelez qmllint avec l'option --deprecated=disable. Et pour transformer les importations inutilisées en erreur, passez l'option --unused-imports=error.

Il est possible de personnaliser les avertissements de manière plus permanente en modifiant le fichier de configuration. Voir la section suivante sur les fichiers de configuration pour plus de détails.

Paramètres

En plus de passer des options de ligne de commande, vous pouvez également configurer qmllint via 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 définis sur info, warning, error, ou disable comme pour les options de la ligne de commande.

qmllint recherchera 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 remplacer 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.

Paramètres des propriétés du contexte

Les propriétés contextuelles peuvent être définies ou ignorées par leur nom dans leur propre fichier de configuration. Les paramètres des propriétés contextuelles permettent une approche plus fine de la désactivation des avertissements d'accès non qualifié pour les utilisations des propriétés contextuelles, alors que .qmllint.ini permet uniquement de désactiver tous les avertissements d'accès non qualifié, y compris potentiellement ceux qui ne sont pas liés aux propriétés contextuelles.

Les paramètres des propriétés de contexte sont nommés .contextProperties.ini et doivent être situés dans le dossier source de votre projet. Ils ressemblent à ceci :

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

Pour désactiver les avertissements de qmllint concernant l'accès non qualifié à un nom de propriété de contexte, ajoutez le nom de la propriété de contexte à disableUnqualifiedAccess. Séparez les noms de propriétés de contexte multiples par une virgule.

Pour avertir de l'utilisation d'une propriété de contexte, ajoutez le nom de la propriété de contexte à warnOnUsage. Séparez les noms de plusieurs propriétés de contexte par une virgule.

Pour contrôler l'heuristique qmllint, définissez disableHeuristic comme true ou false.

Écriture de scripts

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.