桌面应用 / 系统课时

用 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 界面的基础方案。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 Q_PROPERTY 暴露对象状态

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通