Back to Qt.io
Contact Us Blog Download Qt
Sur cette page

Premiers pasGlossaire des termes QML

Premiers pas avec QML

Création d'un document QML

Un document QML définit une hiérarchie d'objets avec une présentation structurée très lisible. Chaque document QML se compose de deux parties : une section d'importation et une section de déclaration d'objet. Les types et fonctionnalités les plus courants dans les interfaces utilisateur sont fournis dans la section d'importation QtQuick.

Importer et utiliser le module QtQuick

Pour utiliser le module Qt Quick un document QML doit l'importer. La syntaxe d'importation se présente comme suit :

import QtQuick

Les types et les fonctionnalités que QtQuick fournit peuvent maintenant être utilisés dans le document QML. Qt Quick peuvent maintenant être utilisés dans le document QML !

Définition d'une hiérarchie d'objets

La déclaration d'objet dans un document QML définit ce qui sera affiché dans la scène visuelle. Qt Quick Elle fournit les éléments de base de toutes les interfaces utilisateur, tels que les objets permettant d'afficher des images et du texte et de traiter les données saisies par l'utilisateur.

Une déclaration d'objet simple peut être une fenêtre colorée dans laquelle un texte est centré :

Window {
    width: 640
    height: 480
    visible: true
    color: "red"

    Text {
        anchors.centerIn: parent
        text: "Hello, World!"
    }
}

Cela définit une hiérarchie d'objets avec un objet racine Window qui a un objet enfant Text. La propriété parent de l'objet Text est automatiquement attribuée à la propriété Window, et de la même manière, l'objet Text est ajouté à la propriété children de l'objet Window, par QML.

Mise en place de l'ensemble

Les types Window et Text utilisés dans l'exemple ci-dessus sont tous deux fournis par l'importation QtQuick. En combinant l'importation et la déclaration d'objet, nous obtenons un document QML complet :

import QtQuick

Window {
    width: 640
    height: 480
    visible: true
    color: "red"

    Text {
        anchors.centerIn: parent
        text: "Hello, World!"
    }
}

Si nous enregistrons ce document sous le nom de "HelloWorld.qml", nous pouvons le charger et l'afficher.

Création et exécution de projets QML

Pour afficher la scène graphique définie par le document QML, celui-ci peut être chargé à l'aide de la commande Qt Creator. Pour créer un nouveau projet QML dans Qt Creator:

  1. Sélectionnez File > New Project > Qt Quick Application à partir de Qt Creator.
  2. Saisissez un nom pour votre projet et sélectionnez un emplacement pour le sauvegarder.
  3. Sélectionnez la version Qt appropriée et configurez éventuellement les paramètres de contrôle de version pour le projet.
  4. Consultez le résumé des paramètres de votre projet et poursuivez la construction du projet.

Lorsque vous avez terminé, Qt Creator génère les fichiers nécessaires et ouvre le projet pour le développement. En appuyant sur le bouton vert Exécuter, vous lancez l'application. Vous devriez voir le texte Hello, World ! au centre d'un rectangle rouge.

Pour plus d'informations sur la création et l'exécution de projets dans Qt Creator, consultez les pages suivantes :

Création d'applications QML avec des contrôles

Alors que Qt Quick fournit des éléments graphiques de base, Qt Quick Controls fournit des types QML prêts à l'emploi à utiliser dans une application.

L'insertion du type ApplicationWindow est un bon point de départ pour créer des applications. L'interface utilisateur d'une application présente cette disposition de base :

Dans chaque zone, différents contrôles peuvent être ajoutés et connectés pour former une application. Par exemple, l'extrait suivant est une application de base qui démontre l'utilisation de l'espace disponible :

//import related modules
import QtQuick
import QtQuick.Controls

//window containing the application
ApplicationWindow {
    width: 640
    height: 480
    visible: true
    //title of the application
    title: qsTr("Hello World")

    //menu containing two menu items
    header: MenuBar {
        Menu {
            title: qsTr("&File")
            Action {
                text: qsTr("&Open...")
                onTriggered: console.log("Open action triggered")
            }
            MenuSeparator { }
            Action {
                text: qsTr("&Exit")
                onTriggered: Qt.quit()
            }
        }
    }

    //Content Area

    //a button in the middle of the content area
    Button {
        text: qsTr("Hello World")
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.verticalCenter: parent.verticalCenter
    }
}

L'application comporte deux éléments de menu et un bouton au milieu. Un clic sur l'élément de menu Exit ferme l'application.

Il existe également différentes méthodes de navigation et différents contrôles tels que des boutons et des curseurs. Les exemples suivants sont disponibles à l'adresse Qt Creator et illustrent différents contrôles et dispositions.

N'hésitez pas à copier et à coller les extraits dans cette simple application Hello World pour voir comment fonctionne QML.

Gestion des données de l'utilisateur

L'un des grands avantages de l'utilisation de QML pour définir une interface utilisateur est qu'il permet au concepteur de l'interface utilisateur de définir la manière dont l'application doit réagir aux événements à l'aide de simples expressions JavaScript. En QML, nous appelons ces événements des signaux et ces signaux sont gérés par des gestionnaires de signaux.

Prenons l'exemple suivant :

import QtQuick

Window {
    id: root
    width: 200
    height: 100
    color: isRed ? "red" : "blue"
    visible: true

    property bool isRed: true  // Track the color state

    Text {
        anchors.centerIn: parent
        text: "Hello, World!"
    }

    TapHandler {
        onTapped: root.isRed = !root.isRed  // Toggle state
    }
}

Cet exemple peut être enregistré sous le nom de "ClickableHelloWorld.qml" et exécuté avec qml, l'outilQML Runtime . Lorsque l'utilisateur clique n'importe où dans la fenêtre, le rectangle passe du rouge au bleu. Si l'utilisateur clique à nouveau, le rectangle redevient rouge.

Remarque : TapHandler émet également le signal "tapped" pour les événements tactiles, de sorte que ce code fonctionnera également sur un appareil mobile.

L'entrée utilisateur au clavier peut être gérée de la même manière avec une simple expression :

import QtQuick

Window {
    id: root
    width: 200
    height: 100
    color: "red"
    visible: true

    Text {
        id: myText
        anchors.centerIn: parent
        text: toggle ? "Hello, World!" : "Goodbye, World!"
        focus: true
        property bool toggle: true
        Keys.onReturnPressed: (event)=>{
            myText.toggle = !myText.toggle;
            event.accepted = true;
        }
    }
}

Maintenant, chaque fois que vous appuyez sur la touche Entrée, le texte alternera entre "Hello, World" et "Goodbye, World".

Liaisons de propriétés

Les objets et leurs propriétés constituent la base d'une interface graphique définie dans un document QML. Le langage QML permet de lier les propriétés les unes aux autres de diverses manières, ce qui permet de créer des interfaces utilisateur très dynamiques.

Dans l'exemple suivant, la géométrie de chaque enfant Rectangle est liée à celle du parent Window. Si la géométrie de l'objet parent Window devait changer, la géométrie de chaque enfant Rectangle serait automatiquement mise à jour en raison des liens entre les propriétés.

import QtQuick

Window {
    id: root
    width: 200
    height: 100
    color: "red"
    visible: true


    Rectangle {
        width: root.width / 2
        height: root.height
        color: "blue"
    }

    Rectangle {
        width: root.width / 2
        height: root.height
        x: root.width / 2
        color: "green"
    }
}

Animations

Les propriétés peuvent également être mises à jour dynamiquement par le biais d'animations. L'importation QtQuick fournit différents types d'animation qui peuvent être utilisés pour animer les changements de valeur d'une propriété. Dans l'exemple suivant, une propriété est animée, puis affichée dans une zone Text:

import QtQuick

Window {
    id: root
    width: 200
    height: 100
    color: "red"
    visible: true

    property int animatedValue

    SequentialAnimation on animatedValue {
        loops: Animation.Infinite
        PropertyAnimation {
            to: 150
            duration: 1000
        }
        PropertyAnimation {
            to: 0
            duration: 1000
        }
    }

    Text {
        anchors.centerIn: parent
        text: root.animatedValue
    }
}

La valeur affichée varie périodiquement de 0 à 150.

Définir des types QML personnalisés pour les réutiliser

L'un des concepts les plus importants de QML est celui de la réutilisation des types. Une application aura probablement plusieurs types visuels similaires (par exemple, plusieurs boutons poussoirs), et QML permet de définir ce genre de choses en tant que types personnalisés réutilisables, afin de minimiser la duplication du code et de maximiser la lisibilité.

Par exemple, imaginons que le développeur définisse un nouveau type MessageLabel dans le fichier MessageLabel.qml:

// MessageLabel.qml
import QtQuick

Rectangle {
    height: 50
    property string message: "debug message"
    property var msgType: ["debug", "warning" , "critical"]
    color: "black"

    Column {
        anchors.fill: parent
        padding: 5.0
        spacing: 2
        Text {
            text: msgType.toString().toUpperCase() + ":"
            font.bold: msgType == "critical"
            font.family: "Terminal Regular"
            color: msgType === "warning" || msgType === "critical" ? "red" : "yellow"
            ColorAnimation on color {
                running: msgType == "critical"
                from: "red"
                to: "black"
                duration: 1000
                loops: msgType == "critical" ? Animation.Infinite : 1
            }
        }
        Text {
            text: message
            color: msgType === "warning" || msgType === "critical" ? "red" : "yellow"
            font.family: "Terminal Regular"
        }
    }

}

Ce type peut maintenant être réutilisé plusieurs fois dans l'application, comme suit :

// application.qml
import QtQuick
Window {
    id: root
    width: 180
    height: 180
    visible: true
    Column {
        anchors.fill: parent
        padding: 1.5
        topPadding: 10.0
        bottomPadding: 10.0
        spacing: 5
        MessageLabel{
            width: root.width - 2
            msgType: "debug"
        }
        MessageLabel {
            width: root.width - 2
            message: "This is a warning!"
            msgType: "warning"
        }
        MessageLabel {
            width: root.width - 2
            message: "A critical warning!"
            msgType: "critical"
        }
    }
}

De cette manière, les types d'interface utilisateur modulaires sont assemblés et réutilisés au sein d'une application.

Voir Attributs d'objets QML pour plus de détails sur la manière de développer vos propres composants réutilisables.

Que faire maintenant ?

Maintenant que vous avez vu QML en action, vous êtes prêt à passer à l'étape suivante. La page suivante vous guidera dans votre voyage avec QML.

Pour commencerGlossaire des termes QML

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.