QQmlProperty Class
QQmlProperty 类抽象了对由 QML 创建的对象上的属性的访问。更多
| 头文件： | #include <QQmlProperty> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Qml)target_link_libraries(mytarget PRIVATE Qt6::Qml) |
| qmake： | QT += qml |
公共类型
| enum | PropertyTypeCategory { InvalidCategory, List, Object, Normal } |
| enum | Type { Invalid, Property, SignalProperty } |
公共函数
| QQmlProperty() | |
| QQmlProperty(QObject *obj) | |
| QQmlProperty(QObject *obj, QQmlContext *ctxt) | |
| QQmlProperty(QObject *obj, QQmlEngine *engine) | |
| QQmlProperty(QObject *obj, const QString &name) | |
| QQmlProperty(QObject *obj, const QString &name, QQmlContext *ctxt) | |
| QQmlProperty(QObject *obj, const QString &name, QQmlEngine *engine) | |
| QQmlProperty(const QQmlProperty &other) | |
| bool | connectNotifySignal(QObject *dest, const char *slot) const |
| bool | connectNotifySignal(QObject *dest, int method) const |
| bool | hasNotifySignal() const |
| int | index() const |
| bool | isDesignable() const |
| bool | isProperty() const |
| bool | isResettable() const |
| bool | isSignalProperty() const |
| bool | isValid() const |
| bool | isWritable() const |
| QMetaMethod | method() const |
| QString | name() const |
| bool | needsNotifySignal() const |
| QObject * | object() const |
| QMetaProperty | property() const |
| QMetaType | propertyMetaType() const |
| int | propertyType() const |
| QQmlProperty::PropertyTypeCategory | propertyTypeCategory() const |
| const char * | propertyTypeName() const |
| QVariant | read() const |
| bool | reset() const |
| QQmlProperty::Type | type() const |
| bool | write(const QVariant &value) const |
| QQmlProperty & | operator=(const QQmlProperty &other) |
| bool | operator==(const QQmlProperty &other) const |
静态公共成员
| QVariant | read(const QObject *object, const QString &name) |
| QVariant | read(const QObject *object, const QString &name, QQmlContext *ctxt) |
| QVariant | read(const QObject *object, const QString &name, QQmlEngine *engine) |
| bool | write(QObject *object, const QString &name, const QVariant &value) |
| bool | write(QObject *object, const QString &name, const QVariant &value, QQmlContext *ctxt) |
| bool | write(QObject *object, const QString &name, const QVariant &value, QQmlEngine *engine) |
详细说明
由于 QML 使用 Qt 的元类型系统（meta-type system），所有现有的QMetaObject 类都可用于反省 QML 创建的对象并与之交互。然而，QML 提供的一些新特性，如类型安全和附加属性，通过 QQmlProperty 类最容易使用，因为它简化了一些自然的复杂性。
与QMetaProperty 表示类类型上的属性不同，QQmlProperty 封装了特定对象实例上的属性。要读取一个属性的值，程序员需要创建一个 QQmlProperty 实例并调用read() 方法。同样，要写入属性值，也要使用write() 方法。
例如，下面的 QML 代码：
// MyItem.qml import QtQuick 2.0 Text { text: "A bit of text" }
可以使用 QQmlProperty 访问Text 对象的属性，如下所示：
#include <QQmlProperty>#include <QGraphicsObject>...QQuickView查看QUrl::fromLocalFile("MyItem.qml"))；QQmlPropertyproperty(view.rootObject(), "font.pixelSize")；qWarning() << "Current pixel size:" << property.read().toInt(); property.write(24)；qWarning() << "Pixel size should now be 24:" << property.read().toInt();
成员类型文件
enum QQmlProperty::PropertyTypeCategory
此枚举指定 QML 属性的类别。
| 常数 | 值 | 说明 |
|---|---|---|
QQmlProperty::InvalidCategory | 0 | 属性无效或为信号属性。 |
QQmlProperty::List | 1 | 该属性是QQmlListProperty 列表属性 |
QQmlProperty::Object | 2 | 该属性是QObject 派生类型指针 |
QQmlProperty::Normal | 3 | 该属性为正常值属性。 |
enum QQmlProperty::Type
此枚举指定 QML 属性的类型。
| 常量 | 值 | 说明 |
|---|---|---|
QQmlProperty::Invalid | 0 | 属性无效。 |
QQmlProperty::Property | 1 | 该属性是常规 Qt 属性。 |
QQmlProperty::SignalProperty | 2 | 该属性为信号属性。 |
成员函数文档
QQmlProperty::QQmlProperty()
创建无效的 QQmlProperty。
QQmlProperty::QQmlProperty(QObject *obj)
为obj 的默认属性创建一个 QQmlProperty。如果没有默认属性，将创建一个无效的 QQmlProperty。
QQmlProperty::QQmlProperty(QObject *obj, QQmlContext *ctxt)
使用context ctxt 为obj 的默认属性创建一个 QQmlProperty。如果没有默认属性，将创建一个无效的 QQmlProperty。
QQmlProperty::QQmlProperty(QObject *obj, QQmlEngine *engine)
使用engine 提供的 QML 组件实例化环境，为obj 的默认属性创建一个 QQmlProperty。如果没有默认属性，则会创建一个无效的 QQmlProperty。
QQmlProperty::QQmlProperty(QObject *obj, const QString &name)
为obj 的属性name 创建一个 QQmlProperty。
QQmlProperty::QQmlProperty(QObject *obj, const QString &name, QQmlContext *ctxt)
使用context ctxt 为obj 的属性name 创建一个 QQmlProperty。
在没有上下文的情况下创建 QQmlProperty 会导致某些属性（如附加属性）无法访问。
QQmlProperty::QQmlProperty(QObject *obj, const QString &name, QQmlEngine *engine)
使用engine 提供的 QML 组件实例化环境，为obj 的属性name 创建一个 QQmlProperty。
QQmlProperty::QQmlProperty(const QQmlProperty &other)
创建other 的副本。
bool QQmlProperty::connectNotifySignal(QObject *dest, const char *slot) const
将属性的更改通知信号连接到dest 对象的指定slot ，并返回 true。如果该元属性不代表常规 Qt 属性，或没有更改通知器信号，或dest 对象没有指定的slot ，则返回 false。
注意： slot 应使用 SLOT() 宏传递，以便正确识别。
bool QQmlProperty::connectNotifySignal(QObject *dest, int method) const
将属性的更改通知信号连接到dest 对象的指定method ，并返回 true。如果该元属性不代表常规 Qt 属性，或没有更改通知器信号，或dest 对象没有指定的method ，则返回 false。
bool QQmlProperty::hasNotifySignal() const
如果属性有更改通知信号，则返回 true，否则返回 false。
int QQmlProperty::index() const
返回属性的 Qt 元对象索引。
bool QQmlProperty::isDesignable() const
如果属性可设计，则返回 true，否则返回 false。
bool QQmlProperty::isProperty() const
如果QQmlProperty 代表常规 Qt 属性，则返回 true。
bool QQmlProperty::isResettable() const
如果属性可重置，则返回 true，否则返回 false。
bool QQmlProperty::isSignalProperty() const
如果QQmlProperty 表示 QML 信号属性，则返回 true。
bool QQmlProperty::isValid() const
如果QQmlProperty 指向有效属性，则返回 true，否则返回 false。
bool QQmlProperty::isWritable() const
如果属性可写，则返回 true，否则返回 false。
QMetaMethod QQmlProperty::method() const
如果是SignalProperty ，则返回该属性的QMetaMethod ，否则返回无效的QMetaMethod 。
QString QQmlProperty::name() const
返回此 QML 属性的名称。
注： 属性名称的获取函数。
bool QQmlProperty::needsNotifySignal() const
如果属性需要更改通知信号以保持绑定的最新状态，则返回 true，否则返回 false。
某些属性（如附加属性或其值从不更改的属性）不需要更改通知器。
QObject *QQmlProperty::object() const
返回QQmlProperty 的QObject 。
注： 属性对象的获取函数。
QMetaProperty QQmlProperty::property() const
返回与此 QML 属性相关的Qt property 。
QMetaType QQmlProperty::propertyMetaType() const
返回属性的元类型。
另请参见 propertyType 。
int QQmlProperty::propertyType() const
返回属性的元类型 ID，如果属性没有元类型，则返回QMetaType::UnknownType 。
另请参见 propertyMetaType 。
QQmlProperty::PropertyTypeCategory QQmlProperty::propertyTypeCategory() const
返回属性类别。
const char *QQmlProperty::propertyTypeName() const
返回属性的类型名称，如果属性没有类型名称，则返回 0。
QVariant QQmlProperty::read() const
返回属性值。
[static] QVariant QQmlProperty::read(const QObject *object, const QString &name)
返回object 的name 属性值。此方法等同于：
QQmlProperty p(object, name); p.read();
[static] QVariant QQmlProperty::read(const QObject *object, const QString &name, QQmlContext *ctxt)
使用context ctxt 返回object 的name 属性值。此方法等同于
QQmlProperty p(object, name, context); p.read();
[static] QVariant QQmlProperty::read(const QObject *object, const QString &name, QQmlEngine *engine)
使用engine 提供的 QML 组件实例化环境，返回object 的name 属性值。此方法等同于
QQmlProperty p(object, name, engine); p.read();
bool QQmlProperty::reset() const
重置属性，如果属性可重置，则返回 true。如果属性不可重置，则什么也不会发生，返回 false。
QQmlProperty::Type QQmlProperty::type() const
返回属性的类型。
bool QQmlProperty::write(const QVariant &value) const
将属性值设置为value 。成功时返回true ，如果因value 类型错误等原因无法设置属性，则返回false 。
[static] bool QQmlProperty::write(QObject *object, const QString &name, const QVariant &value)
将value 写入object 的name 属性。此方法等同于：
QQmlProperty p(object, name); p.write(value);
成功时返回true ，否则返回false 。
[static] bool QQmlProperty::write(QObject *object, const QString &name, const QVariant &value, QQmlContext *ctxt)
使用context ctxt 将value 写入object 的name 属性。此方法等同于
QQmlProperty p(object, name, ctxt); p.write(value);
成功时返回true ，否则返回false 。
[static] bool QQmlProperty::write(QObject *object, const QString &name, const QVariant &value, QQmlEngine *engine)
使用engine 提供的 QML 组件实例化环境，将value 写入object 的name 属性。此方法等同于
QQmlProperty p(object, name, engine); p.write(value);
成功时返回true ，否则返回false 。
QQmlProperty &QQmlProperty::operator=(const QQmlProperty &other)
将other 指定为QQmlProperty 。
bool QQmlProperty::operator==(const QQmlProperty &other) const
如果other 和此QQmlProperty 表示相同的属性，则返回 true。
© 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.
