QQmlContext Class
Die Klasse „QQmlContext“ definiert einen Kontext innerhalb einer QML-Engine. Mehr dazu...
| Kopfzeile: | #include <QQmlContext> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Qml) target_link_libraries(mytarget PRIVATE Qt6::Qml) |
| qmake: | QT += qml |
| Erbt von: | QObject |
Öffentliche Typen
| struct | PropertyPair |
Öffentliche Funktionen
| 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) |
Ausführliche Beschreibung
Kontexte enthalten die durch eine ID identifizierten Objekte in einem QML-Dokument. Sie können sie mit ` nameForObject()` und ` objectForName()` abrufen.
Hinweis: Es liegt in der Verantwortung des Erstellers, jeden von ihm erstellten `QQmlContext` zu löschen. Wenn ein `QQmlContext` nicht mehr benötigt wird, muss er explizit zerstört werden. Der einfachste Weg, dies sicherzustellen, besteht darin, dem `QQmlContext` einen ` parent` zuzuweisen.
Die Kontext-Hierarchie
Kontexte bilden eine Hierarchie. Die Wurzel dieser Hierarchie ist der ` root context` der QML-Engine. Jede QML-Komponente erstellt bei ihrer Instanziierung einen eigenen Kontext, und einige QML-Elemente erstellen zusätzliche Kontexte für sich selbst.
Zwar gehören QML-Objekte, die in einem Kontext instanziiert wurden, streng genommen nicht diesem Kontext, ihre Bindungen jedoch schon. Wird ein Kontext zerstört, werden die Eigenschaftsbindungen der noch bestehenden QML-Objekte nicht mehr ausgewertet.
Kontext-Eigenschaften
Kontexte ermöglichen es zudem, Daten für die von der QML-Engine instanziierten QML-Komponenten verfügbar zu machen. Diese Daten sind für alle Werkzeuge – einschließlich des „Qt Quick “-Compilers – sowie für zukünftige Leser der betreffenden QML-Dokumente unsichtbar. Sie werden nur dann verfügbar gemacht, wenn die QML-Komponente in dem spezifischen C++-Kontext instanziiert wird, den Sie vorsehen. An anderen Stellen können stattdessen andere Kontextdaten verfügbar gemacht werden.
Anstatt den QML-Kontext zu verwenden, um Daten für Ihre QML-Komponenten bereitzustellen, sollten Sie entweder zusätzliche Objekteigenschaften zum Speichern der Daten erstellen oder „ singletons “ verwenden. Eine ausführliche Erläuterung finden Sie unter „Bereitstellung des C++-Zustands für QML “.
Jeder `QQmlContext` enthält eine Reihe von Eigenschaften, die sich von den Eigenschaften des ` QObject ` unterscheiden und es ermöglichen, Daten explizit anhand ihres Namens an einen Kontext zu binden. Die Kontexteigenschaften können durch Aufruf von ` QQmlContext::setContextProperty()` definiert und aktualisiert werden.
Um die Bindung und Verwaltung größerer Datensätze zu vereinfachen, kann ein Kontext-Objekt einem `QQmlContext` zugewiesen werden. Alle Eigenschaften des Kontext-Objekts sind im Kontext namentlich verfügbar, als wären sie einzeln durch Aufrufe von ` QQmlContext::setContextProperty()` hinzugefügt worden. Änderungen an den Werten der Eigenschaften werden über das `notify`-Signal der jeweiligen Eigenschaft erkannt. Das Festlegen eines Kontext-Objekts ist sowohl schneller als auch einfacher als das manuelle Hinzufügen und Verwalten von Kontext-Eigenschaftswerten.
Alle Eigenschaften, die explizit über ` QQmlContext::setContextProperty()` hinzugefügt wurden, haben Vorrang vor den Eigenschaften des Kontext-Objekts.
Unterkontexte erben die Kontext-Eigenschaften ihrer übergeordneten Objekte; wenn ein Unterkontext eine Kontext-Eigenschaft setzt, die in seinem übergeordneten Objekt bereits vorhanden ist, überschreibt die neue Kontext-Eigenschaft die des übergeordneten Objekts.
Warnung: Das Festlegen des Kontextobjekts oder das Hinzufügen neuer Kontexteigenschaften, nachdem ein Objekt in diesem Kontext erstellt wurde, ist ein ressourcenintensiver Vorgang (da im Wesentlichen alle Bindungen neu ausgewertet werden müssen). Wenn Sie also Kontexteigenschaften verwenden müssen, sollten Sie zumindest die „Einrichtung“ des Kontexts abschließen, bevor Sie ihn zum Erstellen von Objekten verwenden.
Siehe auch „Bereitstellen von Attributen von C++-Typen für QML“.
Dokumentation zu Mitgliedsfunktionen
QQmlContext::QQmlContext(QQmlContext *parentContext, QObject *parent = nullptr)
Erstellen Sie einen neuen `QQmlContext` mit dem angegebenen ` parentContext` sowie dem ` QObject ` und dem ` parent`.
QQmlContext::QQmlContext(QQmlEngine *engine, QObject *parent = nullptr)
Erstellen Sie einen neuen `QQmlContext` als untergeordnetes Element des Root-Kontexts von ` engine` sowie des ` QObject ` parent.
[override virtual noexcept] QQmlContext::~QQmlContext()
Löscht das Objekt „ QQmlContext “.
Alle Ausdrücke oder Unterkontexte, die von diesem Kontext abhängen, werden ungültig, jedoch nicht zerstört (es sei denn, sie sind dem Objekt „ QQmlContext “ untergeordnet).
QUrl QQmlContext::baseUrl() const
Gibt die Basis-URL der Komponente zurück oder, falls keine festgelegt ist, die der übergeordneten Komponente.
Siehe auch ` setBaseUrl()`.
[since 6.11] QList<QQmlContext *> QQmlContext::childContexts() const
Gibt die direkten untergeordneten QQmlContexts des Kontexts zurück.
Diese Funktion wurde in Qt 6.11 eingeführt.
Siehe auch „ parentContext()“, „ findObjectRecursively()“ und „ findObjectsRecursively()“.
QObject *QQmlContext::contextObject() const
Gibt das Kontext-Objekt zurück oder „ nullptr “, wenn kein Kontext-Objekt vorhanden ist.
Siehe auch setContextObject().
QVariant QQmlContext::contextProperty(const QString &name) const
Gibt den Wert der Eigenschaft „ name “ für diesen Kontext als „ QVariant “ zurück. Wenn Sie wissen, dass die gesuchte Eigenschaft ein „ QObject “ ist, der im aktuellen Kontext über eine QML-ID zugewiesen wurde, ist „ objectForName()“ praktischer und schneller. Im Gegensatz zu ` objectForName()` und ` nameForObject()` durchläuft diese Methode die Kontexthierarchie und sucht in übergeordneten Kontexten, wenn die ` name ` im aktuellen Kontext nicht gefunden wird. Außerdem berücksichtigt sie alle von Ihnen möglicherweise festgelegten ` contextObject()`.
Siehe auch setContextProperty(), objectForName(), nameForObject() und contextObject().
QQmlEngine *QQmlContext::engine() const
Gibt die ` QQmlEngine` des Kontexts zurück oder ` nullptr `, wenn der Kontext keine ` QQmlEngine ` besitzt oder die ` QQmlEngine ` zerstört wurde.
[since 6.11] QObject *QQmlContext::findObjectRecursively(const QString &id) const
Durchsucht diesen Kontext und dessen untergeordnete Elemente rekursiv nach einem Objekt mit der ID „ id “. Wird ein solches Objekt gefunden, wird es zurückgegeben. Andernfalls wird „ nullptr “ zurückgegeben.
In einem beliebigen Kontext kann es nur ein Objekt mit der angegebenen ID „ id “ geben, aber Sie können innerhalb eines Dokuments viele Kontexte erstellen, beispielsweise mit Ansichten und Delegaten. Jeder dieser Kontexte kann ein Objekt mit der angegebenen ID „ id “ enthalten. Hier wird nur das erste gefundene Objekt zurückgegeben. Die Suche erfolgt mittels Breitensuche.
Diese Funktion wurde in Qt 6.11 eingeführt.
Siehe auch „ findObjectsRecursively()“, „ objectForName()“ und „ childContexts()“.
[since 6.11] QList<QObject *> QQmlContext::findObjectsRecursively(const QString &id) const
Durchsucht diesen Kontext und seine untergeordneten Elemente rekursiv nach Objekten mit der ID „ id “. Gibt eine Liste dieser Objekte zurück.
In einem beliebigen Kontext kann es nur ein Objekt mit der angegebenen ID „ id “ geben, aber Sie können innerhalb eines Dokuments viele Kontexte erstellen, beispielsweise mit Ansichten und Delegaten. Jeder dieser Kontexte kann ein Objekt mit der angegebenen ID „ id “ enthalten.
Diese Funktion wurde in Qt 6.11 eingeführt.
Siehe auch „ findObjectRecursively()“, „ objectForName()“ und „ childContexts()“.
bool QQmlContext::isValid() const
Gibt zurück, ob der Kontext gültig ist.
Um gültig zu sein, muss ein Kontext über eine Engine verfügen, und seine „ contextObject “() – sofern vorhanden – darf nicht gelöscht worden sein.
QString QQmlContext::nameForObject(const QObject *object) const
Gibt den Namen von „ object “ in diesem Kontext zurück oder eine leere Zeichenkette, wenn „ object “ im Kontext nicht benannt ist. Objekte werden über „ setContextProperty()“ benannt, als Eigenschaften eines Kontextobjekts oder, im Falle von durch QML erstellten Kontexten, über IDs.
Verfügt das Objekt über mehrere Namen, wird der erste zurückgegeben.
Im Gegensatz zu ` contextProperty()` durchläuft diese Methode nicht die Kontexthierarchie. Wird der Name im aktuellen Kontext nicht gefunden, wird eine leere Zeichenkette zurückgegeben.
Siehe auch „ contextProperty “ () und „ objectForName “ ().
[since 6.2] QObject *QQmlContext::objectForName(const QString &name) const
Gibt das Objekt für eine angegebene „ name “ in diesem Kontext zurück. Gibt „nullptr“ zurück, wenn „ name “ im Kontext nicht verfügbar ist oder wenn der mit „ name “ verknüpfte Wert kein „ QObject “ ist. Objekte werden über „ setContextProperty()“, als Eigenschaften eines Kontextobjekts oder – im Falle von durch QML erstellten Kontexten – über IDs benannt. Im Gegensatz zu ` contextProperty()` durchläuft diese Methode nicht die Kontexthierarchie. Wird der Name im aktuellen Kontext nicht gefunden, wird `nullptr` zurückgegeben.
Diese Funktion wurde in Qt 6.2 eingeführt.
Siehe auch „ contextProperty “ () und „ nameForObject “ ().
QQmlContext *QQmlContext::parentContext() const
Gibt den übergeordneten Kontext zurück: ` QQmlContext` oder ` nullptr `, falls dieser Kontext keinen übergeordneten Kontext hat oder dieser bereits zerstört wurde.
QUrl QQmlContext::resolvedUrl(const QUrl &src) const
Löst die URL src relativ zur URL der übergeordneten Komponente auf.
Siehe auch QQmlEngine::baseUrl() und setBaseUrl().
void QQmlContext::setBaseUrl(const QUrl &baseUrl)
Legt explizit die URL fest, die resolvedUrl() für relative Verweise auf baseUrl verwenden wird.
Der Aufruf dieser Funktion überschreibt die standardmäßig verwendete URL der übergeordneten Komponente.
Siehe auch baseUrl() und resolvedUrl().
void QQmlContext::setContextObject(QObject *object)
Legen Sie das Kontext object fest.
Hinweis: Sie sollten keine Kontext-Objekte verwenden, um Werte in Ihre QML-Komponenten einzufügen. Verwenden Sie stattdessen Singletons oder reguläre Objekteigenschaften.
Siehe auch contextObject().
void QQmlContext::setContextProperties(const QList<QQmlContext::PropertyPair> &properties)
Legen Sie in diesem Kontext eine Reihe von „ properties “-Eigenschaften fest.
Das Setzen aller Eigenschaften in einem Schritt vermeidet unnötige Aktualisierungsausdrücke und wird daher anstelle des Aufrufs von ` setContextProperty()` für jede einzelne Eigenschaft empfohlen.
Hinweis: Sie sollten keine Kontexteigenschaften verwenden, um Werte in Ihre QML-Komponenten einzufügen. Verwenden Sie stattdessen Singletons oder reguläre Objekteigenschaften.
Siehe auch ` QQmlContext::setContextProperty()`.
void QQmlContext::setContextProperty(const QString &name, QObject *value)
Legen Sie die Eigenschaft „ value “ der Eigenschaft „ name “ in diesem Kontext fest.
QQmlContext Übernimmt nicht die Eigentümerschaft an ` value`.
Hinweis: Sie sollten keine Kontexteigenschaften verwenden, um Werte in Ihre QML-Komponenten einzufügen. Verwenden Sie stattdessen Singletons oder reguläre Objekteigenschaften.
Siehe auch ` contextProperty()`.
void QQmlContext::setContextProperty(const QString &name, const QVariant &value)
Legen Sie den Wert „ value “ für die Eigenschaft „ name “ in diesem Kontext fest.
Hinweis: Sie sollten keine Kontexteigenschaften verwenden, um Werte in Ihre QML-Komponenten einzufügen. Verwenden Sie stattdessen Singletons oder reguläre Objekteigenschaften.
© 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.
