Importation de répertoires de documents QML

Un répertoire local de fichiers QML peut être importé sans aucune installation ou configuration supplémentaire. Un répertoire distant de fichiers QML peut également être importé, mais nécessite l'existence d'un répertoire listant le fichier qmldir. Un répertoire local peut éventuellement contenir un fichier qmldir afin de définir les noms de type qui doivent être fournis aux clients qui importent le répertoire et de spécifier les ressources JavaScript qui doivent être mises à la disposition des importateurs.

Importations de répertoires locaux

Tout fichier QML se trouvant sur le système de fichiers local peut importer un répertoire local à l'aide d'une instruction d'importation faisant référence au chemin absolu ou relatif du système de fichiers du répertoire, ce qui permet au fichier d'utiliser les types d'objets définis dans ce répertoire.

Si le répertoire local contient un fichier qmldir, les types seront disponibles avec les noms de types spécifiés dans le fichier qmldir; sinon, ils seront disponibles avec les noms de types dérivés des noms de fichiers des documents QML. Seuls les noms de fichiers commençant par une lettre majuscule et se terminant par ".qml" seront exposés en tant que types si aucun fichier qmldir n'est spécifié dans le répertoire.

Les importations de répertoires ont une priorité inférieure à celle des importations de modules. Si le même nom est défini dans un module et dans un répertoire qui sont tous deux importés dans le même espace de noms, seul le type du module est rendu disponible.

Un exemple

Considérons la structure suivante des répertoires d'un 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

Le fichier main/application.qml peut importer le répertoire mycomponents en utilisant le chemin relatif vers ce répertoire, ce qui lui permet d'utiliser les types d'objets QML définis dans ce répertoire :

import "../mycomponents"

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

Le répertoire peut être importé dans un espace de noms local qualifié, auquel cas les utilisations de tous les types fournis dans le répertoire doivent être qualifiées :

import "../mycomponents" as MyComponents

MyComponents.DialogBox {
    // ...
}

La possibilité d'importer un répertoire local est pratique dans des cas tels que les ensembles de composants dans l'application et le prototypage d'applications, bien que tout code qui importe de tels modules doive mettre à jour leurs déclarations import pertinentes si le répertoire du module se déplace vers un autre emplacement. Ce problème peut être évité si l'on utilise plutôt des modules QML, car un module installé est importé avec une chaîne d'identification unique plutôt qu'avec un chemin d'accès au système de fichiers.

L'importation implicite

Le répertoire dans lequel réside un document QML est automatiquement importé. Il n'est pas nécessaire d'importer explicitement "." ou autre.

Répertoires situés à distance

Un répertoire de fichiers QML peut également être importé à partir d'un emplacement distant si le répertoire contient une liste de fichiers qmldir.

Par exemple, si le répertoire myapp de l'exemple précédent était hébergé à "http://www.my-example-server.com" et que le répertoire mycomponents contenait un fichier qmldir défini comme suit :

CheckBox CheckBox.qml
DialogBox DialogBox.qml
Slider Slider.qml

Le répertoire pourrait alors être importé en utilisant l'URL du répertoire distant mycomponents:

import "http://www.my-example-server.com/myapp/mycomponents"

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

Notez que lorsqu'un fichier importe un répertoire via un réseau, il ne peut accéder qu'aux fichiers QML et JavaScript spécifiés dans le fichier qmldir situé dans le répertoire.

Fichiers qmldir de listage de répertoires

Un fichier de liste de répertoires qmldir est très différent d'un fichier qmldir de définition de module. Un fichier directory listing qmldir permet de partager rapidement et facilement un groupe de documents QML, mais il ne définit pas un espace de noms de types dans lequel les types d'objets QML définis par les documents sont enregistrés, et il ne prend pas en charge le versionnage de ces types d'objets QML.

La syntaxe d'un fichier de liste de répertoire qmldir est la suivante :

RoundedButton RoundedBtn.qml

internal HighlightedButton HighlightedBtn.qml

MathFunctions mathfuncs.js

Un répertoire du système de fichiers local peut éventuellement inclure un fichier qmldir. Cela permet au moteur de n'exposer que certains types QML aux clients qui importent le répertoire. En outre, les ressources JavaScript du répertoire ne sont pas exposées aux clients à moins qu'elles ne soient déclarées dans un fichier qmldir.