Instructions d'importation

Syntaxe d'une instruction d'importation

Une instruction d'import permet aux clients d'indiquer au moteur quels modules, ressources JavaScript et répertoires de composants sont utilisés dans un document QML. Les types pouvant être utilisés dans un document dépendent des modules, ressources et répertoires importés par celui-ci.

Il existe trois types d’importation différents. Chaque type d’importation possède une syntaxe légèrement différente, et une sémantique différente s’applique à chaque type d’importation.

Importations de modules (espaces de noms)

Le type d’import le plus courant est l’import de module. Les clients peuvent importer des modules QML qui enregistrent des types d’objets QML et des ressources JavaScript dans un espace de noms donné.

La forme générique d’une importation de module est la suivante :

import <ModuleIdentifier> [<Version.Number>] [as <Qualifier>]

• L’ <ModuleIdentifier> est un identifiant spécifié en notation URI pointée, qui identifie de manière unique l’espace de noms de types fourni par le module.
• L’ <Version.Number> est une version de la forme MajorVersion.MinorVersion qui précise quelles définitions des différents types d’objets et ressources JavaScript seront rendues disponibles à la suite de l’importation. Elle peut être omise, auquel cas la dernière version du module est importée. Il est également possible de n’omettre que la version mineure. Dans ce cas, c’est la dernière version mineure de la version majeure donnée qui est importée.
• L'<Qualifier> est un identifiant d'espace de noms local facultatif dans lequel les types d'objets et les ressources JavaScript fournis par le module seront installés, s'il est spécifié. S'il est omis, les types d'objets et les ressources JavaScript fournis par le module seront installés dans l'espace de noms global.

Voici un exemple d’importation de module non qualifiée :

import QtQuick

Cette importation permet d’utiliser tous les types fournis par le module ` QtQuick ` sans avoir à spécifier de qualificateur. Par exemple, le code client permettant de créer un rectangle est le suivant :

import QtQuick

Rectangle {
    width: 200
    height: 100
    color: "red"
}

Voici un exemple d’importation non qualifiée avec indication de version :

import QtQuick 2.10

Dans ce cas, les types définis dans Qt Quick 2.11 et versions ultérieures, ou dans toute version majeure supérieure, comme la 6.0, ne seraient pas disponibles dans le fichier.

Voici un exemple d’importation de module qualifiée :

import QtQuick as Quick

Cette importation permet d’importer simultanément plusieurs modules fournissant des noms de types en conflit ; toutefois, comme chaque utilisation d’un type fourni par un module importé dans un espace de noms qualifié doit être précédée du qualificateur, le conflit peut être résolu sans ambiguïté par le moteur QML.

Voici un exemple de code client créant un rectangle après avoir utilisé une importation de module qualifiée :

import QtQuick as Quick

Quick.Rectangle {
    width: 200
    height: 100
    color: "red"
}

Pour plus d’informations sur les importations qualifiées, consultez la section suivante intitulée « Importation dans un espace de noms local qualifié ».

Notez que si un document QML n’importe pas un module fournissant un type d’objet QML particulier, mais tente malgré tout d’utiliser ce type d’objet, une erreur se produira. Par exemple, le document QML suivant n’importe pas QtQuick et, par conséquent, toute tentative d’utilisation du type Rectangle échouera :

Rectangle {
    width: 200
    height: 100
    color: "red"
}

Dans ce cas, le moteur générera une erreur et refusera de charger le fichier.

Importations de modules C++

En règle générale, les types C++ sont déclarés à l’aide des macros QML_ELEMENT et QML_NAMED_ELEMENT() et enregistrés via le système de compilation à l’aide de QML_IMPORT_NAME et QML_IMPORT_MAJOR_VERSION. Le nom d’importation et la version ainsi fournis forment un module qui peut être importé pour accéder aux types.

Cette pratique est particulièrement courante dans les applications clientes qui définissent leurs propres types d’objets QML en C++.

Importation dans un espace de noms local qualifié

L’instruction ` import ` peut, de manière facultative, utiliser le mot-clé ` as ` pour spécifier que les types doivent être importés dans un espace de noms local au document. Si un espace de noms est spécifié, toute référence aux types rendus disponibles par l’importation doit alors être préfixée par le qualificateur de l’espace de noms local.

Ci-dessous, le module ` QtQuick ` est importé dans l’espace de noms « CoreItems ». Désormais, toute référence aux types du module ` QtQuick ` doit être préfixée par le nom de l’ CoreItems:

import QtQuick as CoreItems

CoreItems.Rectangle {
    width: 100; height: 100

    CoreItems.Text { text: "Hello, world!" }

    // WRONG! No namespace prefix - the Text type won't be found
    Text { text: "Hello, world!" }
}

Un espace de noms sert d’identifiant à un module dans le périmètre du fichier. L’espace de noms ne devient pas un attribut de l’objet racine pouvant être référencé en externe, comme c’est le cas avec les propriétés, les signaux et les méthodes.

L’importation avec espace de noms est utile lorsqu’il est nécessaire d’utiliser deux types QML portant le même nom mais situés dans des modules différents. Dans ce cas, les deux modules peuvent être importés dans des espaces de noms distincts afin de garantir que le code fait référence au bon type :

import QtQuick as CoreItems
import TextWidgets as MyModule

CoreItems.Rectangle {
    width: 100; height: 100

    MyModule.Text { text: "Hello from my custom text item!" }
    CoreItems.Text { text: "Hello from Qt Quick!" }
}

Notez que plusieurs modules peuvent être importés dans un même espace de noms, de la même manière que plusieurs modules peuvent être importés dans l'espace de noms global. Par exemple :

import QtQuick as Project
import QtMultimedia as Project

Project.Rectangle {
    width: 100; height: 50

    Project.Audio {
        source: "music.wav"
        autoPlay: true
    }
}

Importations de répertoires

Un répertoire contenant des documents QML peut également être importé directement dans un document QML. Cela offre un moyen simple de segmenter les types QML en groupes réutilisables : des répertoires sur le système de fichiers.

La forme générique d’un import de répertoire est la suivante :

import "<DirectoryPath>" [as <Qualifier>]

La sémantique relative au fichier ` <Qualifier> ` s’applique de la même manière aux importations de répertoires qu’aux importations de modules ; pour plus d’informations à ce sujet, veuillez consulter la section précédente consacrée à l’importation dans un espace de noms local qualifié.

Pour plus d’informations sur les importations de répertoires, veuillez consulter la documentation détaillée à ce sujet.

Importations de ressources JavaScript

Les ressources JavaScript peuvent être importées directement dans un document QML. Chaque ressource JavaScript doit disposer d’un identifiant permettant d’y accéder.

La forme générique d’une importation de ressource JavaScript est la suivante :

import "<JavaScriptFile>" as <Identifier>

Notez que l’ <Identifier> e doit être unique au sein d’un document QML, contrairement au qualificateur d’espace de noms local qui peut être appliqué aux importations de modules.

Ressources JavaScript provenant de modules

Les fichiers JavaScript peuvent être fournis par des modules, en ajoutant des définitions d’identificateurs au fichier « qmldir » qui spécifie le module.

Par exemple, si le module ` projects.MyQMLProject.MyFunctions ` est spécifié à l’aide du fichier ` qmldir ` suivant et installé dans le chemin d’importation QML :

module projects.MyQMLProject.MyFunctions
SystemFunctions 1.0 SystemFunctions.js
UserFunctions 1.0 UserFunctions.js

une application cliente peut importer les ressources JavaScript déclarées dans le module en important ce dernier et en utilisant l’identifiant associé à une ressource déclarée :

import QtQuick
import projects.MyQMLProject.MyFunctions

Item {
    Component.onCompleted: { SystemFunctions.cleanUp(); }
}

Si le module a été importé dans un espace de noms local au document, les identifiants de ressources JavaScript doivent être préfixés par le qualificateur d’espace de noms pour pouvoir être utilisés :

import QtQuick
import projects.MyQMLProject.MyFunctions as MyFuncs
import org.example.Functions as TheirFuncs

Item {
    Component.onCompleted: {
        MyFuncs.SystemFunctions.cleanUp();
        TheirFuncs.SystemFunctions.shutdown();
    }
}

Informations complémentaires

Pour plus d’informations sur les ressources JavaScript, veuillez consulter la documentation relative à la définition des ressources JavaScript en QML. Pour en savoir plus sur l’importation de ressources JavaScript et sur l’utilisation des importations au sein de ces ressources, veuillez consulter la documentation détaillée sur l’importation de ressources JavaScript en QML.

Chemin d’importation QML

Lorsqu’un module identifié est importé, le moteur Qml recherche dans le chemin d’importation un module correspondant afin de charger les fichiers Qml et les plugins de module Qml. Qt part du principe que tous les fichiers situés sous le chemin d’importation proviennent d’une source fiable.

Ce chemin d’importation, tel que renvoyé par la fonction ` QQmlEngine::importPathList()`, définit les emplacements par défaut dans lesquels le moteur effectue ses recherches. Par défaut, cette liste contient, dans l’ordre de priorité suivant :

• Les chemins d’accès aux bundles spécifiques à la plateforme, le cas échéant (par exemple sous macOS ou Android)
• Le répertoire contenant le binaire de l’application
• Le chemin qrc:/qt-project.org/imports à l’intérieur du répertoire resources.
• Le chemin qrc:/qt/Qml à l’intérieur des ressources (depuis Qt 6.5).
• Les chemins spécifiés par la variable d’environnement ` QML2_IMPORT_PATH ` (obsolète)
• Chemins spécifiés par la variable d'environnement ` QML_IMPORT_PATH `
• L'emplacement spécifié par QLibraryInfo::QmlImportsPath

Si l’attribut ` Qt::AA_PluginApplication ` est défini sur ` QCoreApplication`, alors le répertoire de l’application, tous les chemins spécifiés par des variables d’environnement et tous les chemins de bundles spécifiques à la plateforme situés en dehors du système de fichiers de ressources sont omis par défaut.

Des chemins d’importation supplémentaires peuvent être ajoutés via la fonction ` QQmlEngine::addImportPath()` ou la variable d’environnement ` QML_IMPORT_PATH `. Lors de l’exécution de l’outil `qml`, vous pouvez également utiliser l’option ` -I ` pour ajouter un chemin d’importation.

Vous pouvez spécifier plusieurs chemins d’importation dans la variable d’environnement QML_IMPORT_PATH en les séparant par le séparateur de chemin. Sous Windows, le séparateur de chemin est un point-virgule (;), sur les autres plateformes, il s’agit d’un deux-points (:). Cela signifie que vous ne pouvez pas spécifier de chemins de ressources ou d’URL dans QML_IMPORT_PATH, car ceux-ci contiennent eux-mêmes des deux-points. Cependant, vous pouvez ajouter des chemins de ressources et des URL en appelant QQmlEngine::addImportPath() par programmation.

Débogage

La variable d’environnement ` QML_IMPORT_TRACE ` peut s’avérer utile pour le débogage en cas de problèmes de recherche ou de chargement des modules. Voir Débogage des importations de modules pour plus d’informations.