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'identification en pointillés, qui doit être spécifiée par le module dans son fichier qmldir. Cela permet à ces modules d'être importés avec un identifiant unique qui reste le même quel que soit l'endroit où le module se trouve dans le système de fichiers local.

Lors de l'importation d'un module identifié, un identifiant sans guillemets est utilisé, avec un numéro de version optionnel :

import QtQuick
import com.mycompany.qml.mymodule 1.0

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

D'un point de vue syntaxique, chaque segment de l'URI séparé par des points doit être un nom d'identifiant 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 traduit en noms de répertoire, 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 de fichiers QML et/ou C++ peut être partagé en tant que module identifié s'il contient un fichier qmldir avec les métadonnées du module et s'il est installé dans le chemin d'importation QML. Tout fichier QML se trouvant sur le système de fichiers local peut importer ce répertoire en tant que module en utilisant une déclaration 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 résider dans une structure de répertoire dans le chemin d'importation qui reflète la chaîne d'identifiant pointé de l'URI, où chaque point (".") dans l'identifiant reflète un sous-niveau dans l'arborescence du répertoire. 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 des sous-répertoires qui lui sont propres. Par exemple, la version 2.1 d'un module peut être située sous com/mycompany/mymodule.2/qmldir ou com/mycompany/mymodule.2.1/qmldir. Le moteur chargera automatiquement le module qui correspond le mieux.

Il est également possible de définir les versions des différents types dans un fichier qmldir, mais cela peut rendre la mise à jour d'un tel module plus difficile (car la procédure de mise à jour nécessite la fusion du fichier qmldir ).

Un exemple

Considérons la structure de répertoire suivante du projet QML. Sous le répertoire de premier niveau myapp, il y a un ensemble de composants d'interface utilisateur communs dans un sous-répertoire nommé mycomponents, et le code de l'application principale dans un sous-répertoire nommé main, comme ceci :

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

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

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

En outre, l'emplacement du fichier qmldir dans le chemin d'importation doit correspondre à la chaîne d'identification en pointillés du module. Ainsi, disons que le répertoire de premier niveau myapp est situé dans C:\qml\projects, et que le module doit être identifié comme "myapp.mycomponents". Dans ce cas :

• le chemin C:\qml\projects doit être ajouté au chemin d'importation
• Le fichier qmldir doit être situé sous C:\qml\projects\myapp\mycomponents\qmldir

Une fois cela fait, un fichier QML situé n'importe où sur le système de fichiers local peut importer le module en se référant à 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é en tant que 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.

Il convient de noter que lorsqu'un fichier importe un module via un 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++ dans le 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 pas modifier ou remplacer 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 version spécifiée et de l'ordre d'importation.

Ainsi, les clients qui utilisent le module peuvent être certains que les types d'objets définis dans le module se comporteront comme l'auteur du module l'a documenté.

Un module identifié est soumis à plusieurs restrictions :

• un module identifié doit être installé dans le chemin d'importation de QML
• l'identifiant du module spécifié dans la directive module identifier doit correspondre au chemin d'installation du module (relatif au chemin d'importation QML, où les séparateurs de répertoires sont remplacés par des points)
• le module doit enregistrer ses types dans l'espace de noms des types de l'identifiant du module
• le module ne peut 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'identification du module doit être :

module ExampleModule

Si le module strict est installé sur $QML_IMPORT_PATH/com/example/CustomUi, la directive d'identification du module doit être: :

module com.example.CustomUi

Les clients pourront alors importer le module susmentionné à l'aide de l'instruction import suivante :

import com.example.CustomUi