QQmlContext 类
QQmlContext 类定义了一个 QML 引擎中的上下文。《更多信息...》
| 头文件 | #include <QQmlContext> |
| CMake | find_package(Qt6 REQUIRED COMPONENTS Qml) target_link_libraries(mytarget PRIVATE Qt6::Qml) |
| qmake | QT += qml |
| 继承 | QObject |
Public Types
| struct | PropertyPair |
Public Functions
| QQmlContext(QQmlEngine *engine, QObject *parent = nullptr) | |
| QQmlContext(QQmlContext *parentContext, 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) |
详细描述
上下文保留 QML 文档中由 id 标识的对象。您可以使用 nameForObject() 和 objectForName() 来检索它们。
注意：创建 QQmlContext 的责任人必须删除其构建的任何 QQmlContext。如果一个 QQmlContext 不再需要，则必须显式销毁。确保这一点的最简单方法是给 QQmlContext 一个 parent。
上下文层次结构
上下文形成一个层次结构。这个层次结构的根是QML引擎的根上下文。每个QML组件在实例化时会创建自己的上下文，有些QML元素还会为自己的创建额外的上下文。
虽然在某个上下文中实例化的QML对象并不严格属于该上下文，但它们的绑定确实如此。如果一个上下文被销毁，未完成的QML对象的属性绑定将停止评估。
上下文属性
上下文还允许数据被QML引擎实例化的QML组件所访问。这种数据对于任何工具都是不可见的，包括Qt Quick 编译器以及未来阅读相关的QML文档的人。只有当QML组件在那个特定的C++上下文中实例化时，它才会被公开。在其他地方，可能会公开不同的上下文数据。
您不应该使用QML上下文来将数据公开给您的QML组件，而应该创建额外的对象属性来保存数据或使用单例。请参阅将C++状态公开给QML获取详细解释。
每个QQmlContext包含一组属性，与它的QObject属性不同，允许通过名称显式绑定数据到上下文。可以通过调用QQmlContext::setContextProperty()来定义和更新上下文属性。
为了简化绑定和管理较大的数据集，可以在QQmlContext上设置一个上下文对象。上下文对象的任何属性都可以通过名称在上下文中访问，就像它们都是通过调用QQmlContext::setContextProperty()单独添加的一样。通过属性的notify信号检测属性值的变化。设置上下文对象既快又简单，远比手动添加和维护上下文属性值要简单。
通过QQmlContext::setContextProperty()()显式添加的所有属性都优先于上下文对象的属性。
子上下文继承其父上下文属性；如果子上下文设置了已在父上下文中存在的上下文属性，则新的上下文属性将覆盖父类的属性。
警告：在已在该上下文中创建对象之后设置上下文对象或添加新的上下文属性是一项昂贵的操作（相当于迫使所有绑定重新评估）。因此，如果您需要使用上下文属性，至少应该在将其用于创建任何对象之前完成上下文的“设置”。
另请参阅：将C++类型的属性公开给QML.
成员函数说明
QQmlContext::QQmlContext(QQmlEngine *engine, QObject *parent = nullptr)
创建一个新的QQmlContext，作为engine的根上下文的子上下文，以及QObject parent。
QQmlContext::QQmlContext(QQmlContext *parentContext, QObject *parent = nullptr)
使用给定的parentContext创建一个新的QQmlContext，以及QObject parent。
[重写虚函数] 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
返回上下文是否有效。
为了有效，上下文必须有一个QQmlEngine，并且如果有，它的contextObject不得已被删除。
QString QQmlContext::nameForObject(const QObject *object) const
返回在此上下文中object的名称，如果object在该上下文中未命名则返回空字符串。对象通过setContextProperty()、上下文对象的属性或通过QML创建上下文时的id进行命名。
如果对象有多个名称，则返回第一个。
与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 解决 URL src。
另请参阅 QQmlEngine::baseUrl() 和 setBaseUrl()。
void QQmlContext::setBaseUrl(const QUrl &baseUrl)
显式设置 resolvedUrl() 将用于相对引用的 baseUrl。
调用此函数将覆盖默认情况下由包含组件使用的 URL。
另请参阅 baseUrl() 和 resolvedUrl()。
void QQmlContext::setContextObject(QObject *object)
设置上下文 object。
注意： 您不应使用上下文对象来向您的 QML 组件注入值。请使用单例或常规对象属性代替。
另请参阅 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 组件注入值。请使用单例或常规对象属性代替。
另请参阅 contextProperty()。
void QQmlContext::setContextProperty(const QString &name, const QVariant &value)
在此上下文中设置 name 属性的 value。
注意： 您不应使用上下文属性来向您的 QML 组件注入值。请使用单例或常规对象属性代替。
© 2024 The Qt Company Ltd。本文件中包含的文档贡献是各自所有者的版权。所提供的文档是根据免费软件基金会发布的 GNU 自由文档许可协议版本 1.3 许可的。Qt 及其相关标志是 The Qt Company Ltd. 在芬兰和/或其他国家的商标。所有其他商标均为其各自所有者的财产。
