Modules QML

Un module QML fournit des types versionnés et des ressources JavaScript dans un espace de noms de types qui peuvent être utilisés par les clients qui importent le module. Les types fournis par un module peuvent être définis en C++ dans un plugin ou dans des documents QML. Les modules utilisent le système de versions QML qui permet aux modules d'être mis à jour de manière indépendante.

La définition d'un module QML permet

• le partage de types QML communs au sein d'un projet - par exemple, un groupe de composants d'interface utilisateur utilisés par différentes fenêtres
• la distribution de bibliothèques basées sur QML
• la modularisation de fonctionnalités distinctes, de sorte que les applications ne chargent que les bibliothèques nécessaires à leurs besoins individuels
• le versionnage des types et des ressources afin que le module puisse être mis à jour en toute sécurité sans casser le code client.

Modules QML modernes

La meilleure façon de définir les modules QML est d'utiliser l'API CMake, en particulier qt_add_qml_module. Les sections suivantes décrivent tous les aspects de la création d'un module QML moderne.

Définition des types d'objets à l'aide de documents QML

Les types QML peuvent être définis directement dans les documents QML, ce qui est la manière la plus simple de créer des composants réutilisables. Chaque fichier QML qui commence par une lettre majuscule définit automatiquement un type qui peut être utilisé par d'autres fichiers QML dans le même module.

Définition des types QML à partir de C++

Pour améliorer les performances ou l'accès aux API de bas niveau, les types peuvent être définis en C++ et exposés à QML. Les types C++ offrent un contrôle total sur les propriétés, les méthodes et les signaux, tout en bénéficiant du typage statique et de la compilation.

Lier le tout avec CMake

La commande CMakeqt_add_qml_module rassemble les fichiers QML, les types C++ et les ressources en un module cohérent. Elle gère automatiquement l'enregistrement des types, la compilation des ressources et l'intégration des outils QML, ce qui en fait l'approche recommandée pour le développement de modules QML modernes.

Modernisation des modules QML

Ce guide aide à migrer les anciens modules QML basés sur CMake vers les nouvelles versions de Qt Help. Il explique comment s'adapter aux nouvelles politiques CMake et comment éviter les techniques obsolètes.

Ajustement des modules QML

Les options avancées de configuration des modules dans Writing QML Modules permettent de contrôler finement le comportement des modules. Cela inclut l'ajout de plusieurs modules QML au même binaire, le versionnage, les dispositions de répertoire personnalisées, et des sujets avancés sur les plugins QML.

Anciens modules QML

Un module est défini par un fichier qmldir de définition de module. Chaque module possède un espace de noms de type associé, qui est l'identifiant du module. Un module peut fournir des types d'objets QML (définis soit par des documents QML, soit par un plugin C++) et des ressources JavaScript, et peut être importé par des clients.

Pour définir un module, un développeur doit rassembler les différents documents QML, les ressources JavaScript et les plugins C++ qui appartiennent au module dans un seul répertoire, et écrire un fichier de définition de module qmldir approprié qui doit également être placé dans le répertoire. Le répertoire peut alors être installé dans le chemin d'importation de QML en tant que module.

Notez que la définition d'un module n'est pas le seul moyen de partager des types QML communs au sein d'un projet - une simple importation de répertoire de documents QML peut également être utilisée à cette fin.

Types de modules QML pris en charge

Il existe deux types de modules pris en charge par QML :

• Modules identifiés
• Modules hérités (obsolètes)

Les modules identifiés définissent explicitement leur identifiant et sont installés dans le chemin d'importation de QML. Les modules identifiés sont plus faciles à maintenir (en raison du versionnement des types) et bénéficient de garanties d'enregistrement des types par le moteur QML, ce qui n'est pas le cas des modules hérités. Les modules hérités ne sont pris en charge que pour permettre au code hérité de continuer à fonctionner avec la dernière version de QML, et devraient être évités par les clients dans la mesure du possible.

Les clients peuvent importer un module QML à partir de documents QML ou de fichiers JavaScript. Veuillez consulter la documentation sur l'importation d'un module QML pour plus d'informations à ce sujet.

Fournir des types et des fonctionnalités dans un plugin C

Une application dont une grande partie de la logique est mise en œuvre en C++, ou qui définit des types en C++ et les expose à QML, peut souhaiter mettre en œuvre un module d'extension QML. Le développeur d'un module d'extension QML peut souhaiter implémenter certains types dans un plugin C++ (plutôt que de les définir via des documents QML) afin d'obtenir de meilleures performances ou une plus grande flexibilité.

Chaque module d'extension C++ pour QML possède une fonction d'initialisation qui est appelée par le moteur QML lorsqu'il charge le module d'extension. Cette fonction d'initialisation doit enregistrer tous les types fournis par le plugin, mais ne doit rien faire d'autre (par exemple, l'instanciation de QObjects n'est pas autorisée).

Voir Créer des plugins C++ pour QML pour plus d'informations.