QC++ / Qt 学习之路

实战项目三:数据监控仪表盘(Qt Quick + QML)

用 QML 做实时曲线仪表盘,打通采集线程与图表绘制

进阶第 40 / 48 章第五篇 · QML 与实战项目

#需求与整体架构

第三个项目做一个数据监控仪表盘:实时显示多台设备的 CPU/内存/温度曲线,异常时产生告警,配置面板可调整采样周期与阈值。它是前两个项目的综合体:C++ 负责采集与模型,QML 负责渲染与交互,二者通过 QAbstractListModel 与属性绑定衔接。这也是工业 HMI、运维看板最典型的形态。

生产监控 · 实时 LIVE 刷新 导出 设置 采样周期 1s · Modbus TCP 温度 68.5 ℃ 压力 0.42 MPa 流量 12.8 L/s 转速 1450 rpm 压力超限 14:31 温度偏高 14:28 已恢复 14:20 实时趋势 温度 压力 1h 6h 24h 100 75 50 25 0 08:00 10:00 12:00 14:00 16:00 运行时长 128 h 26 m 今日产量 8,420 件 良品率 98.6 % 最近更新 14:32:07 · 数据点 3,600 Qt Quick · QML 指标卡 Rectangle 告警列表 ListView ChartView 折线趋势 状态栏 Row
数据监控仪表盘的界面布局

功能清单:

  • 多路数据源(本例用模拟数据,可替换为串口/HTTP/MQTT 真实采集);
  • 实时曲线(最近 120 个采样点,滚动窗口);
  • 告警列表(超阈值自动入列,可确认/清除);
  • 配置面板(采样周期、阈值、启停);
  • 主题切换(浅色/深色);
  • KPI 卡片区(总数/在线数/告警数)。

目录结构与运行时架构如下(上半部分是文件划分,下半部分是数据流向):

Text
Dashboard/
├── CMakeLists.txt
├── src/
│   ├── main.cpp
│   ├── monitor.h/.cpp          # 门面对象,聚合所有模型
│   ├── collector.h/.cpp        # 采集器,运行在子线程
│   ├── devicemodel.h/.cpp      # QAbstractListModel(设备)
│   └── alarmmodel.h/.cpp       # QAbstractListModel(告警)
└── qml/
    ├── Main.qml  KpiRow.qml  ChartPanel.qml
    └── AlarmList.qml  ConfigPanel.qml

────────────────────── 运行时架构 ──────────────────────
│                    QML 层(渲染/交互)                    │
│  Main.qml                                                │
│   ├── KpiRow      (绑定 monitor.onlineCount 等属性)       │
│   ├── ChartPanel  (Canvas 自绘曲线,Timer 触发 requestPaint)│
│   ├── AlarmList   (model: monitor.alarmModel)            │
│   └── ConfigPanel (修改 monitor.sampleInterval)           │
└───────────────┬─────────────────────────────────────────┘
                │  Q_PROPERTY / Q_INVOKABLE / 信号
┌───────────────┴─────────────────────────────────────────┐
│              C++ 层(逻辑/数据,主线程)                   │
│  Monitor : QObject                                       │
│   ├── DeviceModel : QAbstractListModel  (设备列表)        │
│   ├── AlarmModel  : QAbstractListModel  (告警列表)        │
│   ├── RingBuffer<double>                (曲线点,非 GUI)  │
│   └── Q_PROPERTY: onlineCount / alarmCount / interval    │
└───────────────┬─────────────────────────────────────────┘
                │  Qt::QueuedConnection 信号(线程安全)
┌───────────────┴─────────────────────────────────────────┘
│          采集线程 Collector : QObject(moveToThread)      │
│   定时器采样 → emit sampleReady(deviceId, value)          │
└─────────────────────────────────────────────────────────┘

关键约束:采集在工作线程,模型与 QML 在主线程,两者只通过排队信号通信。图中的每一条竖线都不能被"直接调用"跨越。

#目录结构与构建

src/ 与 qml/ 严格分开:C++ 不引用任何 QML 文件,QML 只通过注册的类型名和属性名访问 C++。这样双方都能独立重构,比如把 Canvas 换成 QtCharts 时,C++ 侧一行都不用动。

CMake
cmake_minimum_required(VERSION 3.16)
project(Dashboard LANGUAGES CXX)

find_package(Qt6 REQUIRED COMPONENTS Quick)
qt_standard_project_setup()

qt_add_executable(Dashboard
    src/main.cpp src/monitor.cpp src/collector.cpp
    src/devicemodel.cpp src/alarmmodel.cpp
)

qt_add_qml_module(Dashboard
    URI Dashboard
    VERSION 1.0
    QML_FILES
        qml/Main.qml
        qml/KpiRow.qml
        qml/ChartPanel.qml
        qml/AlarmList.qml
        qml/ConfigPanel.qml
)

target_include_directories(Dashboard PRIVATE src)
target_link_libraries(Dashboard PRIVATE Qt6::Quick)

#C++ 后端:采集线程与模型

采集器是个普通 QObject,用 moveToThread 挪到子线程,靠 QTimer 驱动采样。注意它的定时器要在目标线程启动(在 start() 槽里创建,而不是构造函数里),否则定时器仍属于主线程。

C++
// collector.h
#pragma once
#include <QObject>
#include <QTimer>
#include <QRandomGenerator>

class Collector : public QObject
{
    Q_OBJECT
public:
    explicit Collector(QObject *parent = nullptr) : QObject(parent) {}

public slots:
    void start(int intervalMs) {
        delete m_timer;
        m_timer = new QTimer(this);          // 在子线程中构造 → 属于子线程
        m_timer->setInterval(intervalMs);
        connect(m_timer, &QTimer::timeout, this, &Collector::doSample);
        m_timer->start();
    }
    void stop() { if (m_timer) m_timer->stop(); }
    void setInterval(int ms) { if (m_timer) m_timer->setInterval(ms); }

signals:
    void sampleReady(int deviceId, double value);   // 跨线程,自动排队

private slots:
    void doSample() {
        for (int i = 0; i < m_deviceCount; ++i) {
            // 真实项目这里换成读串口 / 发 HTTP / 订阅 MQTT
            double v = 30 + 40 * QRandomGenerator::global()->bounded(1.0)
                     + 15 * std::sin(m_tick * 0.1 + i);
            emit sampleReady(i, v);
        }
        ++m_tick;
    }

private:
    QTimer *m_timer = nullptr;
    int  m_deviceCount = 4;
    int  m_tick = 0;
};

Monitor 是暴露给 QML 的门面。它把子线程的数据接入主线程模型,并统计 KPI:

C++
// monitor.h
#pragma once
#include <QObject>
#include <QThread>
#include "devicemodel.h"
#include "alarmmodel.h"
#include "collector.h"

class Monitor : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    Q_PROPERTY(DeviceModel* deviceModel READ deviceModel CONSTANT)
    Q_PROPERTY(AlarmModel*  alarmModel  READ alarmModel  CONSTANT)
    Q_PROPERTY(int onlineCount  READ onlineCount  NOTIFY statsChanged)
    Q_PROPERTY(int alarmCount   READ alarmCount   NOTIFY statsChanged)
    Q_PROPERTY(int sampleInterval READ sampleInterval WRITE setSampleInterval NOTIFY sampleIntervalChanged)
    Q_PROPERTY(bool running READ running NOTIFY runningChanged)

public:
    explicit Monitor(QObject *parent = nullptr);
    ~Monitor() override;

    DeviceModel* deviceModel() const { return m_devices; }
    AlarmModel*  alarmModel()  const { return m_alarms; }
    int onlineCount() const { return m_online; }
    int alarmCount()  const { return m_alarms->rowCount(); }
    int sampleInterval() const { return m_interval; }
    bool running() const { return m_running; }

    void setSampleInterval(int ms);
    Q_INVOKABLE void start();
    Q_INVOKABLE void stop();
    Q_INVOKABLE QVariantList series(int deviceId) const;   // 供 Canvas 取点

signals:
    void statsChanged();
    void sampleIntervalChanged();
    void runningChanged();
    void startCollector(int intervalMs);                   // 发往子线程
    void stopCollector();

private slots:
    void onSample(int deviceId, double value);             // 主线程执行

private:
    DeviceModel *m_devices;
    AlarmModel  *m_alarms;
    Collector   *m_collector;
    QThread     *m_thread;
    QVector<QVector<double>> m_series;   // 每设备一条环形曲线
    double m_threshold = 75.0;
    int    m_interval = 500;
    int    m_online = 0;
    bool   m_running = false;
};
C++
// monitor.cpp(关键实现)
Monitor::Monitor(QObject *parent) : QObject(parent)
{
    m_devices = new DeviceModel(this);
    m_alarms  = new AlarmModel(this);
    for (int i = 0; i < 4; ++i) {
        m_devices->addDevice(QStringLiteral("设备-%1").arg(i + 1), QStringLiteral("10.0.0.%1").arg(i + 10));
        m_series.append(QVector<double>());
    }

    m_collector = new Collector;              // 不能有 parent!
    m_thread    = new QThread(this);
    m_collector->moveToThread(m_thread);

    connect(m_thread, &QThread::finished, m_collector, &QObject::deleteLater);
    // 这两条是跨线程的,默认 QueuedConnection:安全
    connect(this, &Monitor::startCollector, m_collector, &Collector::start);
    connect(this, &Monitor::stopCollector,  m_collector, &Collector::stop);
    // 子线程 → 主线程,同样是排队连接
    connect(m_collector, &Collector::sampleReady, this, &Monitor::onSample);

    m_thread->start();
}

Monitor::~Monitor()
{
    m_thread->quit();
    m_thread->wait(3000);        // 必须等线程退出再析构
}

void Monitor::onSample(int deviceId, double value)
{
    // 此函数在主线程执行,可以安全改模型
    auto &s = m_series[deviceId];
    s.append(value);
    if (s.size() > 120) s.removeFirst();        // 固定窗口,防止无限增长

    m_devices->updateValue(deviceId, value);

    if (value > m_threshold) {                  // 阈值告警,带简单去抖
        if (!m_alarms->hasActiveAlarm(deviceId))
            m_alarms->addAlarm(deviceId, QStringLiteral("数值 %1 超过阈值 %2")
                                             .arg(value, 0, 'f', 1).arg(m_threshold), value);
    }
    emit statsChanged();
}

QVariantList Monitor::series(int deviceId) const
{
    QVariantList out;
    if (deviceId < 0 || deviceId >= m_series.size()) return out;
    out.reserve(m_series[deviceId].size());
    for (double v : m_series[deviceId]) out.append(v);
    return out;
}

Monitor::series() 返回 QVariantList 是权衡后的选择:每次 Canvas 重绘都要遍历点数(120 个),走 QVariant 有一次装箱开销,但换来的是 QML 侧代码极其简单,且不需要为曲线单独再写一个模型。如果你的采样率高达几百赫兹、点数上万,就应该改为让 C++ 直接暴露一个 Q_INVOKABLE double pointAt(int i) 供 JS 循环调用,或者用 QQuickPaintedItem(C++ 里用 QPainter 画)彻底避开 JS 层——本例的量级下不必过早优化。

要点:

  • m_collector 不能有 parent,否则 moveToThread 会因为"对象有父对象"而失败(Qt 会打印 "Cannot move objects with a parent")。
  • ~Monitor() 里 quit() + wait() 是必须的,否则程序退出时线程还在跑,会崩溃或报 "QThread: Destroyed while thread is still running"。
  • Q_PROPERTY(... CONSTANT) 用于那些生命周期内不会变指针的模型,省掉无意义的 NOTIFY 信号,也避免了绑定循环。
  • 告警加去抖(hasActiveAlarm 判断),否则超阈值时每 500ms 塞一条,列表瞬间爆炸。

#QML 界面:Canvas 自绘曲线

Qt 官方有 QtCharts 模块(商业授权下功能更全,开源版也有 LGPL 的 QtCharts),但它对高频刷新(10Hz 以上)压力较大,且样式定制受限。做监控类界面更常见的做法是自己用 Canvas 画,代码量不大、性能可控。

QML
// ChartPanel.qml
import QtQuick

Item {
    id: root
    property var  monitor: null
    property int  deviceId: 0
    property real yMin: 0
    property real yMax: 100
    property color lineColor: "#2196F3"

    // 数据版本号:C++ 每次采样后 +1,作为重绘触发源
    property int revision: 0

    Canvas {
        id: canvas
        anchors.fill: parent
        antialiasing: true
        renderTarget: Canvas.FramebufferObject   // 大数据量时更快
        renderStrategy: Canvas.Threaded          // 在独立线程渲染,不阻塞 UI

        // 只在 revision 变化时重绘,而不是用 Timer 无脑刷
        onPaint: {
            const ctx = getContext("2d");
            ctx.reset();
            const w = width, h = height;

            // 背景网格
            ctx.strokeStyle = Theme.gridColor;
            ctx.lineWidth = 1;
            for (let i = 0; i <= 4; i++) {
                const y = h * i / 4;
                ctx.beginPath(); ctx.moveTo(0, y); ctx.lineTo(w, y); ctx.stroke();
            }

            const pts = root.monitor ? root.monitor.series(root.deviceId) : [];
            if (pts.length < 2) return;

            const toY = v => h - (v - root.yMin) / (root.yMax - root.yMin) * h;
            const stepX = w / 120;

            // 填充区域
            ctx.beginPath();
            ctx.moveTo(0, toY(pts[0]));
            for (let i = 1; i < pts.length; i++)
                ctx.lineTo(i * stepX, toY(pts[i]));
            ctx.lineTo((pts.length - 1) * stepX, h);
            ctx.lineTo(0, h);
            ctx.closePath();
            ctx.fillStyle = Qt.alpha(root.lineColor, 0.15);
            ctx.fill();

            // 折线
            ctx.beginPath();
            ctx.moveTo(0, toY(pts[0]));
            for (let i = 1; i < pts.length; i++)
                ctx.lineTo(i * stepX, toY(pts[i]));
            ctx.strokeStyle = root.lineColor;
            ctx.lineWidth = 2;
            ctx.stroke();

            // 阈值线
            const ty = toY(root.monitor ? 75 : 0);
            ctx.strokeStyle = "#F44336";
            ctx.setLineDash([4, 4]);
            ctx.beginPath(); ctx.moveTo(0, ty); ctx.lineTo(w, ty); ctx.stroke();
            ctx.setLineDash([]);
        }
    }

    // 关键:用 Connections 监听 C++ 的 statsChanged,递增 revision 触发重绘
    Connections {
        target: root.monitor
        function onStatsChanged() {
            revisionChangedTimer.restart()
        }
    }

    // 合并重绘:把高频采样降频到最多 20fps,避免每一条数据都重绘
    Timer {
        id: revisionChangedTimer
        interval: 50
        repeat: false
        onTriggered: { root.revision++; canvas.requestPaint() }
    }
}

性能是关键考量,监控类界面最常见的失败模式是"刚启动很流畅,跑半小时开始卡顿",根因几乎总是无界增长(数据点无限累积、日志对象不释放)或刷新频率跟着采样率走。三条经验:

  1. 不要在每次采样时重绘。人眼 20fps 就够了,采集可能 100Hz。用一个 restart() 型的单次定时器做节流(throttle),最多 20 次/秒重绘。注意这里用的是 restart() 而不是 start():高频 restart 会把重绘时刻不断推后,直到数据流暂停才真正画一次,正好达到"合并绘制"的效果,代价是极低的数据延迟。
  2. renderStrategy: Canvas.Threaded 把绘制放到独立线程,UI 线程不会被长绘制卡住。
  3. 曲线点数必须固定(120 个),QVector::removeFirst() 虽是 O(n),但 n=120 时开销可忽略;真到上万点应改用环形缓冲(只移动读指针,O(1))。另外 onPaint 里不要分配大对象或做字符串格式化,它是每秒二十次的热路径。

还有一条容易被忽略:多个 ChartPanel 之间不共享取数逻辑,每个面板各自调用一次 monitor.series(id)。四路曲线时无所谓,二十路时就该让 C++ 一次性返回全部序列,避免 JS 反复穿越语言边界。

#主界面组装与主题切换

QML
// Main.qml
import QtQuick
import QtQuick.Controls
import QtQuick.Layouts
import Dashboard

ApplicationWindow {
    visible: true
    width: 1100; height: 700
    title: "数据监控仪表盘"

    Monitor { id: monitor }        // QML_ELEMENT 注册的类型

    property bool dark: false

    ColumnLayout {
        anchors.fill: parent
        anchors.margins: 16
        spacing: 12

        // KPI 卡片:直接绑定 C++ 属性
        RowLayout {
            Layout.fillWidth: true
            spacing: 12
            Repeater {
                model: [
                    { label: "设备总数", value: monitor.deviceModel.rowCount(), color: "#2196F3" },
                    { label: "在线",     value: monitor.onlineCount,           color: "#4CAF50" },
                    { label: "告警",     value: monitor.alarmCount,           color: "#F44336" }
                ]
                delegate: Rectangle {
                    required property var modelData
                    Layout.fillWidth: true; height: 72; radius: 8
                    color: dark ? "#1E1E1E" : "#FFFFFF"
                    border.color: dark ? "#333" : "#E0E0E0"
                    ColumnLayout {
                        anchors.centerIn: parent
                        Label { text: modelData.value; font.pixelSize: 24; font.bold: true
                                color: modelData.color; Layout.alignment: Qt.AlignHCenter }
                        Label { text: modelData.label; font.pixelSize: 12
                                color: dark ? "#AAA" : "#757575"; Layout.alignment: Qt.AlignHCenter }
                    }
                }
            }
        }

        // 曲线区
        RowLayout {
            Layout.fillWidth: true; Layout.fillHeight: true
            spacing: 12
            Repeater {
                model: monitor.deviceModel.rowCount()
                delegate: ChartPanel {
                    required property int index
                    Layout.fillWidth: true; Layout.fillHeight: true
                    monitor: monitor
                    deviceId: index
                    lineColor: ["#2196F3", "#4CAF50", "#FF9800", "#9C27B0"][index]
                }
            }
        }

        // 告警列表
        ListView {
            Layout.fillWidth: true
            Layout.preferredHeight: 140
            model: monitor.alarmModel
            clip: true
            spacing: 4
            delegate: Rectangle {
                width: ListView.view.width; height: 36; radius: 4
                color: dark ? "#2A2A2A" : "#FFEBEE"
                RowLayout {
                    anchors.fill: parent; anchors.margins: 8
                    Label { text: model.time; font.pixelSize: 12; color: "#999" }
                    Label { text: model.device; font.bold: true; Layout.preferredWidth: 80 }
                    Label { text: model.message; Layout.fillWidth: true; elide: Text.ElideRight }
                    Button { text: "确认"; flat: true
                             onClicked: monitor.alarmModel.acknowledge(index) }
                }
            }
        }

        // 配置面板
        RowLayout {
            Layout.fillWidth: true
            Label { text: "采样周期" }
            Slider { id: slider; from: 100; to: 2000; stepSize: 100; value: 500
                     onMoved: monitor.sampleInterval = value }
            Label { text: Math.round(slider.value) + " ms" }
            Button { text: monitor.running ? "停止" : "开始"
                     onClicked: monitor.running ? monitor.stop() : monitor.start() }
            Switch { text: "深色主题"; onToggled: dark = checked }
        }
    }
}

主题切换用一个全局的 dark 属性 + 各组件绑定表达式即可,改一处、全界面自动重绘,这正是属性绑定的价值所在。但在组件较多时,把 dark ? "#1E1E1E" : "#FFFFFF" 这类三元表达式散落进每个文件会带来两个问题:颜色值到处重复,改主题要改十几处;而且新增组件时容易忘记跟着改。更规范的做法是做一个 Theme 单例(Qt 6 用 pragma Singleton),把颜色集中定义,组件只绑定 Theme.surface 这样的语义名,将来加一套"高对比度"主题也只需新增一个字段集合。

QML
// Theme.qml
pragma Singleton
import QtQuick

QtObject {
    property bool dark: false
    property color background: dark ? "#121212" : "#F5F5F5"
    property color surface:    dark ? "#1E1E1E" : "#FFFFFF"
    property color text:       dark ? "#E0E0E0" : "#212121"
    property color gridColor:  dark ? "#2E2E2E" : "#E8E8E8"
}

#小结

  1. 架构铁律:采集在子线程,模型与 QML 在主线程,只通过 QueuedConnection 信号通信;moveToThread 的对象不能有 parent,析构前必须 quit() + wait()。
  2. Monitor 作为门面聚合多个模型,用 Q_PROPERTY(... CONSTANT) 暴露模型指针,用带 NOTIFY 的属性暴露 KPI。
  3. Canvas 自绘曲线比 QtCharts 更可控;关键点是用节流定时器把高频采样降频到 20fps 再 requestPaint()。
  4. 曲线点数必须固定(如 120),否则内存与时间随运行时长线性增长;告警要加去抖,否则列表会被瞬间刷爆。
  5. 主题切换用一个 pragma Singleton 的 Theme 对象集中管理颜色,全界面靠绑定自动更新。

#练习

  1. 把模拟数据源替换成真实采集:读取本机 /proc/stat(Linux)或 PDH(Windows)计算 CPU 占用率,验证曲线能反映真实负载。
  2. 给 ChartPanel 加交互:鼠标悬停显示十字准线与当前点数值(提示:MouseArea 的 onPositionChanged + 在 Canvas 上叠加一个 Rectangle 游标)。
  3. 实现告警确认与自动清除:确认后的告警变灰,超过阈值 10 秒自动移出列表,并在 KPI 区显示"历史告警总数"。
  4. 挑战:把曲线改为可缩放的时间轴(滚轮缩放 X 轴、拖拽平移),并用 C++ 侧保留完整历史(环形缓冲 10000 点)支撑缩放。
我的学习笔记笔记总览
笔记保存在本机浏览器(localStorage),换设备或清理缓存会丢失;重要内容请点「导出全部笔记」存成 .md 文件。