QQmlContext Class
La classe QQmlContext définit un contexte au sein d'un moteur QML. Plus d'informations...
| En-tête : | #include <QQmlContext> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS Qml)target_link_libraries(mytarget PRIVATE Qt6::Qml) |
| qmake : | QT += qml |
| Héritages : | 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 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. La manière la plus simple de s'en assurer est de donner au QQmlContext une adresse parent.
La hiérarchie des contextes
Les contextes forment une hiérarchie. La racine de cette hiérarchie est le moteur QML root context. Chaque composant QML crée son propre contexte lorsqu'il est instancié et certains éléments QML créent des contextes supplémentaires pour eux-mêmes.
Si les objets QML instanciés dans un contexte ne sont 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 suspens cesseront d'être évaluées.
Propriétés du contexte
Les contextes permettent également d'exposer des données aux composants QML instanciés par le moteur QML. Ces données sont invisibles à tout outil, y compris au compilateurQt Quick 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. Dans d'autres endroits, des données de contexte différentes peuvent être exposées à la place.
Au lieu d'utiliser le contexte QML pour exposer les données à vos composants QML, vous devriez soit créer des propriétés d'objet supplémentaires pour contenir les données, soit utiliser singletons. Voir Exposer 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 du contexte peuvent être définies et mises à jour en appelant QQmlContext::setContextProperty().
Pour simplifier la liaison et la maintenance d'ensembles de données plus importants, un objet contextuel peut être défini sur un QQmlContext. Toutes les propriétés de l'objet contextuel sont disponibles par nom dans le contexte, comme si elles avaient été ajoutées individuellement par des appels à QQmlContext::setContextProperty(). Les modifications des valeurs des propriétés sont détectées par le signal de notification de la propriété. La définition d'un objet contextuel est à la fois plus rapide et plus facile que l'ajout et la gestion manuels des valeurs des propriétés du contexte.
Toutes les propriétés ajoutées explicitement par QQmlContext::setContextProperty() sont prioritaires sur les propriétés de l'objet 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à dans son parent, la nouvelle propriété de contexte remplace celle du parent.
Attention : La définition de l'objet de contexte ou l'ajout 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 oblige à réévaluer toutes les liaisons). Par conséquent, 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 aussi Exposer les attributs des types C++ à QML.
Documentation des fonctions membres
QQmlContext::QQmlContext(QQmlContext *parentContext, QObject *parent = nullptr)
Créez un nouveau QQmlContext avec l'adresse parentContext, et l'adresse QObject parent .
QQmlContext::QQmlContext(QQmlEngine *engine, QObject *parent = nullptr)
Créez un nouveau QQmlContext en tant qu'enfant du contexte racine de engine et du contexte racine de QObject parent .
[override virtual noexcept] QQmlContext::~QQmlContext()
Détruit l'objet QQmlContext.
Toutes les expressions ou sous-contextes dépendant de ce contexte seront invalidés, mais pas détruits (sauf s'ils sont liés à l'objet QQmlContext ).
QUrl QQmlContext::baseUrl() const
Renvoie l'url de base du composant, ou du composant qui le contient s'il n'y en a pas.
Voir aussi setBaseUrl().
[since 6.11] QList<QQmlContext *> QQmlContext::childContexts() const
Renvoie les QQmlContexts enfants immédiats du contexte.
Cette fonction a été introduite dans Qt 6.11.
Voir aussi parentContext(), findObjectRecursively(), et findObjectsRecursively().
QObject *QQmlContext::contextObject() const
Retourne 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 en tant que QVariant. Si vous savez que la propriété que vous recherchez est une QObject attribuée à l'aide d'un identifiant QML dans le contexte actuel, objectForName() est plus pratique et plus rapide. Contrairement à objectForName() et nameForObject(), cette méthode traverse la hiérarchie des contextes et recherche dans les contextes parents si la propriété name n'est pas trouvée dans le contexte actuel. Elle prend également en compte les éventuels contextObject() que vous avez définis.
Voir aussi setContextProperty(), objectForName(), nameForObject() et contextObject().
QQmlEngine *QQmlContext::engine() const
Renvoie l'adresse QQmlEngine du contexte, ou nullptr si le contexte n'a pas d'adresse QQmlEngine ou si l'adresse QQmlEngine a été détruite.
[since 6.11] QObject *QQmlContext::findObjectRecursively(const QString &id) const
Recherche récursivement dans ce contexte et ses enfants un objet portant l'ID id. Si un tel objet est trouvé, il est renvoyé. Sinon, il renvoie nullptr.
Il ne peut y avoir qu'un seul objet portant l'identifiant id dans un contexte donné, mais vous pouvez créer de nombreux contextes dans un document, par exemple avec des vues et des délégués. Chacun de ces contextes peut contenir un objet portant le nom id. Seul le premier objet trouvé est renvoyé ici. La recherche est effectuée à l'aide de la fonction "breadth-first search".
Cette fonction a été introduite dans Qt 6.11.
Voir aussi findObjectsRecursively(), objectForName(), et childContexts().
[since 6.11] QList<QObject *> QQmlContext::findObjectsRecursively(const QString &id) const
Recherche récursivement dans ce contexte et ses enfants les objets portant l'ID id. Il 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 de nombreux contextes dans un document, par exemple avec des vues et des délégués. Chacun de ces contextes peut contenir un objet portant le numéro id.
Cette fonction a été introduite dans Qt 6.11.
Voir aussi findObjectRecursively(), objectForName(), et childContexts().
bool QQmlContext::isValid() const
Retourne si le contexte est valide.
Pour être valide, un contexte doit avoir un moteur, et son contextObject(), s'il y en a un, ne doit pas avoir été supprimé.
QString QQmlContext::nameForObject(const QObject *object) const
Renvoie le nom de object dans ce contexte, ou une chaîne vide si object n'est pas nommé dans le contexte. Les objets sont nommés par setContextProperty(), ou 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 a plusieurs noms, le premier est renvoyé.
Contrairement à contextProperty(), cette méthode ne traverse 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 aussi contextProperty() et objectForName().
[since 6.2] QObject *QQmlContext::objectForName(const QString &name) const
Renvoie l'objet pour un name donné dans ce contexte. Renvoie nullptr si name n'est pas disponible dans le contexte ou si la valeur associée à name n'est pas QObject. Les objets sont nommés par setContextProperty(), ou en tant que propriétés d'un objet de contexte, ou par ids dans le cas de contextes créés par QML. Contrairement à contextProperty(), cette méthode ne traverse 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 aussi contextProperty() et nameForObject().
QQmlContext *QQmlContext::parentContext() const
Renvoie le parent du contexte QQmlContext, 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 contenant.
Voir aussi 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 à cette fonction remplacera l'url du composant contenant utilisée par défaut.
Voir aussi baseUrl() et resolvedUrl().
void QQmlContext::setContextObject(QObject *object)
Définir le contexte object.
Note : Vous ne devez pas utiliser les objets de contexte pour injecter des valeurs dans vos composants QML. Utilisez plutôt des singletons ou des propriétés d'objets ordinaires.
Voir également contextObject().
void QQmlContext::setContextProperties(const QList<QQmlContext::PropertyPair> &properties)
Définir un lot de properties sur ce contexte.
La définition de toutes les propriétés en un seul lot permet d'éviter les expressions de rafraîchissement inutiles et est donc recommandée au lieu d'appeler setContextProperty() pour chaque propriété individuelle.
Note : 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'objets ordinaires.
Voir aussi QQmlContext::setContextProperty().
void QQmlContext::setContextProperty(const QString &name, QObject *value)
Fixe le value de la propriété name sur ce contexte.
QQmlContext n'est pas propriétaire de value.
Note : 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'objets ordinaires.
Voir également contextProperty().
void QQmlContext::setContextProperty(const QString &name, const QVariant &value)
Définit l'adresse value de la propriété name de ce contexte.
Note : 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'objets ordinaires.
© 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.
