Modules QML

Un module QML fournit des types versionnés et des ressources JavaScript dans un espace de noms de types pouvant être utilisé par les clients qui importent le module. Les types fournis par un module peuvent être définis en C++ au sein d’un plugin, ou dans des documents QML. Les modules utilisent le système de gestion des versions de QML, ce qui permet de les mettre à 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 ensemble 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, afin que les applications ne chargent que les bibliothèques nécessaires à leurs besoins spécifiques
• La gestion des versions des types et des ressources, afin que le module puisse être mis à jour en toute sécurité sans perturber le code client

Modules QML modernes

La meilleure façon de définir des modules QML est d’utiliser l’API CMake, en particulier la fonction 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 via des documents QML

Les types QML peuvent être définis directement dans des documents QML, ce qui constitue le moyen le plus simple de créer des composants réutilisables. Chaque fichier QML commençant par une majuscule définit automatiquement un type pouvant être utilisé par d’autres fichiers QML du même module.

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

Pour de meilleures performances ou pour accéder à des 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.

Tout regrouper avec CMake

La commande CMake `qt_add_qml_module ` rassemble les fichiers QML, les types C++ et les ressources au sein d’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 moderne de modules QML.

Modernisation des modules QML

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

Réglage fin des modules QML

Les options de configuration avancées des modules décrites dans la section « Écriture de modules QML » permettent un contrôle précis du comportement des modules. Cela inclut l’ajout de plusieurs modules QML au même binaire, la gestion des versions, les structures de répertoires personnalisées et des sujets avancés sur les plugins QML.

Anciens modules QML

Un module est défini par un fichier de définition de module `qmldir`. Chaque module est associé à un espace de noms de type, qui sert d’identifiant au module. Un module peut fournir des types d’objets QML (définis soit par des documents QML, soit via un plugin C++) et des ressources JavaScript, et peut être importé par des clients.

Pour définir un module, un développeur doit regrouper dans un même répertoire les différents documents QML, ressources JavaScript et plugins C++ appartenant au module, puis rédiger un fichier qmldir de définition de module approprié, qui doit également être placé dans ce répertoire. Le répertoire peut ensuite être installé dans le chemin d’importation 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

QML prend en charge deux types de modules différents :

• 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 QML. Les modules identifiés sont plus faciles à maintenir (grâce au contrôle de version des types) et bénéficient de garanties d'enregistrement des types par le moteur QML, garanties qui ne sont pas offertes aux 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 doivent ê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 relative à 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 implémentée en C++, ou qui définit des types en C++ et les expose à QML, peut souhaiter implémenter un plugin QML. Un développeur de 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 plugin C++ pour QML dispose d’une fonction d’initialisation appelée par le moteur QML lors du chargement du plugin. 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éation de plugins C++ pour QML pour plus d’informations.