qmlformat

qmlformat est un outil qui met automatiquement en forme les fichiers QML conformément aux conventions de codage QML.

Options et paramètres

Vous pouvez configurer qmlformat à l'aide d'options de ligne de commande. Il existe deux groupes d'options : celles qui sont directement liées à la mise en forme et celles qui contrôlent le comportement de l'outil.

Les options suivantes n'affectent que le comportement de l'outil :

Le groupe d’options suivant définit la manière dont les fichiers doivent être formatés ; ces paramètres peuvent également être contrôlés via un fichier de configuration.

Pour les options booléennes, passez l'indicateur sur la ligne de commande ou définissez la variable sur « true » dans le fichier de configuration pour activer le comportement.

Arguments

Utilisation

qmlformat est flexible et peut être configuré selon vos besoins. qmlformat doit être déployé dans un bac à sable, un conteneur ou tout autre environnement sécurisé lorsqu'il est exécuté sur du code non fiable, par exemple lors du formatage de fichiers QML pendant les tests dans un environnement CI public.

Sortie

qmlformat écrit la version formatée du fichier sur stdout. Pour que votre fichier soit mis à jour sur place, spécifiez l'option ` -i `.

Regroupement des propriétés, des fonctions et des signaux

Avec le drapeau « -n » ou « --normalize », qmlformat regroupe et trie toutes les propriétés, fonctions et signaux par nom, au lieu de conserver l'ordre existant.

Par exemple :

import QtQuick

QtObject {
    signal s2()
    property int h
    function z() {}
    property int w
    function y() {}
    id: asdf
    signal s1()

    property Item myItem2: Item {
        TextEdit {}
        Rectangle {}
    }
    property Item myItem: Item {
        Rectangle {}
        TextEdit {}
    }
}

est formaté comme suit :

import QtQuick

QtObject {
    id: asdf

    property int h
    property Item myItem: Item {
        Rectangle {
        }
        TextEdit {
        }
    }
    property Item myItem2: Item {
        TextEdit {
        }
        Rectangle {
        }
    }
    property int w

    signal s1
    signal s2

    function y() {
    }
    function z() {
    }
}

Pour regrouper les attributs sans les trier par nom, utilisez plutôt --group-attributes-together.

Cela formate l'extrait précédent comme suit :

import QtQuick

QtObject {
    id: asdf

    property int h
    property int w
    property Item myItem2: Item {
        TextEdit {
        }
        Rectangle {
        }
    }
    property Item myItem: Item {
        Rectangle {
        }
        TextEdit {
        }
    }

    signal s2
    signal s1

    function z() {
    }
    function y() {
    }
}

Cette option a priorité sur --normalize.

Fichier de paramètres

Vous pouvez configurer qmlformat en incluant un fichier de paramètres (.qmlformat.ini) dans le code source de votre projet ou dans les répertoires parents du dossier contenant ce code. Vous pouvez obtenir un fichier de paramètres par défaut en passant l'indicateur --write-defaults. Cela génère le fichier .qmlformat.ini dans le répertoire de travail actuel.

Mise en forme d’une liste de fichiers

Bien que vous puissiez passer une liste de fichiers à formater en tant qu’arguments, qmlformat propose l’option -F pour formater un ensemble de fichiers stockés dans un fichier. Dans ce cas, le formatage s’effectue in situ.

// FileList.txt
main.qml
mycomponent.qml

Pour utiliser cette liste :

qmlformat -F FileList.txt

Règle relative au point-virgule

L'option --semicolon-rule vous permet de personnaliser l'ajout de points-virgules à la fin des instructions JS.

Les valeurs suivantes sont acceptées :

• always - Toujours ajouter des points-virgules (par défaut).
• essential - Supprimer les points-virgules sauf si leur omission entraîne des problèmes.

Désactivation de la mise en forme avec des commentaires

Vous pouvez désactiver temporairement qmlformat à l'aide de commentaires spéciaux.

• // qmlformat off désactive la mise en forme à partir de cette ligne.
• // qmlformat on réactive la mise en forme après l'avoir désactivée.

Cela vous permet de conserver du code ajusté manuellement ou des structures complexes sans que qmlformat n'en modifie la mise en page. Le formatage reste désactivé jusqu'au prochain commentaire « // qmlformat on », ou jusqu'à la fin du fichier si aucun commentaire de réactivation n'est trouvé.

Gardez à l'esprit les points suivants lorsque vous utilisez des directives de mise en forme :

• Les directives doivent figurer sur une ligne distincte.
• Les directives imbriquées ne sont pas prises en charge. Seules la première directive « // qmlformat off » et la directive « // qmlformat on » suivante sont prises en compte. Toute directive supplémentaire située dans une zone désactivée est ignorée.
• Les directives sont ignorées en mode de mise en forme normalisée, lorsque la directive « sortImports » est activée, ou lorsqu’une option réorganisant le document d’origine est utilisée. Dans ces cas, la mise en forme est toujours appliquée.