QQmlContext Class
Die Klasse QQmlContext definiert einen Kontext innerhalb einer QML-Engine. Mehr...
| Kopfzeile: | #include <QQmlContext> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Qml)target_link_libraries(mytarget PRIVATE Qt6::Qml) |
| qmake: | QT += qml |
| Vererbungen: | 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 |
| QObject * | contextObject() const |
| QVariant | contextProperty(const QString &name) const |
| QQmlEngine * | engine() 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) |
Detaillierte Beschreibung
Kontexte enthalten die durch id identifizierten Objekte in einem QML-Dokument. Sie können nameForObject() und objectForName() verwenden, um sie abzurufen.
Hinweis: Es liegt in der Verantwortung des Erstellers, jeden von ihm konstruierten QQmlContext zu löschen. Wenn ein QQmlContext nicht mehr benötigt wird, muss er explizit zerstört werden. Der einfachste Weg, dies sicherzustellen, ist, dem QQmlContext eine parent zu geben.
Die Kontexthierarchie
Kontexte bilden eine Hierarchie. Die Wurzel dieser Hierarchie ist die root context der QML-Engine. Jede QML-Komponente erzeugt bei ihrer Instanziierung ihren eigenen Kontext, und einige QML-Elemente erzeugen für sich selbst zusätzliche Kontexte.
Während QML-Objekte, die in einem Kontext instanziiert werden, nicht strikt diesem Kontext gehören, sind es ihre Bindungen. Wenn ein Kontext zerstört wird, werden die Eigenschaftsbindungen der ausstehenden QML-Objekte nicht mehr ausgewertet.
Kontexteigenschaften
Kontexte ermöglichen es auch, den von der QML-Engine instanziierten QML-Komponenten Daten zur Verfügung zu stellen. Solche Daten sind unsichtbar für alle Werkzeuge, einschließlich der Qt Quick Compiler und für zukünftige Leser der fraglichen QML-Dokumente. Sie werden nur offengelegt, wenn die QML-Komponente in dem von Ihnen vorgesehenen spezifischen C++-Kontext instanziiert wird. An anderen Stellen können stattdessen andere Kontextdaten offengelegt werden.
Anstatt den QML-Kontext zu verwenden, um Daten für Ihre QML-Komponenten freizugeben, sollten Sie entweder zusätzliche Objekteigenschaften erstellen, um die Daten zu halten, oder singletons verwenden. Eine ausführliche Erläuterung finden Sie unter C++-Zustand für QML verfügbar machen.
Jeder QQmlContext enthält eine Reihe von Eigenschaften, die sich von den QObject Eigenschaften unterscheiden und die es ermöglichen, Daten explizit an einen Kontext zu binden. Die Kontexteigenschaften können durch den Aufruf von QQmlContext::setContextProperty() definiert und aktualisiert werden.
Um die Bindung und Pflege größerer Datensätze zu vereinfachen, kann ein Kontextobjekt auf einen QQmlContext gesetzt werden. Alle Eigenschaften des Kontextobjekts sind namentlich im Kontext verfügbar, so als ob sie alle einzeln durch Aufrufe von QQmlContext::setContextProperty() hinzugefügt worden wären. Änderungen an den Eigenschaftswerten werden durch das notify-Signal der Eigenschaft erkannt. Das Setzen eines Kontextobjekts ist sowohl schneller als auch einfacher als das manuelle Hinzufügen und Pflegen von Kontexteigenschaftswerten.
Alle Eigenschaften, die explizit durch QQmlContext::setContextProperty() hinzugefügt werden, haben Vorrang vor den Eigenschaften des Kontextobjekts.
Untergeordnete Kontexte erben die Kontexteigenschaften ihrer Eltern; wenn ein untergeordneter Kontext eine Kontexteigenschaft setzt, die bereits in seinem Elternteil existiert, überschreibt die neue Kontexteigenschaft die des Elternteils.
Warnung: Das Setzen des Kontextobjekts oder das Hinzufügen neuer Kontexteigenschaften, nachdem ein Objekt in diesem Kontext erstellt wurde, ist eine teure Operation (die im Wesentlichen alle Bindungen zu einer Neuauswertung zwingt). Wenn Sie also Kontexteigenschaften verwenden müssen, sollten Sie zumindest das "Setup" des Kontexts abschließen, bevor Sie ihn zur Erstellung von Objekten verwenden.
Siehe auch Attribute von C++-Typen für QML verfügbar machen.
Dokumentation der Mitgliedsfunktionen
QQmlContext::QQmlContext(QQmlContext *parentContext, QObject *parent = nullptr)
Erstellen Sie einen neuen QQmlContext mit dem angegebenen parentContext und dem QObject parent .
QQmlContext::QQmlContext(QQmlEngine *engine, QObject *parent = nullptr)
Erstellen Sie einen neuen QQmlContext als Kind des Wurzelkontextes von engine und den QObject parent .
[override virtual noexcept] QQmlContext::~QQmlContext()
Zerstört den QQmlContext.
Alle Ausdrücke oder Subkontexte, die von diesem Kontext abhängen, werden ungültig gemacht, aber nicht zerstört (es sei denn, sie sind dem Objekt QQmlContext übergeordnet).
QUrl QQmlContext::baseUrl() const
Liefert die Basis-URL der Komponente oder die enthaltende Komponente, wenn keine festgelegt ist.
Siehe auch setBaseUrl().
QObject *QQmlContext::contextObject() const
Gibt das Kontextobjekt zurück, oder nullptr, wenn kein Kontextobjekt 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 es sich bei der gesuchten Eigenschaft um eine QObject handelt, die über eine QML-ID im aktuellen Kontext zugewiesen wurde, ist objectForName() bequemer und schneller. Im Gegensatz zu objectForName() und nameForObject() durchläuft diese Methode die Kontexthierarchie und sucht in übergeordneten Kontexten, wenn die name nicht im aktuellen Kontext gefunden wird. Sie berücksichtigt auch alle contextObject(), die Sie möglicherweise gesetzt haben.
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 hat oder die QQmlEngine zerstört wurde.
bool QQmlContext::isValid() const
Gibt zurück, ob der Kontext gültig ist.
Um gültig zu sein, muss ein Kontext einen Motor haben und sein contextObject() darf nicht gelöscht worden sein.
QString QQmlContext::nameForObject(const QObject *object) const
Gibt den Namen von object in diesem Kontext zurück oder einen leeren String, wenn object nicht im Kontext benannt ist. Objekte werden durch setContextProperty() benannt, oder als Eigenschaften eines Kontextobjekts, oder durch ids im Fall von mit QML erstellten Kontexten.
Wenn das Objekt mehrere Namen hat, wird der erste zurückgegeben.
Im Gegensatz zu contextProperty() durchläuft diese Methode nicht die Kontexthierarchie. Wenn der Name im aktuellen Kontext nicht gefunden wird, wird ein leerer String zurückgegeben.
Siehe auch contextProperty() und objectForName().
[since 6.2] QObject *QQmlContext::objectForName(const QString &name) const
Gibt das Objekt für ein gegebenes 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 durch setContextProperty() oder als Eigenschaften eines Kontextobjekts oder durch ids im Fall von mit QML erstellten Kontexten benannt. Im Gegensatz zu contextProperty() durchläuft diese Methode nicht die Kontexthierarchie. Wenn der Name im aktuellen Kontext nicht gefunden wird, wird nullptr zurückgegeben.
Diese Funktion wurde in Qt 6.2 eingeführt.
Siehe auch contextProperty() und nameForObject().
QQmlContext *QQmlContext::parentContext() const
Rückgabe des übergeordneten Kontexts QQmlContext, oder nullptr, wenn dieser Kontext keinen übergeordneten Kontext hat oder der übergeordnete Kontext zerstört wurde.
QUrl QQmlContext::resolvedUrl(const QUrl &src) const
Löst die URL src relativ zur URL der enthaltenden 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 soll.
Durch den Aufruf dieser Funktion wird die standardmäßig verwendete URL der enthaltenden Komponente außer Kraft gesetzt.
Siehe auch baseUrl() und resolvedUrl().
void QQmlContext::setContextObject(QObject *object)
Setzen Sie den Kontext object.
Hinweis: Sie sollten keine Kontextobjekte verwenden, um Werte in Ihre QML-Komponenten zu injizieren. Verwenden Sie stattdessen Singletons oder reguläre Objekteigenschaften.
Siehe auch contextObject().
void QQmlContext::setContextProperties(const QList<QQmlContext::PropertyPair> &properties)
Setzt einen Stapel von properties auf diesen Kontext.
Das Setzen aller Eigenschaften in einem Stapel vermeidet unnötige Aktualisierungsausdrücke und wird daher empfohlen, anstatt setContextProperty() für jede einzelne Eigenschaft aufzurufen.
Hinweis: Sie sollten keine Kontexteigenschaften verwenden, um Werte in Ihre QML-Komponenten zu injizieren. Verwenden Sie stattdessen Singletons oder reguläre Objekteigenschaften.
Siehe auch QQmlContext::setContextProperty().
void QQmlContext::setContextProperty(const QString &name, QObject *value)
Setzen Sie die value der Eigenschaft name auf diesen Kontext.
QQmlContext übernimmt nicht das Eigentum an value.
Hinweis: Sie sollten keine Kontexteigenschaften verwenden, um Werte in Ihre QML-Komponenten zu injizieren. Verwenden Sie stattdessen Singletons oder reguläre Objekteigenschaften.
Siehe auch contextProperty().
void QQmlContext::setContextProperty(const QString &name, const QVariant &value)
Setzen Sie die value der name Eigenschaft auf diesen Kontext.
Hinweis: Sie sollten keine Kontexteigenschaften verwenden, um Werte in Ihre QML-Komponenten zu injizieren. Verwenden Sie stattdessen Singletons oder reguläre Objekteigenschaften.
© 2025 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.
