深入理解Qt属性系统[Q_PROPERTY]

Qt 属性系统是 Qt 框架中一个非常核心和强大的部分，它提供了一种标准化的方法来访问对象的属性。这一系统不仅使得开发者能够以一致的方式处理各种数据类型，还为动态属性的管理提供了支持，并与 Qt 的元对象系统紧密集成。在这篇文章中，我们将详细介绍 Qt 属性系统的概念、实现机制和使用方式，以及它如何帮助开发者提升应用程序的灵活性和可维护性。

Q_PROPERTY

声明属性的类必须要继承QObject，并且使用Q_OBJECT宏，然后通过Q_PROPERTY宏来声明属性。

源码解释

Q_PROPERTY(type name(READ getFunction [WRITE setFunction] |MEMBER memberName [(READ getFunction | WRITE setFunction)])[RESET resetFunction][NOTIFY notifySignal][REVISION int | REVISION(int[, int])][DESIGNABLE bool][SCRIPTABLE bool][STORED bool][USER bool][CONSTANT][FINAL][REQUIRED])

基本结构

• type：属性的数据类型，支持以下类型：
  1. Qt内建类型：常见的Qt数据类型如QString、QDate、QTime、QDateTime、QUrl、QList、QMap、QStringList、QChar、QByteArray等。
  2. 标准C++类型：int、bool、double、float、char*等。
  3. 枚举类型
  4. 自定义类型：自定义的类也可以作为属性的类型，但是要满足以下条件：
     1. 类必须被Qt的元对象系统所知晓，这通常意味着类需要使用Q_DECLARE_METATYPE宏声明。
     2. 类需要提供公共的构造函数、拷贝构造函数和赋值运算符，以便Qt能够在内部处理属性的复制和赋值。
     3. 如果要通过QVariant进行存储或传递，类必须注册到Qt的类型系统中，使用qRegisterMetaType<ClassName>()。
• name：属性的名称

注意：这里的name和具体的成员变量名可以不同，因为Q_PROPERTY声明的属性不是具体的成员，属性是用来关联对应某个成员对象的。

访问函数

• READ：READ访问器函数，即读取属性值的函数。函数的返回值必须是属性对应类型或对该类型的const引用，函数体必须带const修饰。函数示例如下：

type getNameFunction() const;
const type& getNameFunction() const;

• WRITE：WRITE访问器函数，即修改属性值的函数。函数的返回值必须是void类型，并且只接受一个参数，可以是属性对应的类型，也可以是指向该类型的指针或引用。函数示例如下：

void setNameFunction(type val);
void setNameFunction(const type& val);

• MEMBER：直接指定类中的成员变量作为属性的存储，代替使用单独的读写方法。可以与READ或WRITE搭配使用来覆盖默认的成员访问。
  

可选修饰符

• RESET：指定一个函数用于重置属性到默认的初始状态。通常不带参数，没有返回值。
• NOTIFY：指定当属性值改变时要发出的信号。这在绑定和数据驱动的界面更新中非常有用。
• REVISION：用于版本控制，指明属性从哪个Qt版本开始可用。这主要用于与QML集成时的版本控制。
• DESIGNABLE：指定属性是否应该在Qt设计器中显示，默认为true。
• SCRIPTABLE：指定属性是否可以通过脚本访问，默认为true。
• STORED：指明属性是否应该被序列号，默认为true。如果属性是计算出来的，并不需要存储，可以设置为false。
• USER：指明这个属性是否被指定为该类的面向用户的属性或用户可编辑的属性。通常，每个类只有一个USER属性，默认为false。
• CONSTANT：标记属性为常量，一旦在构造函数中设置后不能改变。常用于只读的配置值。
• FINAL：指明这个属性在派生类中不能被重写。
• REQUIRED：属性的存在表明该属性应由该类的用户设置。这不是由 moc 强制执行的，并且对于暴露于 QML 的类来说最有用。在 QML 中，除非设置了所有必需属性，否则无法实例化具有必需属性的类。
  

使用示例

注意：

1. 使用READ和WRITE两个访问器函数在未指定MEMBER时需要显式定义
2. 在指定MEMBER时可以不用显式定义READ和WRITE两个访问器函数
3. READ和WRITE两个访问器函数主要的作用不是显式调用相应的函数，而是通过对象的property()和setProperty()来调用

只读属性

class Data : public QObject {Q_OBJECTQ_PROPERTY(QString name READ name FINAL)
public:explicit Data(QObject* parent = nullptr): QObject(parent){}QString name() const{return m_name;}private:QString m_name { "Data" };
};int main(int argc, char* argv[])
{QCoreApplication a(argc, argv);Data data;// 使用 property() 来获取属性值qDebug() << "Initial name:" << data.property("name").toString();// 使用 setProperty() 来修改属性值data.setProperty("name", "Updated Name");qDebug() << "Updated name:" << data.property("name").toString();return a.exec();
}

输出结果：

Initial name: "Data"
Updated name: "Data"

可读写属性

class Data : public QObject {Q_OBJECTQ_PROPERTY(QString name READ name WRITE setName FINAL)
public:explicit Data(QObject* parent = nullptr): QObject(parent){}QString name() const{return m_name;}void setName(const QString& name){if (name != m_name)m_name = name;}private:QString m_name { "Data" };
};int main(int argc, char* argv[])
{QCoreApplication a(argc, argv);Data data;// 使用 property() 来获取属性值qDebug() << "Initial name:" << data.property("name").toString();// 使用 setProperty() 来修改属性值data.setProperty("name", "Updated Name");qDebug() << "Updated name:" << data.property("name").toString();return a.exec();
}

输出结果：

Initial name: "Data"
Updated name: "Updated Name"

MEMBER关键字

class Data : public QObject {Q_OBJECTQ_PROPERTY(QString name MEMBER m_name FINAL)
public:explicit Data(QObject* parent = nullptr): QObject(parent){}private:QString m_name { "Data" };
};int main(int argc, char* argv[])
{QCoreApplication a(argc, argv);Data data;// 使用 property() 来获取属性值qDebug() << "Initial name:" << data.property("name").toString();// 使用 setProperty() 来修改属性值data.setProperty("name", "Updated Name");qDebug() << "Updated name:" << data.property("name").toString();return a.exec();
}

输出结果：

Initial name: "Data"
Updated name: "Updated Name"

使用MEMBER关键字时，用户无法通过实例对象显式调用getter和setter函数，只能通过property()和setProperty()来获取和设置。

NOTIFY关键字的使用

class Data : public QObject {Q_OBJECTQ_PROPERTY(QString name MEMBER m_name NOTIFY nameChanged FINAL)
public:explicit Data(QObject* parent = nullptr): QObject(parent){}signals:void nameChanged(const QString& name);private:QString m_name { "Data" };
};int main(int argc, char* argv[])
{QCoreApplication a(argc, argv);Data data;QObject::connect(&data, &Data::nameChanged, [&data](const QString& name) {qDebug() << "nameChanged: " << data.property("name");});// 使用 property() 来获取属性值qDebug() << "Initial name:" << data.property("name").toString();// 使用 setProperty() 来修改属性值data.setProperty("name", "Updated Name");qDebug() << "Updated name:" << data.property("name").toString();return a.exec();
}

输出结果：

Initial name: "Data"
nameChanged:  QVariant(QString, "Updated Name")
Updated name: "Updated Name"

属性系统的主要应用场景

C++和QML交互

首先，我们需要定义一个包含可观察属性的C++类。此类将发出属性变化的信号，QML界面将响应这些信号更新显示。
CppBackend.h

#ifndef CPPBACKEND_H
#define CPPBACKEND_H#include <QObject>
#include <QString>class CppBackend : public QObject {Q_OBJECTQ_PROPERTY(QString message READ message WRITE setMessage NOTIFY messageChanged)public:explicit CppBackend(QObject *parent = nullptr) : QObject(parent), m_message("Hello from C++!") {}QString message() const { return m_message; }public slots:void setMessage(const QString &message) {if (m_message != message) {m_message = message;emit messageChanged();}}signals:void messageChanged();private:QString m_message;
};#endif // CPPBACKEND_H

接下来，我们创建一个QML文件来显示message属性，并提供一个按钮来改变它。
main.qml

import QtQuick 2.15
import QtQuick.Window 2.15
import QtQuick.Controls 2.15Window {width: 640height: 480visible: truetitle: qsTr("Hello World")Column {anchors.centerIn: parentspacing: 20Text {id: displayTexttext: backend.messagefont.pointSize: 20}Button {text: "Change Message"onClicked: {backend.message = "Updated by QML!"}}}
}

在主程序中，我们将注册后端对象为QML可访问，并加载QML文件。
main.cpp

#include "CppBackend.h"
#include <QGuiApplication>
#include <QQmlApplicationEngine>
#include <QQmlContext>int main(int argc, char* argv[])
{
#if QT_VERSION < QT_VERSION_CHECK(6, 0, 0)QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling);
#endifQGuiApplication app(argc, argv);QQmlApplicationEngine engine;CppBackend backend;engine.rootContext()->setContextProperty("backend", &backend);const QUrl url(QStringLiteral("qrc:/main.qml"));QObject::connect(&engine,&QQmlApplicationEngine::objectCreated,&app,[url](QObject* obj, const QUrl& objUrl) {if (!obj && url == objUrl)QCoreApplication::exit(-1);},Qt::QueuedConnection);engine.load(url);return app.exec();
}

属性树形控件

属性树形控件的类虽然已经被移除，但QtCreator还是在使用的，可以通过Qt的源码查找qtpropertybrowser。
展示使用的代码：
TestData1.h

#ifndef TESTDATA1_H
#define TESTDATA1_H#include <QColor>
#include <QObject>class TestData1 : public QObject {Q_OBJECTQ_PROPERTY(int count READ count WRITE setCount NOTIFY countChanged FINAL)Q_PROPERTY(QColor bkColor READ bkColor WRITE setBkColor NOTIFY bkColorChanged FINAL)Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged FINAL)
public:explicit TestData1(QObject* parent = nullptr): QObject(parent){}int count() const { return m_count; }void setCount(int value){if (value != m_count) {m_count = value;emit countChanged(m_count);}}QColor bkColor() const { return m_bkColor; }void setBkColor(const QColor& color){if (color != m_bkColor) {m_bkColor = color;emit bkColorChanged(m_bkColor);}}QString name() const { return m_name; }void setName(const QString& value){if (value != m_name) {m_name = value;emit nameChanged(m_name);}}signals:void countChanged(int value);void bkColorChanged(const QColor& color);void nameChanged(const QString& name);private:int m_count { 1 };QColor m_bkColor { Qt::black };QString m_name { "TestData" };
};#endif // TESTDATA1_H

TestData2.h

#ifndef TESTDATA2_H
#define TESTDATA2_H#include <QColor>
#include <QObject>class TestData2 : public QObject {Q_OBJECTQ_PROPERTY(int number READ count WRITE setCount NOTIFY countChanged FINAL)Q_PROPERTY(QColor bkColor READ bkColor WRITE setBkColor NOTIFY bkColorChanged FINAL)Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged FINAL)
public:explicit TestData2(QObject* parent = nullptr): QObject(parent){}int count() const { return m_number; }void setCount(int value){if (value != m_number) {m_number = value;emit countChanged(m_number);}}QColor bkColor() const { return m_bkColor; }void setBkColor(const QColor& color){if (color != m_bkColor) {m_bkColor = color;emit bkColorChanged(m_bkColor);}}QString name() const { return m_name; }void setName(const QString& value){if (value != m_name) {m_name = value;emit nameChanged(m_name);}}signals:void countChanged(int value);void bkColorChanged(const QColor& color);void nameChanged(const QString& name);private:int m_number { 99 };QColor m_bkColor { Qt::blue };QString m_name { "TestData2" };
};
#endif // TESTDATA2_H

widget.h

#ifndef WIDGET_H
#define WIDGET_H#include "qtpropertybrowser/qteditorfactory.h"
#include "qtpropertybrowser/qttreepropertybrowser.h"
#include "qtpropertybrowser/qtvariantproperty.h"
#include "testdata1.h"
#include "testdata2.h"
#include <QListWidgetItem>
#include <QWidget>QT_BEGIN_NAMESPACE
namespace Ui {
class Widget;
}
QT_END_NAMESPACEclass Widget : public QWidget {Q_OBJECTpublic:Widget(QWidget* parent = nullptr);~Widget();private slots:void on_listWidget_currentItemChanged(QListWidgetItem* current, QListWidgetItem* previous);protected:void updateProperties(QObject* selectedObject);private:Ui::Widget* ui;QtVariantPropertyManager* m_variantManager;QtVariantEditorFactory* m_variantFactory;TestData1 m_data1;TestData1 m_data1_2;TestData2 m_data2;TestData2 m_data2_2;
};
#endif // WIDGET_H

widget.cpp

#include "widget.h"
#include "./ui_widget.h"
#include <QMetaProperty>Widget::Widget(QWidget* parent): QWidget(parent), ui(new Ui::Widget), m_variantManager(new QtVariantPropertyManager(this)), m_variantFactory(new QtVariantEditorFactory(this))
{ui->setupUi(this);m_data1.setName("TestData1");m_data1.setBkColor(Qt::red);m_data1_2.setName("TestData1_2");m_data1_2.setBkColor(Qt::yellow);m_data2.setCount(60);ui->widget->setFactoryForManager(m_variantManager, m_variantFactory);QtVariantProperty* item = m_variantManager->addProperty(QVariant::Double, "透明度");item->setValue(0.5);ui->widget->addProperty(item);
}Widget::~Widget()
{delete ui;
}void Widget::on_listWidget_currentItemChanged(QListWidgetItem* current, QListWidgetItem* previous)
{static int index = 0;int i = index % 4;if (i == 0)updateProperties(&m_data1);else if (i == 1)updateProperties(&m_data1_2);else if (i == 2)updateProperties(&m_data2);elseupdateProperties(&m_data2_2);index++;
}void Widget::updateProperties(QObject* selectedObject)
{ui->widget->clear();auto metaObj = selectedObject->metaObject();for (int i = 0; i < metaObj->propertyCount(); ++i) {auto propertyObj = metaObj->property(i);auto propertyName = propertyObj.name();auto propertyValue = selectedObject->property(propertyName);auto item = m_variantManager->addProperty(propertyValue.type(), propertyName);item->setValue(propertyValue);ui->widget->addProperty(item);connect(m_variantManager, &QtVariantPropertyManager::valueChanged,this, [selectedObject](QtProperty* prop, const QVariant& value) {selectedObject->setProperty(prop->propertyName().toStdString().c_str(), value);});}
}

注意：
ui->widget就是QtTreePropertyBrowser类。

效果：

总结

属性系统说到底就是建立在类的成员变量之上，并通过标准化的接口（getter和setter）以及元对象系统来增强这些成员的功能。
在很多UI和数据进行交互的时候，我们通常可以通过属性系统提供的标准化接口来实现，因为其带来以下好处：

1. 一致性和易用性

提供一个统一的方法来访问和修改对象的属性，这意味着无论你在哪里或如何使用这些对象，访问和修改属性的方式总是相同的。这种一致性减少了学习和使用不同对象时的认知负担，使得开发更直观，同时也减少了代码中可能出现的错误。

2. 封装和数据保护

通过标准化的 getter 和 setter 方法来访问和修改数据，这增强了封装性，保护了数据不被非法访问和修改。封装是面向对象编程中的一个核心概念，它隐藏了对象的内部状态和实现细节，只暴露有限的接口与外界交互。

3. 解耦和模块化

标准化接口促进了解耦和模块化设计。开发者可以更轻松地替换或修改内部实现而不影响使用这些对象的代码。这是因为外部代码依赖于接口而非具体实现，从而使得整个系统更加灵活和可维护。

4. 自动化工具和库的集成

标准化的属性接口使得自动化工具（如 GUI 设计器）和其他库（如序列化库、数据库映射工具）能够更容易地与你的代码集成。例如，一个自动化工具可以通过反射机制查找所有属性并允许用户在图形界面中配置它们。

5. 动态性和反射能力

Qt 的元对象系统依赖于标准化的属性接口来支持反射，即在运行时查询和操作对象的能力。这不仅有助于开发各种动态特性（如动态数据绑定和脚本集成），也使得开发者能够编写通用代码来处理不同类型的对象。

6. 跨语言和平台兼容性

标准化接口简化了在不同编程语言和平台间的对象交互。由于接口提供了清晰定义的交互点，因此可以更容易地将 Qt 应用与其他系统集成，或者在不同平台间迁移应用。