桌面应用 / 系统课时
用 Q_PROPERTY 暴露对象状态
用 Q_PROPERTY 暴露对象状态
本篇解决 QML 界面无法感知 C++ 状态变化的问题。通过 Q_PROPERTY 暴露属性,并配合 NOTIFY 信号建立响应式更新链路,让 C++ 状态变化能够自动驱动 QML 界面刷新。
学习目标
- 理解 Q_PROPERTY 在 Qt 对象模型中的作用
- 掌握 READ、WRITE、NOTIFY 三部分的配合方式
- 能够实现 C++ 状态变化自动同步到 QML
Q_PROPERTY 如何连接 C++ 与 QML
QML 的核心特点是声明式更新。界面通常不会主动查询 C++ 当前值,而是绑定到一个属性上,当属性变化时重新计算相关绑定。
普通 C++ 成员变量无法参与这种机制,需要通过 Q_PROPERTY 注册为 Qt 属性。
一个完整属性通常包含三个部分:
| 部分 | 作用 |
|---|---|
| READ | 提供 QML 读取当前值的方法 |
| WRITE | 提供 QML 修改值的方法 |
| NOTIFY | 属性变化时通知 QML 更新 |
其中 NOTIFY 是实现自动刷新的关键。如果没有通知信号,QML 绑定无法知道属性已经改变。
创建带通知的 C++ 属性
下面实现一个表示加载状态的对象。
cpp
// downloadmodel.h
#pragma once
#include <QObject>
class DownloadModel : public QObject
{
Q_OBJECT
Q_PROPERTY(int progress READ progress WRITE setProgress NOTIFY progressChanged)
public:
explicit DownloadModel(QObject *parent = nullptr);
int progress() const;
void setProgress(int value);
signals:
void progressChanged();
private:
int m_progress = 0;
};属性声明中的 progressChanged 信号表示:当 progress 值变化时,需要通知绑定它的 QML 表达式重新计算。
实现属性访问逻辑:
cpp
// downloadmodel.cpp
#include "downloadmodel.h"
DownloadModel::DownloadModel(QObject *parent)
: QObject(parent)
{
}
int DownloadModel::progress() const
{
return m_progress;
}
void DownloadModel::setProgress(int value)
{
if (m_progress == value) {
return;
}
m_progress = value;
emit progressChanged();
}预期结果
text
当 progress 从 10 变化到 20 时,progressChanged 信号触发,绑定 progress 的 QML 控件重新计算显示值。在 QML 中绑定 C++ 属性
假设该类型已经注册到 QML,可以直接绑定属性:
qml
import QtQuick
import MyApp
Rectangle {
width: 400
height: 100
DownloadModel {
id: download
}
Text {
text: "Progress: " + download.progress + "%"
}
}当 C++ 调用 setProgress() 并发出 progressChanged() 后,Text 会自动更新,无需手动调用刷新方法。
属性设计中的边界处理
Q_PROPERTY 并不只是暴露变量,还定义了对象状态的访问规则。实际开发中需要注意:
- WRITE 方法必须避免无意义重复通知,先判断新旧值是否相同
- NOTIFY 信号名称应与属性语义保持一致
- 多个属性变化时,应分别设计对应通知信号
- 只读状态可以省略 WRITE,只提供 READ 和 NOTIFY
例如只读版本号:
cpp
Q_PROPERTY(QString version READ version NOTIFY versionChanged)这种设计适合由 C++ 控制、QML 只负责展示的状态。
什么时候使用 Q_PROPERTY
当状态需要参与 QML 绑定、动画、条件判断或组件更新时,应优先使用 Q_PROPERTY。它比在 QML 中定时轮询 C++ 方法更高效,也能保持声明式界面的设计方式。
对于桌面应用中的用户信息、任务进度、设备状态、网络连接状态等持续变化的数据,Q_PROPERTY 加 NOTIFY 是连接 C++ 业务层和 QML 界面的基础方案。
按自己的节奏,确认真正理解。