QML怎么使用C++多线程编程

在 QML 中使用 C++ 多线程，核心原则是：永远不要在主线程（UI 线程）执行耗时操作，也永远不要在工作线程直接操作 UI 对象。

最稳健且推荐的做法是采用 "控制器模式" ：创建一个继承自 QObject 的 C++ 控制器类，它持有工作对象，并通过信号与槽机制安全地与 QML 通信。

以下是实现这一模式的完整步骤和最佳实践。

🚀 一、核心模式：控制器 + 工作对象

这种模式将 UI 逻辑、业务逻辑和线程管理清晰地分离开来。

1. 创建 Worker 类 (工作对象)

这个类负责执行具体的耗时任务。它不关心 UI，只负责干活和汇报结果。

• 关键点 ：继承 QObject，使用信号（signals）汇报进度和结果，使用槽函数（slots）接收开始和停止的指令。

// worker.h
#ifndef WORKER_H
#define WORKER_H

#include <QObject>
#include <QTimer>

class Worker : public QObject
{
    Q_OBJECT
public:
    explicit Worker(QObject *parent = nullptr) : QObject(parent), m_count(0) {
        // 使用定时器来模拟周期性任务，避免在单一线程中长时间阻塞
        connect(&m_timer, &QTimer::timeout, this, &Worker::doWork);
    }

public slots:
    // QML 通过控制器调用此槽来启动任务
    void startWork() {
        m_count = 0;
        m_timer.start(1000); // 每秒执行一次 doWork
    }

    // QML 通过控制器调用此槽来停止任务
    void stopWork() {
        m_timer.stop();
    }

private slots:
    void doWork() {
        m_count++;
        // 模拟耗时计算
        QString result = QString("后台数据 %1").arg(m_count);
        
        // 1. 发出信号，将数据发送到主线程
        emit dataReady(result);
        
        // 2. 任务完成后，发出完成信号
        if (m_count >= 10) {
            stopWork();
            emit workFinished();
        }
    }

signals:
    void dataReady(const QString &data); // 发送数据
    void workFinished();                 // 发送完成信号

private:
    QTimer m_timer;
    int m_count;
};

#endif // WORKER_H

2. 创建 Controller 类 (控制器)

这个类是 QML 和 Worker 之间的桥梁。它在主线程中创建，负责管理 Worker 的生命周期和线程移动，并转发信号。

• 关键点 ：
  1. 在构造函数中创建 Worker 并将其 moveToThread。
  2. 使用 Q_INVOKABLE 暴露给 QML 调用的方法。
  3. 连接信号和槽，将 Worker 的信号安全地转发给 QML。

// threadcontroller.h
#ifndef THREADCONTROLLER_H
#define THREADCONTROLLER_H

#include <QObject>
#include <QThread>
#include "worker.h"

class ThreadController : public QObject
{
    Q_OBJECT
    // 将工作状态暴露给 QML，方便绑定
    Q_PROPERTY(bool isWorking READ isWorking NOTIFY isWorkingChanged)

public:
    explicit ThreadController(QObject *parent = nullptr) : QObject(parent) {
        // 1. 创建工作对象
        m_worker = new Worker();
        // 2. 创建新线程
        m_workerThread = new QThread(this);
        // 3. 将工作对象移动到新线程
        m_worker->moveToThread(m_workerThread);

        // 4. 连接信号和槽 (关键！)
        // 当 QML 调用 start()，触发 startWork 信号，Worker 的 startWork 槽函数会在工作线程中被调用
        connect(this, &ThreadController::startWork, m_worker, &Worker::startWork);
        // 停止信号同理
        connect(this, &ThreadController::stopWork, m_worker, &Worker::stopWork);

        // 5. 将 Worker 的结果信号转发回主线程的槽函数
        connect(m_worker, &Worker::dataReady, this, &ThreadController::onDataReady);
        connect(m_worker, &Worker::workFinished, this, &ThreadController::onWorkFinished);

        // 6. 启动线程的事件循环
        m_workerThread->start();
    }

    ~ThreadController() {
        // 确保线程正确退出
        m_workerThread->quit();
        m_workerThread->wait();
    }

    // QML 可调用的方法
    Q_INVOKABLE void start() {
        if (!m_isWorking) {
            setWorking(true);
            emit startWork(); // 发出信号，通知工作线程开始
        }
    }

    Q_INVOKABLE void stop() {
        if (m_isWorking) {
            emit stopWork(); // 发出信号，通知工作线程停止
            setWorking(false);
        }
    }

    bool isWorking() const { return m_isWorking; }

signals:
    void startWork();
    void stopWork();
    void newData(const QString &data); // 转发给 QML 的信号
    void isWorkingChanged();

private slots:
    // 在工作线程的数据到达主线程后，在此处处理并转发
    void onDataReady(const QString &data) {
        emit newData(data);
    }

    void onWorkFinished() {
        setWorking(false);
    }

    void setWorking(bool working) {
        if (m_isWorking != working) {
            m_isWorking = working;
            emit isWorkingChanged();
        }
    }

private:
    Worker *m_worker;
    QThread *m_workerThread;
    bool m_isWorking = false;
};

#endif // THREADCONTROLLER_H

3. 在 main.cpp 中注册

将控制器实例暴露给 QML 引擎。

#include <QGuiApplication>
#include <QQmlApplicationEngine>
#include <QQmlContext>
#include "threadcontroller.h"

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);
    QQmlApplicationEngine engine;

    // 1. 在主线程创建控制器
    ThreadController controller;
    // 2. 将其注册为 QML 上下文属性，QML 中就可以通过 "threadController" 访问它
    engine.rootContext()->setContextProperty("threadController", &controller);

    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
    return app.exec();
}

4. 在 QML 中使用

现在，QML 可以像调用普通对象一样，安全地调用 C++ 的多线程功能。

import QtQuick 2.15
import QtQuick.Controls 2.15

ApplicationWindow {
    visible: true
    width: 400
    height: 300
    title: "C++ 多线程示例"

    Column {
        anchors.centerIn: parent
        spacing: 20

        Text {
            id: statusText
            text: "状态: 空闲"
            font.pixelSize: 20
        }

        Button {
            text: "开始任务"
            enabled: !threadController.isWorking // 根据状态禁用按钮
            onClicked: {
                statusText.text = "状态: 运行中..."
                threadController.start()
            }
        }

        Button {
            text: "停止任务"
            enabled: threadController.isWorking
            onClicked: {
                statusText.text = "状态: 正在停止..."
                threadController.stop()
            }
        }
    }

    // 监听 C++ 发来的数据
    Connections {
        target: threadController
        function onNewData(data) {
            statusText.text = "收到数据: " + data
        }
    }
}

---

💡 二、其他替代方案

除了上述经典的 QThread 模式，Qt 还提供了更高级的抽象，可以简化开发。

1. Qt Concurrent (适用于简单任务)

对于"发射后不管"的简单耗时任务（如一次性计算），QtConcurrent::run 是最简洁的选择。它基于线程池，无需手动管理 QThread。

#include <QtConcurrent>
#include <QFutureWatcher>

class Calculator : public QObject {
    Q_OBJECT
public:
    Q_INVOKABLE void startCalculation(int value) {
        // 在后台线程运行 lambda 表达式
        QFuture<int> future = QtConcurrent::run([value]() {
            // 这里是耗时计算
            int result = 0;
            for(int i = 0; i < 1000000; ++i) {
                result += i;
            }
            return result;
        });

        // 使用 QFutureWatcher 监听完成信号
        QFutureWatcher<int> *watcher = new QFutureWatcher<int>(this);
        connect(watcher, &QFutureWatcher<int>::finished, this, [watcher, this]() {
            int result = watcher->result();
            emit calculationFinished(result); // 信号会自动在主线程被接收
            watcher->deleteLater();
        });
        watcher->setFuture(future);
    }
signals:
    void calculationFinished(int result);
};

2. WorkerScript (适用于纯 QML/JS 逻辑)

如果你的耗时任务是纯 JavaScript 逻辑（如复杂的数据处理），不想写 C++，可以使用 QML 内置的 WorkerScript。

// main.qml
import QtQuick 2.15

WorkerScript {
    id: worker
    source: "worker.js"
    onMessage: (message) => {
        console.log("主线程收到结果:", message.data.result)
        // 安全地更新 UI
    }
}

// 启动任务
function startTask() {
    worker.sendMessage({ value: 10000 })
}

// worker.js
WorkerScript.onMessage = function(message) {
    // 在工作线程执行
    var result = 0;
    for (var i = 0; i < message.value; i++) {
        result += Math.sqrt(i);
    }
    // 发送结果回主线程
    WorkerScript.sendMessage({ result: result });
}

📌 三、总结与最佳实践

方案	适用场景	优点	缺点
控制器模式 (QThread)	复杂、长期运行的后台任务，需要精细控制生命周期和通信。	结构清晰，功能强大，是 Qt 官方推荐模式。	代码量相对较多。
Qt Concurrent	简单、一次性的耗时操作，如计算、数据转换。	代码简洁，无需管理线程对象。	不适合需要频繁启停或复杂交互的任务。
WorkerScript	纯 JavaScript 的耗时逻辑，不想引入 C++。	完全在 QML 层实现，方便快速开发。	性能不如 C++，无法调用 C++ 对象。

核心法则：

1. 线程亲和性 ：QObject 属于创建它的线程。不要跨线程直接调用其方法。
2. 信号与槽 ：跨线程通信的唯一安全方式。Qt 的 Qt::QueuedConnection 会自动将信号参数打包，通过事件循环发送到目标线程。
3. 生命周期管理 ：确保在销毁对象前，正确退出并等待工作线程结束 (quit() + wait())，防止程序崩溃。