QQmlContext Class
QQmlContext 类定义了 QML 引擎中的上下文。更多
| 头文件： | #include <QQmlContext> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Qml)target_link_libraries(mytarget PRIVATE Qt6::Qml) |
| qmake： | QT += qml |
| 继承： | QObject |
公共类型
| struct | PropertyPair |
公共函数
| 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) |
详细说明
Contexts 保存 QML 文档中用id标识的对象。你可以使用nameForObject() 和objectForName() 来检索它们。
注意： 创建者有责任删除其构建的任何 QQmlContext。如果不再需要 QQmlContext，就必须明确地将其销毁。确保这一点的最简单方法是给 QQmlContext 一个parent 。
上下文层次结构
上下文形成一个层次结构。这个层次结构的根是 QML 引擎的root context 。每个 QML 组件在实例化时都会创建自己的上下文，有些 QML 元素还会为自己创建额外的上下文。
虽然在上下文中实例化的 QML 对象严格来说不属于该上下文，但它们的绑定属于该上下文。如果上下文被销毁，未完成的 QML 对象的属性绑定将停止评估。
上下文属性
上下文还允许把数据暴露给 QML 引擎实例化的 QML 组件。这些数据对任何工具，包括 Qt Quick Compiler以及 QML 文档的未来读者都不可见。只有当 QML 组件在你所设想的特定 C++ 上下文中实例化时，它才会暴露出来。在其他地方，可能会暴露不同的上下文数据。
与其使用 QML 上下文将数据暴露给 QML 组件，不如创建额外的对象属性来保存数据，或者使用singletons 。详细解释请参阅Exposing C++ State to QML（将 C++ 状态暴露给 QML）。
每个 QQmlContext 都包含一组不同于其QObject 属性的属性，允许数据通过名称显式绑定到上下文。上下文属性可通过调用QQmlContext::setContextProperty() 进行定义和更新。
为了简化绑定和维护大型数据集，可以在 QQmlContext 上设置上下文对象。上下文对象的所有属性都可以通过名称在上下文中找到，就好像它们都是通过调用QQmlContext::setContextProperty() 单独添加的一样。属性值的变化会通过属性的通知信号被检测到。与手动添加和维护上下文属性值相比，设置上下文对象既快又简单。
所有通过QQmlContext::setContextProperty() 明确添加的属性都优先于上下文对象的属性。
子上下文继承其父上下文属性；如果子上下文设置的上下文属性已存在于其父上下文中，则新的上下文属性优先于父上下文属性。
警告： 在上下文中创建对象后再设置上下文对象或添加新的上下文属性，是一项代价高昂的操作（基本上会强制重新评估所有绑定）。因此，如果需要使用上下文属性，至少应在使用上下文创建对象之前完成上下文的 "设置"。
另请参阅 Exposing Attributes of C++ Types to QML（向 QML 公开 C++ 类型的属性）。
成员函数文档
QQmlContext::QQmlContext(QQmlContext *parentContext, QObject *parent = nullptr)
用给定的parentContext 和QObject parent 创建一个新的 QQmlContext。
QQmlContext::QQmlContext(QQmlEngine *engine, QObject *parent = nullptr)
创建一个新的 QQmlContext 作为engine 的根上下文的子上下文，以及QObject parent 。
[override virtual noexcept] QQmlContext::~QQmlContext()
销毁QQmlContext 。
依赖于此上下文的任何表达式或子上下文都将失效，但不会被销毁（除非它们是QQmlContext 对象的父上下文）。
QUrl QQmlContext::baseUrl() const
返回组件的基本 URL，如果未设置，则返回包含组件的 URL。
另请参见 setBaseUrl()。
QObject *QQmlContext::contextObject() const
返回上下文对象，如果没有上下文对象，则返回nullptr 。
另请参见 setContextObject().
QVariant QQmlContext::contextProperty(const QString &name) const
以QVariant 的形式返回此上下文中name 属性的值。如果你知道你要找的属性是在当前上下文中使用 QML id 分配的QObject ，objectForName() 更方便、更快捷。与objectForName() 和nameForObject() 不同，如果name 在当前上下文中找不到，该方法会遍历上下文层次，并在父上下文中搜索。它还会考虑您可能设置的任何contextObject() 。
另请参见 setContextProperty()、objectForName()、nameForObject() 和contextObject()。
QQmlEngine *QQmlContext::engine() const
返回上下文的QQmlEngine ，如果上下文没有QQmlEngine 或QQmlEngine 已被销毁，则返回nullptr 。
bool QQmlContext::isValid() const
返回上下文是否有效。
上下文必须有一个引擎，并且contextObject()（如果有的话）必须没有被删除，这样的上下文才是有效的。
QString QQmlContext::nameForObject(const QObject *object) const
返回此上下文中object 的名称，如果上下文中没有object 的名称，则返回空字符串。对象通过setContextProperty() 命名，或作为上下文对象的属性命名，或在 QML 创建的上下文中通过 ids 命名。
如果对象有多个名称，则返回第一个名称。
与contextProperty() 不同，该方法不遍历上下文层次结构。如果在当前上下文中找不到名称，则返回空字符串。
另请参阅 contextProperty() 和objectForName()。
[since 6.2] QObject *QQmlContext::objectForName(const QString &name) const
返回上下文中给定name 的对象。如果name 在上下文中不可用，或者与name 关联的值不是QObject ，则返回 nullptr。对象由setContextProperty() 命名，或作为上下文对象的属性，或在 QML 创建上下文的情况下由 ids 命名。与contextProperty() 不同，该方法不遍历上下文层次结构。如果在当前上下文中找不到名称，则返回 nullptr。
该函数在 Qt 6.2 中引入。
另请参阅 contextProperty() 和nameForObject()。
QQmlContext *QQmlContext::parentContext() const
返回上下文的父节点QQmlContext ，如果没有父节点或父节点已被销毁，则返回nullptr 。
QUrl QQmlContext::resolvedUrl(const QUrl &src) const
解析相对于包含组件的 URL 的 URLsrc 。
另请参阅 QQmlEngine::baseUrl() 和setBaseUrl()。
void QQmlContext::setBaseUrl(const QUrl &baseUrl)
明确设置resolvedUrl() 对baseUrl 的相对引用所使用的 url。
调用此函数将覆盖默认使用的包含组件的 url。
另请参阅 baseUrl() 和resolvedUrl()。
void QQmlContext::setContextObject(QObject *object)
设置上下文object 。
注意： 您不应使用上下文对象将值注入 QML 组件。请使用 singletons 或常规对象属性。
另请参阅 contextObject() 。
void QQmlContext::setContextProperties(const QList<QQmlContext::PropertyPair> &properties)
为此上下文设置一批properties 。
在一个批次中设置所有属性可以避免不必要的刷新表达式，因此建议使用setContextProperty() 来代替对每个属性的调用。
注意： 您不应使用上下文属性将值注入 QML 组件。请使用单子或常规对象属性。
另请参阅 QQmlContext::setContextProperty().
void QQmlContext::setContextProperty(const QString &name, QObject *value)
设置此上下文中name 属性的value 。
QQmlContext 不拥有 的所有权。value
注意： 您不应使用上下文属性将值注入 QML 组件。请使用 singletons 或常规对象属性。
另请参阅 contextProperty().
void QQmlContext::setContextProperty(const QString &name, const QVariant &value)
设置此上下文name 属性的value 。
注意： 您不应使用上下文属性将值注入 QML 组件。请使用单子或常规对象属性。
© 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.
