QQmlContext Class
La classe `QQmlContext` définit un contexte au sein d'un moteur QML. En savoir plus...
| En-tête : | #include <QQmlContext> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS Qml) target_link_libraries(mytarget PRIVATE Qt6::Qml) |
| qmake : | QT += qml |
| Hérite de : | QObject |
Types publics
| struct | PropertyPair |
Fonctions publiques
| QQmlContext(QQmlContext *parentContext, QObject *parent = nullptr) | |
| QQmlContext(QQmlEngine *engine, QObject *parent = nullptr) | |
| virtual | ~QQmlContext() override |
| QUrl | baseUrl() const |
(since 6.11) QList<QQmlContext *> | childContexts() const |
| QObject * | contextObject() const |
| QVariant | contextProperty(const QString &name) const |
| QQmlEngine * | engine() const |
(since 6.11) QObject * | findObjectRecursively(const QString &id) const |
(since 6.11) QList<QObject *> | findObjectsRecursively(const QString &id) const |
| bool | isValid() const |
| QString | nameForObject(const QObject *object) const |
(since 6.2) QObject * | objectForName(const QString &name) const |
| QQmlContext * | parentContext() const |
| QUrl | resolvedUrl(const QUrl &src) const |
| void | setBaseUrl(const QUrl &baseUrl) |
| void | setContextObject(QObject *object) |
| void | setContextProperties(const QList<QQmlContext::PropertyPair> &properties) |
| void | setContextProperty(const QString &name, QObject *value) |
| void | setContextProperty(const QString &name, const QVariant &value) |
Description détaillée
Les contextes contiennent les objets identifiés par leur identifiant (id) dans un document QML. Vous pouvez utiliser nameForObject() et objectForName() pour les récupérer.
Remarque : il incombe au créateur de supprimer tout QQmlContext qu’il construit. Si un QQmlContext n’est plus nécessaire, il doit être détruit explicitement. Le moyen le plus simple de s’en assurer est d’appeler la méthode parent sur le QQmlContext.
La hiérarchie des contextes
Les contextes forment une hiérarchie. La racine de cette hiérarchie est le ` root context` du moteur QML. Chaque composant QML crée son propre contexte lors de son instanciation et certains éléments QML créent des contextes supplémentaires pour eux-mêmes.
Bien que les objets QML instanciés dans un contexte ne soient pas strictement la propriété de ce contexte, leurs liaisons le sont. Si un contexte est détruit, les liaisons de propriétés des objets QML en cours d’exécution cesseront d’être évaluées.
Propriétés de contexte
Les contextes permettent également d’exposer des données aux composants QML instanciés par le moteur QML. Ces données sont invisibles pour tous les outils, y compris le Qt Quick Compiler et aux futurs lecteurs des documents QML en question. Elles ne seront exposées que si le composant QML est instancié dans le contexte C++ spécifique que vous envisagez. Ailleurs, d’autres données de contexte peuvent être exposées à la place.
Au lieu d’utiliser le contexte QML pour exposer des données à vos composants QML, vous devriez soit créer des propriétés d’objet supplémentaires pour contenir ces données, soit utiliser ` singletons`. Consultez la section « Exposition de l’état C++ à QML » pour une explication détaillée.
Chaque `QQmlContext` contient un ensemble de propriétés, distinctes de ses propriétés ` QObject `, qui permettent de lier explicitement des données à un contexte par leur nom. Les propriétés de contexte peuvent être définies et mises à jour en appelant ` QQmlContext::setContextProperty()`.
Pour simplifier la liaison et la gestion d’ensembles de données plus volumineux, un objet contextuel peut être associé à un `QQmlContext`. Toutes les propriétés de l’objet de contexte sont accessibles par leur nom dans le contexte, comme si elles avaient toutes été ajoutées individuellement via des appels à ` QQmlContext::setContextProperty()`. Les modifications apportées aux valeurs des propriétés sont détectées via le signal `notify` de la propriété. La définition d’un objet de contexte est à la fois plus rapide et plus simple que l’ajout et la gestion manuels des valeurs des propriétés de contexte.
Toutes les propriétés ajoutées explicitement par ` QQmlContext::setContextProperty()` ont priorité sur les propriétés de l’objet de contexte.
Les contextes enfants héritent des propriétés de contexte de leurs parents ; si un contexte enfant définit une propriété de contexte qui existe déjà chez son parent, la nouvelle propriété de contexte remplace celle du parent.
Avertissement : définir l'objet de contexte ou ajouter de nouvelles propriétés de contexte après la création d'un objet dans ce contexte est une opération coûteuse (qui force essentiellement toutes les liaisons à être réévaluées). Ainsi, si vous devez utiliser des propriétés de contexte, vous devez au moins terminer la « configuration » du contexte avant de l'utiliser pour créer des objets.
Voir également Exposition des attributs des types C++ dans QML.
Documentation sur les fonctions membres
QQmlContext::QQmlContext(QQmlContext *parentContext, QObject *parent = nullptr)
Créer un nouvel objet `QQmlContext` avec l'parentContext` fournie, ainsi que l'QObject ` parent.
QQmlContext::QQmlContext(QQmlEngine *engine, QObject *parent = nullptr)
Créez un nouvel objet `QQmlContext` en tant qu'enfant du contexte racine de ` engine`, ainsi que l'objet ` QObject ` parent.
[override virtual noexcept] QQmlContext::~QQmlContext()
Détruit l'QQmlContext.
Toutes les expressions ou tous les sous-contextes dépendant de ce contexte seront invalidés, mais pas détruits (à moins qu'ils ne soient rattachés à l'objet ` QQmlContext `).
QUrl QQmlContext::baseUrl() const
Renvoie l'URL de base du composant, ou celle du composant parent si aucune n'est définie.
Voir aussi setBaseUrl().
[since 6.11] QList<QQmlContext *> QQmlContext::childContexts() const
Renvoie les QQmlContexts enfants directs du contexte.
Cette fonction a été introduite dans Qt 6.11.
Voir également parentContext(), findObjectRecursively() et findObjectsRecursively().
QObject *QQmlContext::contextObject() const
Renvoie l'objet de contexte, ou nullptr s'il n'y a pas d'objet de contexte.
Voir aussi setContextObject().
QVariant QQmlContext::contextProperty(const QString &name) const
Renvoie la valeur de la propriété name pour ce contexte sous la forme d’un objet QVariant. Si vous savez que la propriété recherchée est un objet QObject attribué à l’aide d’un identifiant QML dans le contexte actuel, la méthode objectForName() est plus pratique et plus rapide. Contrairement à ` objectForName()` et ` nameForObject()`, cette méthode parcourt la hiérarchie des contextes et effectue des recherches dans les contextes parents si l’ name e n’est pas trouvé dans le contexte actuel. Elle prend également en compte toute valeur définie via ` contextObject()`.
Voir également setContextProperty(), objectForName(), nameForObject() et contextObject().
QQmlEngine *QQmlContext::engine() const
Renvoie l'QQmlEngine du contexte, ou nullptr si le contexte ne dispose pas d'QQmlEngine ou si l'QQmlEngine a été détruit.
[since 6.11] QObject *QQmlContext::findObjectRecursively(const QString &id) const
Recherche de manière récursive dans ce contexte et ses enfants un objet dont l'ID est id. Si un tel objet est trouvé, il est renvoyé. Sinon, la méthode renvoie nullptr.
Il ne peut y avoir qu’un seul objet portant l’identifiant id dans un contexte donné, mais vous pouvez créer plusieurs contextes au sein d’un même document, par exemple avec des vues et des délégués. Chacun de ces contextes peut contenir un objet portant l’identifiant id. Seul le premier objet trouvé est renvoyé ici. La recherche est effectuée selon l’algorithme de recherche en largeur.
Cette fonction a été introduite dans Qt 6.11.
Voir également findObjectsRecursively(), objectForName() et childContexts().
[since 6.11] QList<QObject *> QQmlContext::findObjectsRecursively(const QString &id) const
Recherche de manière récursive, dans ce contexte et ses enfants, les objets dont l'ID est id. Renvoie une liste de ces objets.
Il ne peut y avoir qu’un seul objet portant l’identifiant id dans un contexte donné, mais vous pouvez créer plusieurs contextes au sein d’un même document, par exemple avec des vues et des délégués. Chacun de ces contextes peut contenir un objet portant l’identifiant id.
Cette fonction a été introduite dans Qt 6.11.
Voir également ` findObjectRecursively()`, ` objectForName()` et ` childContexts()`.
bool QQmlContext::isValid() const
Indique si le contexte est valide.
Pour être valide, un contexte doit disposer d'un moteur, et son ` contextObject()` (le cas échéant) ne doit pas avoir été supprimé.
QString QQmlContext::nameForObject(const QObject *object) const
Renvoie le nom d'un objet « object » dans ce contexte, ou une chaîne vide si « object » n'est pas nommé dans ce contexte. Les objets sont nommés par « setContextProperty() », en tant que propriétés d'un objet de contexte, ou par des identifiants dans le cas de contextes créés par QML.
Si l’objet possède plusieurs noms, c’est le premier qui est renvoyé.
Contrairement à ` contextProperty()` (), cette méthode ne parcourt pas la hiérarchie du contexte. Si le nom n’est pas trouvé dans le contexte actuel, une chaîne vide est renvoyée.
Voir également contextProperty() et objectForName().
[since 6.2] QObject *QQmlContext::objectForName(const QString &name) const
Renvoie l’objet correspondant à une adresse de contexte donnée ( name ) dans ce contexte. Renvoie nullptr si l’adresse de contexte ( name ) n’est pas disponible dans le contexte ou si la valeur associée à l’adresse de contexte ( name ) n’est pas un objet de type ` QObject`. Les objets sont nommés par ` setContextProperty()`, ou en tant que propriétés d’un objet de contexte, ou encore par des identifiants (ids) dans le cas des contextes créés par QML. Contrairement à ` contextProperty()`, cette méthode ne parcourt pas la hiérarchie du contexte. Si le nom n'est pas trouvé dans le contexte actuel, `nullptr` est renvoyé.
Cette fonction a été introduite dans Qt 6.2.
Voir également contextProperty() et nameForObject().
QQmlContext *QQmlContext::parentContext() const
Renvoie l'QQmlContext parent du contexte, ou nullptr si ce contexte n'a pas de parent ou si le parent a été détruit.
QUrl QQmlContext::resolvedUrl(const QUrl &src) const
Résout l'URL src par rapport à l'URL du composant qui la contient.
Voir également QQmlEngine::baseUrl() et setBaseUrl().
void QQmlContext::setBaseUrl(const QUrl &baseUrl)
Définit explicitement l'URL que resolvedUrl() utilisera pour les références relatives à baseUrl.
L'appel de cette fonction remplace l'URL du composant parent utilisée par défaut.
Voir également baseUrl() et resolvedUrl().
void QQmlContext::setContextObject(QObject *object)
Définissez l'object de contexte.
Remarque : vous ne devez pas utiliser d'objets de contexte pour injecter des valeurs dans vos composants QML. Utilisez plutôt des singletons ou des propriétés d'objet classiques.
Voir également contextObject().
void QQmlContext::setContextProperties(const QList<QQmlContext::PropertyPair> &properties)
Définissez un lot de propriétés properties dans ce contexte.
Le fait de définir toutes les propriétés en une seule fois évite les rafraîchissements inutiles des expressions ; cette méthode est donc recommandée plutôt que d’appeler ` setContextProperty()` pour chaque propriété individuellement.
Remarque : vous ne devez pas utiliser les propriétés de contexte pour injecter des valeurs dans vos composants QML. Utilisez plutôt des singletons ou des propriétés d'objet classiques.
Voir également ` QQmlContext::setContextProperty()`.
void QQmlContext::setContextProperty(const QString &name, QObject *value)
Définissez la valeur « value » de la propriété « name » dans ce contexte.
QQmlContext ne prend pas possession de value.
Remarque : vous ne devez pas utiliser les propriétés de contexte pour injecter des valeurs dans vos composants QML. Utilisez plutôt des singletons ou des propriétés d'objet classiques.
Voir également contextProperty().
void QQmlContext::setContextProperty(const QString &name, const QVariant &value)
Définissez la valeur « a » pour la propriété « value » de la propriété « name » dans ce contexte.
Remarque : vous ne devez pas utiliser les propriétés de contexte pour injecter des valeurs dans vos composants QML. Utilisez plutôt des singletons ou des propriétés d'objet classiques.
© 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.
