Documents QML

Un document QML est une chaîne de caractères conforme à la syntaxe des documents QML. Un document définit un type d’objet QML. Un document est généralement chargé à partir d’un fichier ".qml" stocké localement ou à distance, mais il peut être construit manuellement dans le code. Une instance du type d'objet défini par un document peut être créée à l'aide d'une instruction « Component » en code QML, ou d'une instruction « QQmlComponent » en C++. Par ailleurs, si le type d'objet est explicitement exposé au système de types QML avec un nom de type particulier, ce type peut être utilisé directement dans les déclarations d'objets d'autres documents.

La possibilité de définir des types d’objets QML réutilisables dans les documents est un atout majeur qui permet aux développeurs d’écrire du code modulaire, très lisible et facile à maintenir.

Depuis Qt 5.4, un document peut également porter l’extension de fichier ".ui.qml". Le moteur QML traite ces fichiers comme des fichiers .qml standard et ignore la partie .ui de l’extension. Qt Design Studio traite ces fichiers comme des fichiers d’interface utilisateur. Ces fichiers ne peuvent contenir qu’un sous-ensemble des fonctionnalités du langage QML.

Structure d’un document QML

Un document QML se compose de deux sections : la section des importations et la section de déclaration des objets. La section des importations d’un document contient des instructions d’importation qui définissent les types d’objets QML et les ressources JavaScript que le document est en mesure d’utiliser. La section de déclaration des objets définit l’arborescence d’objets à créer lors de l’instanciation du type d’objet défini par le document.

Voici un exemple de document simple :

import QtQuick 2.0

Rectangle {
    width: 300
    height: 200
    color: "blue"
}

Consultez la section Structure d’un document QML pour plus d’informations sur ce sujet.

Syntaxe du langage QML

La section de déclaration d’objets du document doit spécifier une hiérarchie d’objets valide en utilisant la syntaxe QML appropriée. Une déclaration d’objet peut inclure la spécification d’attributs d’objet personnalisés. Les attributs de méthode d’objet peuvent être spécifiés sous forme de fonctions JavaScript, et les attributs de propriété d’objet peuvent se voir attribuer des expressions de liaison de propriété.

Veuillez consulter la documentation relative à la syntaxe de QML pour plus d’informations sur la syntaxe valide, et la documentation relative à l’intégration de QML et de JavaScript pour des informations approfondies sur ce sujet.

Définition des types d’objets via des documents QML

Comme décrit brièvement dans la section précédente, un document définit implicitement un type d’objet QML. L’un des principes fondamentaux de QML est la possibilité de définir puis de réutiliser des types d’objets. Cela améliore la maintenabilité du code QML, augmente la lisibilité des déclarations de hiérarchie d’objets et favorise la séparation entre la définition de l’interface utilisateur et la mise en œuvre de la logique.

Dans l’exemple suivant, le développeur client définit un type ` Button ` à l’aide d’un document dans un fichier :

// Button.qml
import QtQuick

Rectangle {
    width: 100; height: 100
    color: "red"

    MouseArea {
        anchors.fill: parent
        onClicked: console.log("Button clicked!")
    }
}

Le type ` Button ` peut ensuite être utilisé dans une application :

// application.qml
import QtQuick

Column {
    Button { width: 50; height: 50 }
    Button { x: 50; width: 100; height: 50; color: "blue" }
    Button { width: 50; height: 50; radius: 8 }
}

Veuillez consulter la documentation relative à la définition des types d'objets dans les documents pour obtenir des informations détaillées sur le sujet.

Chargement des ressources et transparence réseau

Il est important de noter que QML est transparent vis-à-vis du réseau. Les applications peuvent importer des documents à partir de chemins d’accès distants aussi facilement que des documents à partir de chemins d’accès locaux. En effet, toute propriété d’ url peut se voir attribuer une URL distante ou locale, et le moteur QML se chargera de toutes les communications réseau nécessaires.

Veuillez consulter la documentation sur la transparence réseau pour plus d'informations sur la transparence réseau lors des importations.

Portée et résolution des noms

Les expressions dans les documents impliquent généralement des objets ou des propriétés d’objets, et comme plusieurs objets peuvent être définis et que différents objets peuvent posséder des propriétés portant le même nom, certaines règles prédéfinies de résolution des symboles doivent être définies par QML. Veuillez consulter la page sur la portée et la résolution des symboles pour obtenir des informations détaillées sur ce sujet.