Importation de répertoires de documents QML

Un répertoire local de fichiers QML peut être importé sans aucune installation ni configuration supplémentaire. Un répertoire distant de fichiers QML peut également être importé, mais nécessite l’existence d’un fichier d’ qmldir s sur le répertoire. Un répertoire local peut, de manière facultative, contenir un fichier d'qmldir s sur le répertoire afin de définir les noms de types à fournir aux clients qui importent le répertoire, et de spécifier les ressources JavaScript qui doivent être mises à la disposition des importateurs.

Qt part du principe que tous les fichiers contenus dans le répertoire importé proviennent d’une source fiable.

Importations de répertoires locaux

Tout fichier QML présent 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 d’accès absolu ou relatif du répertoire sur le système de fichiers, ce qui permet au fichier d’utiliser les types d’objets définis dans ce répertoire.

Le QML Runtime lit un fichier d'qmldir facultatif (fichier de liste de répertoires) situé dans le répertoire importé afin de découvrir les types disponibles définis en QML et en C++. Le fichier qmldir spécifie les noms des types définis en QML et les chemins d'accès aux plugins contenant les types définis en C++.

Les fichiers QML sont mis à disposition avec les noms de types spécifiés dans le fichier ` qmldir ` s’il existe ; sinon, ils seront mis à disposition avec des noms de types dérivés des noms de fichiers des documents QML. Seuls les noms de fichiers commençant par une 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.

La QML Runtime charge tous les plugins répertoriés dans le fichier ` qmldir ` afin de trouver tous les types exposés depuis le C++.

Les importations de répertoires ont une priorité inférieure à celle des importations de modules. Si un même nom est défini dans un module et dans un répertoire, 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 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 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é ; dans ce cas, l’utilisation de tout type fourni dans le répertoire doit être qualifiée :

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 au sein d’une application et le prototypage d’applications, bien que tout code important de tels modules doive mettre à jour ses déclarations ` import ` correspondantes si le répertoire du module est déplacé vers un autre emplacement. Cela peut être évité si l’on utilise plutôt des modules QML, car un module installé est importé à l’aide d’une chaîne d’identifiant unique plutôt que d’un chemin d’accès au système de fichiers.

L’importation implicite

Le répertoire dans lequel se trouve un document QML est automatiquement importé. Vous n’avez pas besoin d’importer explicitement ` "." ` ou une instruction similaire.

Répertoires distants

Un répertoire de fichiers QML peut également être importé depuis un emplacement distant si ce répertoire contient un fichier d’ qmldir s de liste de répertoires.

Par exemple, si le répertoire ` myapp ` de l’exemple précédent était hébergé à l’adresse « 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

Dans ce cas, le répertoire pourrait être importé à l’aide de 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 ce répertoire.

Fichiers qmldir de liste de répertoires

Un fichier d’ qmldir de liste de répertoires est très différent d’ un fichier qmldir de définition de module. Un fichier qmldir de liste de répertoires permet de partager rapidement et facilement un ensemble de documents QML, mais il ne définit pas d’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 la gestion des versions de ces types d’objets QML.

La syntaxe d’un fichier de liste de répertoires qmldir est la suivante :

RoundedButton RoundedBtn.qml

internal HighlightedButton HighlightedBtn.qml

MathFunctions mathfuncs.js

Un répertoire du système de fichiers local peut, de manière facultative, inclure un fichier ` qmldir `. Cela permet au moteur de n’exposer que certains types QML aux clients qui importent ce répertoire. De plus, les ressources JavaScript présentes dans le répertoire ne sont pas exposées aux clients à moins d’être déclarées dans un fichier ` qmldir `.