Déclarations d'importation

Syntaxe d'une instruction d'importation

Une instruction d'importation 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 qui peuvent être utilisés dans un document dépendent des modules, ressources et répertoires qui sont importés par le document.

Il existe trois types d'importation différents. Chaque type d'importation a une syntaxe légèrement différente et une sémantique différente s'applique aux différents types d'importation.

Importations de modules (espaces de noms)

Le type d'importation le plus courant est l'importation 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>]

• <ModuleIdentifier> est un identifiant spécifié en notation URI pointée, qui identifie de manière unique l'espace de noms de type fourni par le module.
• <Version.Number> est une version de la forme MajorVersion.MinorVersion qui spécifie quelles définitions de divers types d'objets et de ressources JavaScript seront mises à disposition en raison de l'importation. Il peut être omis, auquel cas la dernière version du module est importée. Il est également possible d'omettre uniquement la version mineure. Dans ce cas, la dernière version mineure de la version majeure donnée est importée.
• <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 indiqué. 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 qu'il soit nécessaire de spécifier un qualificateur. Par exemple, le code client pour créer un rectangle est le suivant :

import QtQuick

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

Un exemple d'importation non qualifiée avec version serait le suivant

import QtQuick 2.10

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

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

import QtQuick as Quick

Cette importation permet d'importer en même temps plusieurs modules qui fournissent des noms de types conflictuels. Cependant, 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 qui crée 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, voir la section suivante sur l'importation dans un espace de noms local qualifié.

Notez que si un document QML n'importe pas un module qui fournit un type d'objet QML particulier, mais tente quand même d'utiliser ce type d'objet, une erreur se produira. Par exemple, le document QML suivant n'importe pas QtQuick et la tentative d'utilisation du type Rectangle échouera :

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

Dans ce cas, le moteur émettra une erreur et refusera de charger le fichier.

Importations de modules C++

Habituellement, 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 construction à l'aide de QML_IMPORT_NAME et QML_IMPORT_MAJOR_VERSION. Le nom d'importation et la version ainsi obtenus forment un module qui peut être importé pour accéder aux types.

Cette méthode est la plus 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 éventuellement utiliser le mot-clé as pour spécifier que les types doivent être importés dans un espace de noms local particulier du document. Si un espace de noms est spécifié, toutes les références aux types rendus disponibles par l'importation doivent être préfixées par le qualificatif d'espace de noms local.

Ci-dessous, le module QtQuick est importé dans l'espace de noms "CoreItems". Maintenant, toute référence aux types du module QtQuick doit être préfixée par le nom 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 pour un module dans le cadre du fichier. L'espace de noms ne devient pas un attribut de l'objet racine auquel il peut être fait référence à l'extérieur, comme c'est le cas pour les propriétés, les signaux et les méthodes.

L'importation dans un espace de noms est utile s'il est nécessaire d'utiliser deux types QML qui portent le même nom, mais qui se trouvent dans des modules différents. Dans ce cas, les deux modules peuvent être importés dans des espaces de noms différents afin de s'assurer que le code se réfère 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 le 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, il est possible d'importer plusieurs modules dans le même espace de noms :

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. Il s'agit d'un moyen simple de segmenter les types QML en groupes réutilisables : les répertoires du système de fichiers.

La forme générique d'une importation de répertoire est la suivante :

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

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

Pour plus d'informations sur les importations de répertoires, veuillez consulter la documentation détaillée sur les importations de répertoires.

Importation de ressources JavaScript

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

La forme générique d'une importation de ressources JavaScript est la suivante :

import "<JavaScriptFile>" as <Identifier>

Notez que le <Identifier> doit être unique dans 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é avec le fichier qmldir suivant, et installé dans le chemin d'importation de 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 le module 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 des ressources JavaScript doivent être préfixés avec le qualificatif de l'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 sur la définition des ressources JavaScript en QML, et pour plus d'informations sur la manière d'importer des ressources JavaScript, et sur la manière dont les importations peuvent être utilisées à partir de ressources JavaScript, veuillez consulter la documentation approfondie sur l'importation de ressources JavaScript en QML.

Chemin d'importation QML

Lorsqu'un module identifié est importé, le moteur QML recherche le chemin d'importation pour un module correspondant.

Ce chemin d'importation, tel qu'il est renvoyé par QQmlEngine::importPathList(), définit les emplacements par défaut à rechercher par le moteur. Par défaut, cette liste contient, dans cet ordre de priorité

• les chemins d'accès aux bundles spécifiques à la plateforme, le cas échéant (par exemple sur macOS ou Android)
• Le répertoire du binaire de l'application
• Le chemin qrc:/qt-project.org/imports à l'intérieur des ressources.
• Le chemin qrc:/qt/qml à l'intérieur des ressources (depuis Qt 6.5).
• 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, le répertoire de l'application, tous les chemins spécifiés par les variables d'environnement et tous les chemins des bundles spécifiques à la plate-forme en dehors du système de fichiers des ressources sont omis par défaut.

Des chemins d'importation supplémentaires peuvent être ajoutés via 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 reliant à l'aide du séparateur de chemin. Sous Windows, le séparateur de chemin est un point-virgule ( ;), tandis que sur les autres plateformes, il s'agit de deux points ( :). Cela signifie que vous ne pouvez pas spécifier des chemins de ressources ou des URL dans QML_IMPORT_PATH, car ils contiennent eux-mêmes des deux-points. Cependant, vous pouvez ajouter des chemins de ressources et des URL en appelant QQmlEngine::addImportPath() par programme.

Débogage

La variable d'environnement QML_IMPORT_TRACE peut être utile pour le débogage lorsqu'il y a des problèmes avec la recherche et le chargement des modules. Voir Débogage des importations de modules pour plus d'informations.