Back to Qt.io
Contact Us Blog Download Qt
Sur cette page

Exposition de QtAbstractListModel à QML Conventions de codage QML

Bonnes pratiques pour le QML et Qt Quick

Malgré tous les avantages offerts par QML et Qt Quick, leur utilisation peut s'avérer complexe dans certaines situations. Les sections suivantes détaillent certaines des meilleures pratiques qui vous aideront à obtenir de meilleurs résultats lors du développement d'applications.

Privilégiez les contrôles intégrés aux contrôles d’interface utilisateur personnalisés

Une interface utilisateur fluide et moderne est la clé du succès de toute application dans le monde d'aujourd'hui, et c'est là que QML prend tout son sens pour un concepteur ou un développeur. Qt propose les contrôles d'interface utilisateur les plus basiques nécessaires pour créer une interface fluide et moderne. Il est recommandé de consulter cette liste de contrôles d'interface utilisateur avant de créer votre propre contrôle personnalisé.

Outre ces contrôles d’interface utilisateur de base proposés par Qt Quick, un ensemble complet de contrôles est également disponible sur Qt Quick Controls. Ils répondent aux cas d’utilisation les plus courants sans aucune modification et offrent bien plus de possibilités grâce à leurs options de personnalisation. En particulier, Qt Quick Controls propose des options de mise en forme qui s’alignent sur les dernières tendances en matière de conception d’interface utilisateur. Ce n’est que si ces contrôles d’interface utilisateur ne répondent pas aux besoins de votre application qu’il est recommandé de créer un contrôle personnalisé.

Vous pouvez utiliser ces contrôles lors de la conception d'interfaces utilisateur dans Qt Design Studio. De plus, cet outil propose des animations basées sur une timeline, des effets visuels, des mises en page et un aperçu en direct pour le prototypage d'applications.

Conventions de codage

Voir les conventions de codage QML.

Regroupement des ressources de l'application

La plupart des applications s'appuient sur des ressources, telles que des images et des icônes, pour offrir une expérience utilisateur riche. Il est souvent difficile de rendre ces ressources accessibles à l'application, quel que soit le système d'exploitation cible. La plupart des systèmes d'exploitation courants appliquent des politiques de sécurité qui restreignent l'accès au système de fichiers, ce qui complique le chargement de ces ressources. Comme alternative, Qt propose son propre système de ressources intégré au binaire de l'application, permettant d'accéder aux ressources de l'application quel que soit le système d'exploitation cible.

Par exemple, pour un projet C++, considérons la structure de répertoires suivante :

MyModule
├── images
│   ├── image1.png
│   └── image2.png
├── CMakeLists.txt
└── main.qml

Vous pouvez représenter cette structure sous la forme d’un module QML CMake de la manière suivante :

qt_add_qml_module(my_module
   URI MyModule
   VERSION 1.0
   QML_FILES
       main.qml
   RESOURCES
       images/image1.png
       images/image2.png
   # ...
)

Tous les fichiers QML répertoriés sous ` QML_FILES ` seront automatiquement précompilés.

Vous devez conserver les fichiers QML dans le même répertoire que le fichier CMakeLists.txt contenant la directive ` qt_add_qml_module`. Sinon, leurs importations implicites différeront de celles des modules QML auxquels ils appartiennent. C’est une source fréquente d’erreurs.

Séparer l’interface utilisateur de la logique métier

L'un des principaux objectifs que la plupart des développeurs d'applications souhaitent atteindre est de créer une application facile à maintenir. L'un des moyens d'y parvenir consiste à séparer l'interface utilisateur (le front-end) de la logique métier (le back-end). Voici quelques raisons pour lesquelles l'interface utilisateur d'une application devrait être écrite en QML :

  • Les langages déclaratifs sont particulièrement adaptés à la définition d’interfaces utilisateur.
  • Le code QML est plus simple à écrire, car il est moins verbeux que le C++ et n’est pas fortement typé. Cela en fait également un excellent langage pour la création de prototypes, une qualité essentielle lors de la collaboration avec des concepteurs, par exemple.
  • JavaScript peut facilement être utilisé dans QML pour répondre à des événements.

Les langages fortement typés, tels que le C++, sont les mieux adaptés à la logique métier d’une application, c’est-à-dire le backend. Généralement, ce type de code effectue des tâches telles que des calculs complexes ou le traitement de données, qui sont plus rapides dans les langages fortement typés qu’en QML.

Qt propose différentes approches pour intégrer QML à un langage fortement typé au sein d’une application. Un cas d’utilisation typique consiste à afficher une liste de données dans une interface utilisateur. Si l’ensemble de données est statique, simple et de petite taille, un modèle écrit en QML peut suffire.

L'extrait de code suivant présente des exemples de modèles écrits en QML :

model: [ "Item 1", "Item 2", "Item 3" ]

model: 10

Pour des ensembles de données plus volumineux et plus dynamiques, utilisez un langage fortement typé, tel que le C++, pour gérer la logique métier.

Exposition des données du C++ vers le QML

La refactorisation du QML est bien plus facile que celle du C++ ; par conséquent, afin de faciliter la maintenance, il convient de veiller à ce que les types C++ restent, autant que possible, indépendants du QML. Pour ce faire, on peut « pousser » des références aux types C++ dans le QML.

Pour ce faire, utilisez des propriétés obligatoires et définissez-les via QQmlApplicationEngine::setInitialProperties. Il est également possible de créer un ou plusieurs singletons qui renverront toutes les données que le côté C++ souhaite fournir à QML.

Grâce à cette approche, le code C++ reste inchangé au cas où le code QML devrait être refactorisé à l’avenir.

Pour un guide rapide sur le choix de la bonne approche permettant d’exposer des types C++ à QML, consultez la section « Choisir la bonne méthode d’intégration entre C++ et QML ».

L'utilisation Qt Design Studio

Qt Design Studio utilise des fichiers d'interface utilisateur portant l'extension .ui.qml afin de séparer les éléments visuels de l'interface utilisateur de la logique que vous implémentez dans des fichiers .qml. Vous ne devez modifier les fichiers d’interface utilisateur que dans la vue « 2D » d’ Qt Design Studio. Si vous utilisez un autre outil pour ajouter du code non pris en charge par Qt Design Studio, des messages d’erreur s’affichent. Corrigez ces erreurs pour réactiver l’édition visuelle des fichiers d’interface utilisateur. En règle générale, vous devez déplacer le code non pris en charge vers un fichier .qml.

Utilisation des vues « Qt Quick »

Enregistrement de l’état dans les modèles

Voir Avoid Storing State in Delegates.

Utilisation de Qt Quick Layouts

Qt propose des « Qt Quick Layouts » pour organiser visuellement les éléments d’ Qt Quick s dans une mise en page. Contrairement à leur alternative, les «item positioners», les « Qt Quick Layouts » peuvent également redimensionner leurs enfants lors du redimensionnement de la fenêtre. Bien que les « Qt Quick Layouts » soient souvent le choix privilégié pour la plupart des cas d’utilisation, il convient de respecter les consignes suivantes lors de leur utilisation :

À faire

  • Utilisez la méthode ` anchors ` ou les propriétés ` width ` et ` height ` pour spécifier la taille de la mise en page par rapport à son élément parent n’appartenant pas à la mise en page.
  • Utilisez la propriété attachée Layout pour définir les attributs de taille et d’alignement des enfants directs de la mise en page.

À ne pas faire

  • Ne définissez pas de tailles préférentielles pour les éléments qui fournissent implicitWidth et implicitHeight, sauf si leurs tailles implicites ne sont pas satisfaisantes.
  • N’utilisez pas d’ancrages sur un élément qui est un enfant direct d’une mise en page. Utilisez plutôt les propriétés « Layout.preferredWidth » et « Layout.preferredHeight » :
    RowLayout {
    id: layout
    anchors.fill: parent
    spacing: 6
    Rectangle {
        color: 'orange'
        Layout.fillWidth: true
        Layout.minimumWidth: 50
        Layout.preferredWidth: 100
        Layout.maximumWidth: 300
        Layout.minimumHeight: 150
        Text {
            anchors.centerIn: parent
            text: parent.width + 'x' + parent.height
        }
    }
    Rectangle {
        color: 'plum'
        Layout.fillWidth: true
        Layout.minimumWidth: 100
        Layout.preferredWidth: 200
        Layout.preferredHeight: 100
        Text {
            anchors.centerIn: parent
            text: parent.width + 'x' + parent.height
        }
    }
}

Remarque : les mises en page et les ancrages sont tous deux des types d’objets qui nécessitent davantage de mémoire et de temps d’instanciation. Évitez de les utiliser (en particulier dans les délégués de listes et de tableaux, ainsi que dans les styles des contrôles) lorsque de simples liaisons aux propriétés x, y, width et height suffisent.

Sécurité des types

Lors de la déclaration de propriétés en QML, il est facile et pratique d'utiliser le type « var » :

property var name
property var size
property var optionsMenu

Cependant, cette approche présente plusieurs inconvénients :

  • Si une valeur de type incorrect est attribuée, l'erreur signalée indiquera l'emplacement de la déclaration de la propriété, et non celui où la propriété a été attribuée. Cela ralentit le processus de développement en rendant plus difficile la recherche des erreurs.
  • Il n'est pas possible de recourir à l'analyse statique pour détecter des erreurs telles que celles mentionnées ci-dessus.
  • Le type sous-jacent réel de la propriété n'est pas toujours immédiatement clair pour le lecteur.

Utilisez plutôt toujours le type réel lorsque cela est possible :

property string name
property int size
property MyMenu optionsMenu

Signaux de modification de propriété

Privilégiez les signaux d’interaction explicites plutôt que les signaux de modification de valeur afin d’éviter les bogues subtils.

L'utilisation de « valueChanged » peut entraîner des cascades d'événements où la valeur est constamment modifiée parce qu'elle est, d'une manière ou d'une autre, arrondie ou normalisée.

L'utilisation exclusive de signaux d'interaction explicites permet d'éviter toute cette catégorie de problèmes.

Par exemple, « Slider » dispose de signaux similaires : « moved » et « valueChanged ».

Slider {
    value: someValueFromBackend

    onValueChanged: pushToBackend(value)
    // or
    onMoved: pushToBackend(value)
}

Les deux cas se ressemblent, et vous pourriez être tenté d’utiliser valueChanged.

Les développeurs négligent souvent le fait que la propriété « Slider » peut changer automatiquement de valeur, par exemple en raison d’un écrêtage aux valeurs minimales/maximales ou d’un arrondi. Dans ce cas, le signal « valueChanged » est émis. Si vous utilisez le signal « valueChanged », vous remarquerez peut-être qu’il est émis à des moments inattendus.

Pour éviter d’éventuels problèmes, utilisez un signal d’interaction : le signal émis lorsque l’utilisateur interagit avec le contrôle. Dans cet exemple, si vous utilisez le signal « moved », l’emplacement ne sera déclenché que si l’utilisateur modifie le contrôle.

Performances

Pour plus d’informations sur les performances en QML et dans Qt Quick, consultez la section « Considérations et suggestions relatives aux performances en QML ».

Privilégiez les liaisons déclaratives aux affectations impératives

En QML, il est possible d’utiliser du code JavaScript impératif pour effectuer des tâches telles que répondre à des événements d’entrée, envoyer des données sur un réseau, etc. Le code impératif occupe une place importante en QML, mais il est également important de savoir quand ne pas l’utiliser.

Prenons par exemple l’affectation impérative suivante :

Rectangle {
    Component.onCompleted: color = "red"
}

Cela présente les inconvénients suivants :

  • Elle est lente. La propriété « color » sera d’abord évaluée avec une valeur par défaut, puis à nouveau avec « red » par la suite.
  • Elle repousse les erreurs qui auraient pu être détectées lors de la compilation jusqu’à l’exécution, ce qui ralentit le processus de développement.
  • Elle écrase tout lien déclaratif qui était en place. Dans la plupart des cas, cela est voulu, mais cela peut parfois être involontaire. Voir Débogage de l’écrasement des liens pour plus d’informations.
  • Cela interfère avec les outils ; le Designer d’ Qt Quick, par exemple, ne prend pas en charge JavaScript.

Le code peut être réécrit pour utiliser une liaison déclarative à la place :

Rectangle {
    color: "red"
}

Ne stockez pas d’état dans des délégués

Ne stockez pas d'état dans un délégué. Le problème ici est que le délégué est créé et détruit plusieurs fois, ce qui entraîne la perte de l'état enregistré.

// Wrong approach:
ListView {
    // ...

    delegate: Button {
        // ...
        property bool someStateProperty
        onClicked: someStateProperty = true
    }
}

Stockez plutôt l’état en dehors du délégué. Par exemple, dans un modèle. Lorsque le délégué est détruit, l’état enregistré n’est pas perdu.

// Right approach:
ListView {
    // ...

    delegate: Button {
        // ...
        onClicked: model.someStateProperty = true
    }
}

Rendez les chaînes destinées aux utilisateurs traduisibles

Il est recommandé de rendre les chaînes destinées à l'utilisateur traduisibles dès le départ. Voir Écriture du code source en vue de la traduction.

ToolButton {
    id: selectionToolButton
    // ...
    icon.source: "qrc:/images/selection.png"

    Tooltip.Text: qsTr("Select pixels within an area and move them")

    onClicked: canvas.tool = ImageCanvas.SelectionTool
}

Ne personnalisez pas les styles natifs

Les styles natifs (styles Windows et macOS) ne prennent pas en charge la personnalisation. Veillez à ne pas personnaliser un style natif.

// Wrong approach:
import QtQuick.Controls.Windows

// Don't customize a native style
Button {
    background: Rectangle { /*...*/ }
}

Il est plutôt recommandé de toujours baser un contrôle personnalisé sur un style unique disponible sur toutes les plateformes, par exemple le style Basic, Fusion, Imagine, Material ou Universal. Ainsi, vous avez la garantie que l'apparence restera toujours la même, quel que soit le style utilisé par l'application. Pour savoir comment utiliser un style différent, consultez la section « Utilisation des styles » dans le guide « Qt Quick Controls ». Vous pouvez également créer votre propre style.

// Right approach:
import QtQuick.Controls.Basic

// You can customize a commonly available style
Button {
    background: Rectangle { /*...*/ }
}

Outils et utilitaires

Pour plus d’informations sur les outils et utilitaires utiles qui facilitent le travail avec QML et Qt Quick, consultez la section « Outils et utilitaires » deQt Quick .

Arborescence de scène

Pour plus d’informations sur le graphe de scène d’ Qt Quick, consultez la section « Graphe de scène » deQt Quick .

Interfaces utilisateur adaptatives

À mesure que les résolutions d’affichage s’améliorent, il devient de plus en plus important de disposer d’une interface utilisateur d’application évolutive. L’une des approches pour y parvenir consiste à conserver plusieurs copies de l’interface utilisateur pour différentes résolutions d’écran, et à charger celle qui convient en fonction de la résolution disponible. Bien que cela fonctionne plutôt bien, cela alourdit la charge de maintenance.

Qt propose une meilleure solution à ce problème et recommande aux développeurs d'applications de suivre ces conseils :

  • Utilisez des ancrages ou le module « Qt Quick Layouts » pour agencer les éléments visuels.
  • Ne spécifiez pas explicitement la largeur et la hauteur d’un élément visuel.
  • Fournissez des ressources d’interface utilisateur, telles que des images et des icônes, pour chaque résolution d’écran prise en charge par votre application. L’exemple de la galerie « Qt Quick Controls » illustre bien ce principe en fournissant l’ qt-logo.png pour les résolutions @2x, @3x et @4x, ce qui permet à l’application de s’adapter aux écrans haute résolution. Qt choisit automatiquement l’image adaptée à l’écran concerné, à condition que la fonctionnalité de mise à l’échelle haute DPI soit explicitement activée.
  • Utilisez des images SVG pour les petites icônes. Si les fichiers SVG volumineux peuvent être lents à afficher, les petits fonctionnent très bien. Les images vectorielles évitent d’avoir à fournir plusieurs versions d’une même image, comme c’est le cas avec les images bitmap.
  • Utilisez des icônes basées sur des polices, telles que Font Awesome. Celles-ci s’adaptent à n’importe quelle résolution d’écran et permettent également d’être colorées. L’exemple « Qt Quick Controls Text Editor » en est une bonne illustration.

Une fois ces éléments en place, l’interface utilisateur de votre application devrait s’adapter en fonction de la résolution d’affichage disponible.

Exemple d'écran d'accueil de la galerie avec le logo Qt

Exposition de QtAbstractListModel à QML Conventions de codage QML

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