QQmlProperty Class
QQmlProperty 类将访问由 QML 创建的对象上的属性进行了抽象化。更多内容...
| 头文件： | #include <QQmlProperty> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Qml) target_link_libraries(mytarget PRIVATE Qt6::Qml) |
| qmake： | QT += qml |
| 在 QML 中： | qmlProperty |
公共类型
| 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 的元类型系统，因此所有现有的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 view(QUrl::fromLocalFile("MyItem.qml"));
QQmlProperty property(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 | 该属性是信号属性。 |
属性文档
[read-only] name : const QString
该属性存储了 QML 属性的名称。
访问函数：
| QString | name() const |
另请参阅 QQmlProperty::object 。
[read-only] object : QObject* const
该属性存储由 QML 属性表示的QObject 。
访问函数：
| QObject * | object() const |
另请参阅 QQmlProperty::name 。
成员函数文档
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。
© 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.
