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 en code. Une instance du type d'objet défini par un document peut être créée à l'aide d'un Component en code QML ou d'un 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, le 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 des documents est un élément important qui permet aux clients d'écrire un code modulaire, très lisible et facile à maintenir.

Depuis Qt 5.4, un document peut également avoir 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 des déclarations d'objets. La section des importations d'un document contient des déclarations d'importation qui définissent les types d'objets QML et les ressources JavaScript que le document peut utiliser. La section de déclaration d'objet définit l'arbre 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"
}

Voir la Structure d'un document QML pour plus d'informations sur le sujet.

Syntaxe du langage QML

La section de déclaration d'objet du document doit spécifier une hiérarchie d'objets valide avec 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 en tant que fonctions JavaScript, et les attributs de propriété d'objet peuvent être associés à des expressions de liaison de propriété.

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

Définition des types d'objets à l'aide de 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, 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 avec 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 sur la définition des types d'objets dans les documents pour obtenir des informations plus détaillées sur le sujet.

Chargement des ressources et transparence du réseau

Il est important de noter que QML est transparent pour le réseau. Les applications peuvent importer des documents à partir de chemins d'accès distants tout aussi simplement que des documents à partir de chemins d'accès locaux. En fait, toute propriété url peut se voir attribuer une URL locale ou distante, et le moteur QML se chargera de toute communication réseau nécessaire.

Veuillez consulter la documentation sur la transparence du réseau pour plus d'informations sur la transparence du réseau dans les 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 avoir des propriétés portant le même nom, une certaine sémantique prédéfinie de résolution de symboles doit être définie par QML. Veuillez consulter la page sur la portée et la résolution des symboles pour obtenir des informations plus détaillées sur ce sujet.