Modules identifiés

Les modules identifiés sont des modules installés et identifiables par le moteur QML grâce à un URI sous la forme d'une chaîne d'identificateurs séparés par des points, qui doit être spécifiée par le module dans son fichier « qmldir ». Cela permet d’importer ces modules avec un identifiant unique qui reste le même, quel que soit l’emplacement du module sur le système de fichiers local.

Lors de l’importation d’un module identifié, on utilise un identifiant sans guillemets, accompagné d’un numéro de version facultatif :

import QtQuick
import com.mycompany.qml.mymodule 1.0

Les modules identifiés doivent être installés dans le chemin d’importation pour pouvoir être trouvés par le moteur QML.

D'un point de vue syntaxique, chaque segment de l'URI séparé par un point doit être un nom d'identificateur ECMAScript bien formé. Cela signifie, par exemple, que les segments ne doivent pas commencer par un chiffre et ne doivent pas contenir de caractères « - » (moins). Comme l’URI sera converti en noms de répertoires, vous devez le limiter aux caractères alphanumériques de l’alphabet latin, aux traits de soulignement et aux points.

Modules identifiés installés localement

Un répertoire contenant des fichiers QML et/ou C++ peut être partagé en tant que module identifié s’il contient un fichier `qmldir` renfermant les métadonnées du module et s’il est installé dans le chemin d’importation QML. Tout fichier QML présent sur le système de fichiers local peut importer ce répertoire en tant que module à l’aide d’une instruction d’importation faisant référence à l’URI du module, ce qui permet au fichier d’utiliser les types d’objets QML et les ressources JavaScript définis par le module.

Le fichier ` qmldir ` du module doit se trouver dans une structure de répertoires au sein du chemin d’importation qui reflète la chaîne d’identifiant URI ponctuée, où chaque point (« . ») de l’identifiant correspond à un sous-niveau dans l’arborescence des répertoires. Par exemple, le fichier ` qmldir ` du module com.mycompany.mymodule doit se trouver dans le sous-chemin com/mycompany/mymodule/qmldir, quelque part dans le chemin d’importation.

Il est possible de stocker différentes versions d’un module dans ses propres sous-répertoires. Par exemple, une version 2.1 d’un module pourrait se trouver sous com/mycompany/mymodule.2/qmldir ou com/mycompany/mymodule.2.1/qmldir. Le moteur chargera automatiquement le module le plus adapté.

Il est également possible de définir la gestion des versions pour différents types au sein même d’un fichier qmldir ; toutefois, cela peut compliquer la mise à jour d’un tel module (car une fusion des fichiers qmldir doit avoir lieu dans le cadre de la procédure de mise à jour).

Un exemple

Considérons la structure de répertoires suivante pour un projet QML. Sous le répertoire de niveau supérieur myapp, on trouve un ensemble de composants d’interface utilisateur communs dans un sous-répertoire nommé mycomponents, et le code principal de l’application dans un sous-répertoire nommé main, comme suit :

myapp
    |- mycomponents
        |- CheckBox.qml
        |- DialogBox.qml
        |- Slider.qml
    |- main
        |- application.qml

Pour que le répertoire mycomponents soit disponible en tant que module identifié, il doit contenir un fichier qmldir définissant l'identifiant du module et décrivant les types d'objets mis à disposition par celui-ci. Par exemple, pour rendre les types CheckBox, DialogBox et Slider disponibles pour la version 1.0 du module, le fichier qmldir contiendrait ce qui suit :

module myapp.mycomponents
CheckBox 1.0 CheckBox.qml
DialogBox 1.0 DialogBox.qml
Slider 1.0 Slider.qml

De plus, l’emplacement du fichier qmldir dans le chemin d’importation doit correspondre à la chaîne d’identificateur pointée du module. Supposons donc que le répertoire de niveau supérieur myapp se trouve dans C:\qml\projects et que le module doive être identifié comme « myapp.mycomponents ». Dans ce cas :

• Le chemin C:\qml\projects doit être ajouté au chemin d’importation
• Le fichier qmldir doit se trouver sous C:\qml\projects\myapp\mycomponents\qmldir

Une fois cette opération effectuée, un fichier QML situé n’importe où sur le système de fichiers local peut importer le module en faisant référence à son URI et à la version appropriée :

import myapp.mycomponents 1.0

DialogBox {
    CheckBox {
        // ...
    }
    Slider {
        // ...
    }
}

Modules identifiés installés à distance

Les modules identifiés sont également accessibles en tant que ressource réseau. Dans l'exemple précédent, si le répertoire C:\qml\projects était hébergé à l'adresse http://www.some-server.com/qml/projects et que cette URL était ajoutée au chemin d'importation QML, le module pourrait être importé exactement de la même manière.

Notez que lorsqu’un fichier importe un module via le réseau, il ne peut accéder qu’aux ressources QML et JavaScript fournies par le module ; il ne peut pas accéder aux types définis par les plugins C++ du module.

Sémantique des modules identifiés

Un module identifié bénéficie des garanties suivantes de la part du moteur QML :

• les autres modules ne peuvent ni modifier ni redéfinir les types dans l'espace de noms du module
• les autres modules ne peuvent pas enregistrer de nouveaux types dans l’espace de noms du module
• l'utilisation des noms de types par les clients se résoudra de manière déterministe à une définition de type donnée, en fonction de la gestion des versions spécifiée et de l'ordre d'importation

Cela garantit aux clients qui utilisent le module que les types d’objets définis dans celui-ci se comporteront conformément à la documentation fournie par l’auteur du module.

Un module identifié est soumis à plusieurs restrictions :

• un module identifié doit être installé dans le chemin d'importation QML
• l’identifiant du module spécifié dans la directive d’identifiant de module doit correspondre au chemin d’installation du module (par rapport au chemin d’importation QML, les séparateurs de répertoires étant remplacés par des points)
• le module doit enregistrer ses types dans l'espace de noms de types de l'identifiant de module
• le module ne doit pas enregistrer de types dans l'espace de noms d'un autre module

Par exemple, si un module identifié est installé dans $QML_IMPORT_PATH/ExampleModule, la directive d'identifiant de module doit être :

module ExampleModule

Si le module « strict » est installé dans $QML_IMPORT_PATH/com/example/CustomUi, la directive d’identifiant de module doit être :

module com.example.CustomUi

Les clients pourront alors importer le module ci-dessus à l’aide de l’instruction d’import suivante :

import com.example.CustomUi