📚 课程目录第3章 Qt Quick与C++集成

3. Qt Quick与C++集成

在设备通信工程中，Qt Quick 负责界面呈现与交互，而串口、TCP、Modbus、协议解析等底层能力通常由 C++ 实现。QML 与 C++ 的集成质量，直接决定了通信数据能否稳定、低延迟地呈现在界面上。本节围绕四条主线展开：交互机制、类型注册、上下文属性、信号槽通信，并给出可落地的工程写法。

一、核心原理：QML 与 C++ 的两种交互方向

QML 与 C++ 的交互本质上是双向的。C++ 向 QML 暴露能力，QML 向 C++ 发起调用或回传数据。理解方向，才能选对机制。

C++ → QML：通过注册类型、上下文属性、单例或模型，把 C++ 对象交给 QML 使用。
QML → C++：通过调用 Q_INVOKABLE 方法、读写 Q_PROPERTY、触发信号，把界面意图传给 C++。
双向通道：信号槽是贯穿两个方向的主干，既可由 C++ 通知 QML，也可由 QML 触发 C++ 逻辑。

在设备通信场景中，典型链路是：串口线程收到字节流 → C++ 解析为帧 → 更新属性或发出信号 → QML 绑定属性或响应信号 → 界面刷新。整条链路中，QML 不直接碰硬件，C++ 不直接操作界面元素，职责清晰。

二、类型注册：把 C++ 类变成 QML 可实例化组件

类型注册适合“需要在 QML 中多次创建对象”的场景，例如每个设备面板对应一个 DeviceSession。注册后，QML 可以像使用内置组件一样声明它。

// devicesession.h
class DeviceSession : public QObject {
    Q_OBJECT
    Q_PROPERTY(QString deviceId READ deviceId WRITE setDeviceId NOTIFY deviceIdChanged)
    Q_PROPERTY(bool online READ online NOTIFY onlineChanged)
public:
    explicit DeviceSession(QObject *parent = nullptr);
    QString deviceId() const;
    void setDeviceId(const QString &id);
    bool online() const;

    Q_INVOKABLE void connectDevice();
    Q_INVOKABLE void sendCommand(const QString &cmd);

signals:
    void deviceIdChanged();
    void onlineChanged();
    void dataReceived(const QString &payload);

private:
    QString m_deviceId;
    bool m_online = false;
};

// main.cpp
qmlRegisterType<DeviceSession>("Comm.Device", 1, 0, "DeviceSession");

QML 侧即可直接声明：

import Comm.Device 1.0

DeviceSession {
    id: session
    deviceId: "COM3"
    onDataReceived: console.log("收到:", payload)
}

Button {
    text: "连接"
    onClicked: session.connectDevice()
}

若使用 Qt 6，推荐用 QML_ELEMENT 宏配合 CMake 的 qt_add_qml_module，减少手工注册代码，同时获得更好的编译期检查。

三、上下文属性：把已有对象注入 QML 根上下文

上下文属性适合“全局唯一、生命周期由 C++ 管理”的对象，例如通信管理器、配置中心、日志服务。它不需要在 QML 中实例化，直接以变量名访问。

// main.cpp
CommManager manager;
engine.rootContext()->setContextProperty("commManager", &manager);

// QML 中直接使用
Text {
    text: commManager.statusText
}

Button {
    text: "刷新"
    onClicked: commManager.refreshDevices()
}

上下文属性在 QML 中属于“隐式全局变量”，调试时不易追踪来源。工程中建议只注入少量全局服务，业务对象优先用类型注册或单例。

四、信号槽通信：跨语言的事件主干

信号槽是 QML 与 C++ 之间最可靠的通信方式。C++ 发信号，QML 用 onXxx 或 Connections 接收；QML 也可以定义信号，由 C++ 连接。

// C++ 侧：解析完成后发信号
emit dataReceived(QString::fromUtf8(frame));

// QML 侧：两种接收方式
DeviceSession {
    onDataReceived: logModel.append({ "msg": payload })
}

Connections {
    target: commManager
    function onStatusChanged(text) {
        statusLabel.text = text
    }
}

反向通信时，QML 声明信号，C++ 通过 QMetaObject::invokeMethod 或连接 QML 对象的信号来响应。设备通信中常见的“界面点击发送指令”就是 QML 调用 C++ 的 Q_INVOKABLE 方法，再由 C++ 写入串口。

五、四种集成方式对比

方式	适用场景	QML 使用形式	注意事项
类型注册	可多次实例化的设备对象	声明式组件	需 import 模块，注意版本号
上下文属性	全局单例服务	直接变量名访问	隐式依赖，避免滥用
QML 单例	全局配置、状态中心	import 后直接引用	需 qmlRegisterSingletonType
信号槽	事件通知、异步数据	onXxx / Connections	跨线程注意队列连接

六、案例：串口数据上屏的完整链路

假设设备通过串口持续上报温度。C++ 侧 SerialWorker 在独立线程读取字节流，解析出温度值后更新 Q_PROPERTY(double temperature) 并发出 temperatureChanged()。QML 侧用 Text { text: session.temperature.toFixed(1) + " ℃" } 绑定属性，属性变化时界面自动刷新，无需手动 setText。

若数据频率很高，应避免每个字节都发信号，而是按帧或按固定周期批量通知，减少 QML 引擎的事件压力。对于列表型数据，优先使用 QAbstractListModel 派生模型，而不是反复重建 JavaScript 数组。

常见误区：在 QML 中直接创建 C++ 对象却忘记设置 parent，导致对象泄漏；或在非 GUI 线程直接操作 QML 对象，引发崩溃。跨线程通信应通过信号槽的队列连接，让槽函数在 GUI 线程执行。

七、复盘与工程建议

接口先行：先定义 C++ 的属性、方法、信号，再写 QML，避免边写边改导致绑定失效。
职责单一：C++ 管通信与协议，QML 管展示与交互，不把解析逻辑写进 QML。
命名清晰：信号用过去式（dataReceived），方法用动词（sendCommand），属性用名词。
线程安全：串口读写放工作线程，通过信号槽把结果投递到 GUI 线程。
可测试：把协议解析抽成纯 C++ 类，不依赖 QML，便于单元测试。

掌握这四种机制后，QML 与 C++ 的边界就清晰了：类型注册解决“有什么对象”，上下文属性解决“全局服务怎么拿”，信号槽解决“事件怎么传”，属性绑定解决“界面怎么自动更新”。四者配合，才能支撑起稳定、可维护的设备通信应用。