Qt6基础教程：多线程串口通信实战#

在实际 Qt 项目中，串口通信往往需要长时间运行、频繁收发数据。如果在 GUI 线程中直接操作 QSerialPort，则 readyRead 信号和 write 调用可能阻塞界面，造成卡顿。本文介绍一种线程安全、高内聚低耦合的设计模式：将串口操作封装到工作线程中，通过 SerialManager 对外提供简洁接口，实现串口通信与界面逻辑的完全分离。

一、创建串口工作类 `SerialWorker`#

我们要设计的第一个类是 SerialWorker，它继承自 QObject，以便后续可以轻松移动到工作线程。

1.1 基本框架#

头文件 serialworker.h 最开始只需要包含必要的头文件和类声明：

1
#ifndef SERIALWORKER_H
2
#define SERIALWORKER_H
3

4
#include <QObject>
5
#include <QSerialPort>
6

7
class SerialWorker : public QObject
8
{
9
    Q_OBJECT
10

11
};
12
#endif

接着添加构造函数和析构函数。注意构造时接收父对象指针，以便启用 Qt 的对象树内存管理。

1
class SerialWorker : public QObject
2
{
3
    Q_OBJECT
4
public:
5
    explicit SerialWorker(QObject *parent = nullptr);
6
    ~SerialWorker();
7
};

对应的实现文件 serialworker. 暂时如下：

1
#include "serialworker.h"
2
#include <QDebug>
3

4
SerialWorker::SerialWorker(QObject *parent)
5
    : QObject(parent)
6
{
7
}
8

9
SerialWorker::~SerialWorker()
10
{
11
}

1.2 加入串口对象成员#

在 SerialWorker 中增加一个 QSerialPort 指针，并在构造函数中创建它，同时将其设置为 this 的子对象。这样，当 SerialWorker 销毁时，m_serial 会被 Qt 自动清理，无需手动 delete。

1
class SerialWorker : public QObject
2
{
3
    // ... 已有代码 ...
4
private:
5
    QSerialPort *m_serial = nullptr;
6
};

1
SerialWorker::SerialWorker(QObject *parent)
2
    : QObject(parent)
3
    , m_serial(new QSerialPort(this))
4
{
5
}

说明：new QSerialPort(this) 将 m_serial 作为 SerialWorker 的子对象，自动纳入 Qt 对象树。父对象析构时会递归删除所有子对象，因此我们不需要在析构函数中写 delete m_serial。

1.3 串口的打开与关闭#

为了能让外部控制串口，我们提供 open 和 close 两个槽函数。由于它们将来可能被跨线程调用，所以定义为 public slots。同时，为了便于传递串口参数，先定义一个配置结构体 SerialConfig。

1
struct SerialConfig {
2
    QString portName;
3
    qint32 baudRate = 115200;
4
    QSerialPort::DataBits dataBits = QSerialPort::Data8;
5
    QSerialPort::Parity parity = QSerialPort::NoParity;
6
    QSerialPort::StopBits stopBits = QSerialPort::OneStop;
7
    QSerialPort::FlowControl flowControl = QSerialPort::NoFlowControl;
8
};
9

10
class SerialWorker : public QObject
11
{
12
    Q_OBJECT
13
public:
14
    explicit SerialWorker(QObject *parent = nullptr);
15
    ~SerialWorker();
16
public slots:
17
    void open(const SerialConfig &config);
18
    void close();
19
private:
20
    QSerialPort *m_serial = nullptr;
21
    void applyConfig(const SerialConfig &config);
22
    bool m_isOpen = false;
23
};

对应的实现如下：

1
void SerialWorker::open(const SerialConfig &config)
2
{
3
    if (m_isOpen) {
4
        close();  // 如果已打开，先关闭
5
    }
6
    applyConfig(config);
7
    m_serial->open(QIODevice::ReadWrite);
8
    m_isOpen = true;
9
}
10

11
void SerialWorker::close()
12
{
13
    if (m_serial->isOpen()) {
14
        m_serial->clear();
15
        m_serial->close();
16
    }
17
    m_isOpen = false;
18
}
19

20
void SerialWorker::applyConfig(const SerialConfig &config)
21
{
22
    m_serial->setPortName(config.portName);
23
    m_serial->setBaudRate(config.baudRate);
24
    m_serial->setDataBits(config.dataBits);
25
    m_serial->setParity(config.parity);
26
    m_serial->setStopBits(config.stopBits);
27
    m_serial->setFlowControl(config.flowControl);
28
}

为什么打开前要调用 close？ 如果串口已经打开，直接修改端口名、波特率等参数可能不会立即生效，有些参数（如端口名）甚至要求串口处于关闭状态。先关闭再应用新配置，可以保证所有参数按照预期重新初始化。

1.4 接收数据：解决粘包与界面卡顿#

串口数据是流式传输的，readyRead 信号可能在数据未完整时就被触发。如果每收到几个字节就立即通知上层，会导致频繁的信号发射和界面刷新，效率很低。更好的做法是：将数据暂存到缓冲区，等待一小段时间（例如 100 毫秒），如果这段时间内没有新数据到来，再将完整的缓冲区数据一次性发出。这既能避免粘包，又能减少界面刷新次数。

我们使用一个 QTimer 来实现延迟聚合。同时为了防止缓冲区无限增长，设定一个最大容量（如 10 MB），超出则强制发送。

修改类定义，添加必要的成员和槽函数：

1
class SerialWorker : public QObject
2
{
3
    Q_OBJECT
4
public:
5
    // ... 已有 public 成员 ...
6
signals:
7
    void dataReceived(const QByteArray &data);
8
private slots:
9
    void onReadyRead();
10
    void onTimeout();
11
private:
12
    QSerialPort *m_serial = nullptr;
13
    QTimer *m_delayTimer = nullptr;
14
    QByteArray m_buffer;
15
    int m_receiveDelay = 100;   // 默认100ms
16
    bool m_isOpen = false;
17
    void applyConfig(const SerialConfig &config);
18
    void flushBuffer();
19
};

构造函数中创建定时器并连接信号：

1
SerialWorker::SerialWorker(QObject *parent)
2
    : QObject(parent)
3
    , m_serial(new QSerialPort(this))
4
    , m_delayTimer(new QTimer(this))
5
{
6
    m_delayTimer->setSingleShot(true); // 单次触发模式
7
    connect(m_serial, &QSerialPort::readyRead, this, &SerialWorker::onReadyRead);
8
    connect(m_delayTimer, &QTimer::timeout, this, &SerialWorker::onTimeout);
9
}

onReadyRead 以及相关辅助函数的实现：

1
void SerialWorker::onReadyRead()
2
{
3
    QByteArray chunk = m_serial->readAll();
4
    m_buffer.append(chunk);
5

6
    // 防止缓冲区无限增长（例如 10MB 上限）
7
    constexpr int MAX_BUFFER_SIZE = 10 * 1024 * 1024; // 10 MiB
8
    if (m_buffer.size() > MAX_BUFFER_SIZE) {
9
        flushBuffer();
10
    }
11

12
    if (m_receiveDelay == 0) {
13
        flushBuffer(); // 立即发送
14
    } else {
15
        m_delayTimer->start(m_receiveDelay); // 重启定时器
16
    }
17
}
18

19
void SerialWorker::onTimeout()
20
{
21
    flushBuffer();
22
}
23

24
void SerialWorker::flushBuffer()
25
{
26
    if (m_buffer.isEmpty()) return;
27
    emit dataReceived(m_buffer);
28
    m_buffer.clear();
29
}

核心思想：每次 readyRead 都会重置定时器，只有在延时期间没有新数据到达时，定时器才会超时并真正发出数据。这既能保证实时性，又能有效聚合小数据包。

1.5 发送数据：支持文本与十六进制#

为了灵活发送数据，我们再实现一个 sendData 槽函数同时提供一个 setReceiveDelay 接口，用于动态调整接收聚合延时。

类定义中增加：

1
public slots:
2
    void sendData(const QByteArray &data);
3
    void setReceiveDelay(int ms);

实现如下：

1
void SerialWorker::sendData(const QByteArray &data)
2
{
3
    if (!m_isOpen) return;
4
    if (data.isEmpty()) return;
5

6
    QByteArray outData = data;
7
    m_serial->write(outData);
8
}
9

10
void SerialWorker::setReceiveDelay(int ms)
11
{
12
    m_receiveDelay = ms;
13
}

说明：上述 sendData 中仅完成了格式转换，实际写入操作 m_serial->write(outData) 请根据项目需要添加。同时，示例代码中 onTimeout 槽函数已在前面实现，但类声明中未显式声明，实际使用时请确保声明与定义一致。

1.6 完善错误处理与状态信号#

为了便于上层感知串口状态变化和错误，我们增加一组信号：

1
signals:
2
    void opened();                          // 打开成功
3
    void closed();                          // 关闭成功
4
    void errorOccurred(const QString &errorString);
5
    void dataReceived(const QByteArray &data);
6
    void configApplied(const QString &configStr);

同时完善 open 和 sendData 的实现，增加错误检查和信号发射。

完善后的 open 函数：

1
void SerialWorker::open(const SerialConfig &config)
2
{
3
    if (m_isOpen) {
4
        close();
5
    }
6

7
    applyConfig(config);
8
    if (!m_serial->open(QIODevice::ReadWrite)) {
9
        emit errorOccurred(tr("打开串口失败: %1").arg(m_serial->errorString()));
10
        return;
11
    }
12
    m_isOpen = true;
13
    emit opened();
14
    emit configApplied(config.toString());  // 需要 SerialConfig 实现 toString()，或自行构造字符串
15
}

完善后的 sendData 函数：

1
void SerialWorker::sendData(const QByteArray &data)
2
{
3
    if (!m_isOpen) {
4
        emit errorOccurred(tr("串口未打开，无法发送数据"));
5
        return;
6
    }
7
    if (data.isEmpty()) return;
8

9
    QByteArray outData = data;
10

11
    qint64 written = m_serial->write(outData);
12
    if (written != outData.size()) {
13
        emit errorOccurred(tr("数据发送不完整"));
14
    }
15
}

设置接收延迟的槽函数：

1
void SerialWorker::setReceiveDelay(int ms)
2
{
3
    m_receiveDelay = ms;
4
}

至此，SerialWorker 类已经具备了打开、关闭、发送、接收（带延迟聚合）以及完整错误通知的能力。

二、创建管理类 `SerialManager`#

SerialWorker 已经实现了串口的所有底层操作，但它仍然运行在创建它的线程中。为了实现真正的多线程隔离，需要一个管理类，负责：

将 SerialWorker 移动到一个独立的 QThread 中。
对外提供线程安全的调用接口（通过信号槽自动处理线程切换）。
将 SerialWorker 发出的信号转发给上层，避免上层直接与工作对象耦合。

2.1 定义 `SerialManager` 类的基本框架#

创建头文件 serialmanager.h，定义 SerialManager 类，继承自 QObject。需要包含一个 QThread 成员和一个 SerialWorker 指针。

1
#ifndef SERIALMANAGER_H
2
#define SERIALMANAGER_H
3

4
#include <QObject>
5
#include <QThread>
6
#include "serialworker.h"
7

8
class SerialManager : public QObject
9
{
10
    Q_OBJECT
11
public:
12
    explicit SerialManager(QObject *parent = nullptr);
13
    ~SerialManager();
14

15
private:
16
    QThread m_workerThread;
17
    SerialWorker *m_worker = nullptr;
18
};
19

20
#endif

2.2 添加对外公开接口#

为了让 GUI 层能够控制串口，需要提供 open、close、sendData、setReceiveDelay 等函数。这些函数将被设计为 Q_INVOKABLE（方便 QML 调用，但不是必须），并且可以在任意线程中安全调用——它们内部只发射信号，不执行实际操作。

1
class SerialManager : public QObject
2
{
3
    Q_OBJECT
4
public:
5
    explicit SerialManager(QObject *parent = nullptr);
6
    ~SerialManager();
7

8
    // 对外公开接口（可从任意线程安全调用）
9
    Q_INVOKABLE void open(const SerialConfig &config);
10
    Q_INVOKABLE void close();
11
    Q_INVOKABLE void sendData(const QByteArray &data);
12
    Q_INVOKABLE void setReceiveDelay(int ms);
13

14
    // ... 其余成员
15
};

2.3 添加内部请求信号#

公开接口本身不直接操作 SerialWorker，而是发射一个“请求信号”。这些信号会被连接到 SerialWorker 的对应槽函数。由于信号槽可以跨线程，SerialWorker 将在自己的线程中执行这些槽。

1
class SerialManager : public QObject
2
{
3
    // ...
4
signals:
5
    // 请求信号（用于转发给 SerialWorker）
6
    void requestOpen(const SerialConfig &config);
7
    void requestClose();
8
    void requestSendData(const QByteArray &data);
9
    void requestSetReceiveDelay(int ms);
10

11
    // 转发信号（稍后添加）
12
};

2.4 添加转发信号#

SerialWorker 会发出一些状态信号（如 opened、dataReceived 等）。上层只需要连接 SerialManager 的信号即可，因此需要定义一组相同的信号用于转发。

1
class SerialManager : public QObject
2
{
3
    // ...
4
signals:
5
    // ... 请求信号
6

7
    // 转发信号（来自 SerialWorker 的事件）
8
    void opened();
9
    void closed();
10
    void errorOccurred(const QString &errorString);
11
    void dataReceived(const QByteArray &data);
12
    void configApplied(const QString &configStr);
13
};

2.5 实现构造函数#

构造函数需要完成以下工作：

创建 SerialWorker 对象（此时它还在主线程）。
将工作对象移动到 m_workerThread。
连接请求信号到工作对象的槽。
连接工作对象的信号到转发信号。
启动工作线程。

1
// serialmanager.
2
#include "serialmanager.h"
3

4
SerialManager::SerialManager(QObject *parent)
5
    : QObject(parent)
6
{
7
    m_worker = new SerialWorker();
8
    m_worker->moveToThread(&m_workerThread);
9

10
    // 连接请求信号到工作对象的槽
11
    connect(this, &SerialManager::requestOpen, m_worker, &SerialWorker::open);
12
    connect(this, &SerialManager::requestClose, m_worker, &SerialWorker::close);
13
    connect(this, &SerialManager::requestSendData, m_worker, &SerialWorker::sendData);
14
    connect(this, &SerialManager::requestSetReceiveDelay, m_worker, &SerialWorker::setReceiveDelay);
15

16
    // 连接工作对象的信号到转发信号
17
    connect(m_worker, &SerialWorker::opened, this, &SerialManager::opened);
18
    connect(m_worker, &SerialWorker::closed, this, &SerialManager::closed);
19
    connect(m_worker, &SerialWorker::errorOccurred, this, &SerialManager::errorOccurred);
20
    connect(m_worker, &SerialWorker::dataReceived, this, &SerialManager::dataReceived);
21
    connect(m_worker, &SerialWorker::configApplied, this, &SerialManager::configApplied);
22

23
    m_workerThread.start();
24
}

2.6 实现析构函数#

析构时需要安全地停止线程并释放工作对象。

1
SerialManager::~SerialManager()
2
{
3
    m_workerThread.quit();
4
    m_workerThread.wait();
5
    delete m_worker;
6
}

说明：m_worker 是在构造函数中用 new 创建的，并且被移到了工作线程。虽然它没有父对象，但我们在析构函数中手动 delete 是安全的，因为 wait() 保证了线程已经退出，不会再有槽函数被调用。

2.7 实现公开接口#

每个公开接口只需要发射对应的请求信号。由于信号槽是异步的，调用者不会阻塞。

1
void SerialManager::open(const SerialConfig &config)
2
{
3
    emit requestOpen(config);
4
}
5

6
void SerialManager::close()
7
{
8
    emit requestClose();
9
}
10

11
void SerialManager::sendData(const QByteArray &data)
12
{
13
    emit requestSendData(data);
14
}
15

16
void SerialManager::setReceiveDelay(int ms)
17
{
18
    emit requestSetReceiveDelay(ms);
19
}

三、创建简易Demo#

3.1 搭建基础界面与 `SerialManager` 集成#

首先创建一个继承自 QWidget 的界面类，并加入必要的成员变量。

头文件 widget.h 初始结构：

1
#ifndef WIDGET_H
2
#define WIDGET_H
3

4
#include <QWidget>
5
#include "serial/serialmanager.h"
6

7
QT_BEGIN_NAMESPACE
8
namespace Ui { class Widget; }
9
QT_END_NAMESPACE
10

11
class Widget : public QWidget
12
{
13
    Q_OBJECT
14
public:
15
    explicit Widget(QWidget *parent = nullptr);
16
    ~Widget();
17

18
private:
19
    Ui::Widget *ui;
20
    SerialManager *manager = nullptr;   // 串口管理器（多线程安全）
21
};
22

23
#endif

实现文件 widget.cpp 构造函数：

1
#include "widget.h"
2
#include "ui_widget.h"
3

4
Widget::Widget(QWidget *parent)
5
    : QWidget(parent)
6
    , manager(new SerialManager(this))   // manager 作为子对象，自动释放
7
    , ui(new Ui::Widget)
8
{
9
    ui->setupUi(this);
10
}
11

12
Widget::~Widget()
13
{
14
    delete ui;
15
}

说明：SerialManager 内部已经封装了工作线程，我们只需像普通 QObject 一样创建它，并设置父对象即可。所有串口操作都可以通过 manager 的公开接口安全调用。

3.2 初始化串口参数下拉框#

串口调试助手需要让用户选择波特率、数据位等参数。我们在 Widget 中添加一个私有方法 initUIConfig()，在构造函数中调用它。

在 widget.h 中添加：

1
private:
2
    void initUIConfig();

实现 initUIConfig()：

1
void Widget::initUIConfig()
2
{
3
    // 波特率
4
    ui->comBaudRate->addItems({"1200", "2400", "4800", "9600", "19200", "38400", "57600", "115200"});
5
    ui->comBaudRate->setEditable(true);
6
    ui->comBaudRate->setValidator(new QIntValidator(0, 1000000, this));
7
    ui->comBaudRate->setCurrentIndex(3);   // 默认 9600
8

9
    // 数据位
10
    ui->comDataBits->addItems({"5", "6", "7", "8"});
11
    ui->comDataBits->setCurrentIndex(3);   // 默认 8
12

13
    // 校验位
14
    ui->comParity->addItems({"Even", "Mark", "None", "Odd", "Space"});
15
    ui->comParity->setCurrentIndex(2);     // 默认 None
16

17
    // 停止位
18
    ui->comStopBits->addItems({"1", "1.5", "2"});
19
    ui->comStopBits->setCurrentIndex(0);   // 默认 1
20
}

关键点：

使用 addItems 一次性添加常用选项。

波特率设置为可编辑 + 整数校验器，方便用户手动输入非常用波特率。

默认选择最常用的参数（9600/8/N/1）。

3.3 获取可用串口列表#

动态扫描系统串口是调试助手的基本功能。我们添加 getportInfo() 方法，并在构造函数中调用。

声明与实现：

1
private:
2
    void getportInfo();
3

4
// widget.
5
void Widget::getportInfo()
6
{
7
    ui->comPortName->clear();
8
    QList<QSerialPortInfo> ports = QSerialPortInfo::availablePorts();
9
    if (ports.isEmpty()) {
10
        ui->comPortName->addItem("无可用串口");
11
        ui->OpenComBtn->setEnabled(false);
12
        return;
13
    }
14
    ui->OpenComBtn->setEnabled(true);
15
    for (const QSerialPortInfo &info : ports)
16
        ui->comPortName->addItem(info.portName());
17
}

说明：

使用 QSerialPortInfo::availablePorts() 获取当前系统中的串口列表。

若无可用串口，禁用“打开串口”按钮并显示提示项。

若有串口，启用按钮并填充端口名。

3.4 打开与关闭串口#

这是与 SerialManager 交互的第一步。我们需要连接按钮的点击信号，并在槽函数中调用 manager->open(config) 或 manager->close()。同时，为了知道串口何时真正打开/关闭，需要连接 SerialManager 的状态信号。

在 Widget 中添加槽函数和状态处理：

1
private slots:
2
    void onOpenCloseButtonClicked();
3
    void handleOpened();
4
    void handleClosed();
5
    void handleErrorOccurred(const QString &error);
6
private:
7
    bool isSerialOpen = false;

构造函数中连接信号：

1
// 在 Widget 构造函数中添加
2
connect(ui->OpenComBtn, &QPushButton::clicked, this, &Widget::onOpenCloseButtonClicked);
3
connect(manager, &SerialManager::opened, this, &Widget::handleOpened);
4
connect(manager, &SerialManager::closed, this, &Widget::handleClosed);
5
connect(manager, &SerialManager::errorOccurred, this, &Widget::handleErrorOccurred);

实现打开/关闭逻辑：

1
void Widget::onOpenCloseButtonClicked()
2
{
3
    if (!isSerialOpen) {
4
        // 准备配置
5
        SerialConfig config;
6
        config.portName = ui->comPortName->currentText();
7
        config.baudRate = ui->comBaudRate->currentText().toInt();
8

9
        // 数据位映射
10
        switch (ui->comDataBits->currentIndex()) {
11
        case 0: config.dataBits = QSerialPort::Data5; break;
12
        case 1: config.dataBits = QSerialPort::Data6; break;
13
        case 2: config.dataBits = QSerialPort::Data7; break;
14
        default: config.dataBits = QSerialPort::Data8; break;
15
        }
16
        // 校验位映射
17
        switch (ui->comParity->currentIndex()) {
18
        case 0: config.parity = QSerialPort::EvenParity; break;
19
        case 1: config.parity = QSerialPort::MarkParity; break;
20
        case 2: config.parity = QSerialPort::NoParity; break;
21
        case 3: config.parity = QSerialPort::OddParity; break;
22
        default: config.parity = QSerialPort::SpaceParity; break;
23
        }
24
        // 停止位映射
25
        switch (ui->comStopBits->currentIndex()) {
26
        case 0: config.stopBits = QSerialPort::OneStop; break;
27
        case 1: config.stopBits = QSerialPort::OneAndHalfStop; break;
28
        default: config.stopBits = QSerialPort::TwoStop; break;
29
        }
30

31
        manager->open(config);
32
        ui->OpenComBtn->setEnabled(false);
33
        ui->OpenComBtn->setText("正在打开...");
34
    } else {
35
        manager->close();
36
    }
37
}
38

39
void Widget::handleOpened()
40
{
41
    isSerialOpen = true;
42
    ui->OpenComBtn->setEnabled(true);
43
    ui->OpenComBtn->setText("关闭串口");
44
}
45

46
void Widget::handleClosed()
47
{
48
    isSerialOpen = false;
49
    ui->OpenComBtn->setEnabled(true);
50
    ui->OpenComBtn->setText("打开串口");
51
}
52

53
void Widget::handleErrorOccurred(const QString &error)
54
{
55
    QMessageBox::critical(this, "串口错误", error);
56
    isSerialOpen = false;
57
    ui->OpenComBtn->setEnabled(true);
58
    ui->OpenComBtn->setText("打开串口");
59
}

设计要点：

打开时先禁用按钮并显示“正在打开…”，防止重复点击。

打开成功/失败后，通过 handleOpened 或 handleErrorOccurred 恢复按钮状态。

关闭操作同样异步，最终由 handleClosed 更新界面。

3.5 实现数据发送（支持纯文本与十六进制）#

SerialManager 只接受 QByteArray 类型的原始字节数据。因此，我们需要根据界面上的“Hex发送”复选框，将用户输入的文本转换成对应的字节数组。

添加槽函数和辅助方法：

1
private slots:
2
    void onSendButtonClicked();
3
private:
4
    void initCheckbox();          // 初始化 Hex 模式相关信号槽
5
    void formatTxEditForHex();    // 实时格式化 Hex 输入
6
    void convertTextToHex();      // 文本 -> Hex 字符串
7
    void convertHexToText();      // Hex 字符串 -> 文本

发送按钮槽函数实现：

1
void Widget::onSendButtonClicked()
2
{
3
    QString text = ui->TxEdit->toPlainText().trimmed();
4
    if (text.isEmpty()) return;
5

6
    bool hexFlag = ui->HexTxBox->isChecked();
7
    QByteArray data;
8

9
    if (hexFlag) {
10
        // 移除空格，校验偶数个字符
11
        QString hexStr = text;
12
        hexStr.remove(' ');
13
        if (hexStr.length() % 2 != 0) {
14
            QMessageBox::warning(this, "错误", "十六进制数据必须为偶数个字符，请补零后重试");
15
            return;
16
        }
17
        data = QByteArray::fromHex(hexStr.toUtf8());
18
        if (data.isEmpty() && !hexStr.isEmpty()) {
19
            QMessageBox::warning(this, "错误", "无效的十六进制数据");
20
            return;
21
        }
22
    } else {
23
        data = text.toUtf8();   // 文本模式使用 UTF-8 编码
24
    }
25
    manager->sendData(data);
26
}

Hex 输入辅助功能（实时格式化和模式切换）：

1
void Widget::initCheckbox()
2
{
3
    // 切换 Hex 发送模式时，转换当前文本框内容
4
    connect(ui->HexTxBox, &QCheckBox::stateChanged, this, [=](int state) {
5
        if (state == Qt::Checked)
6
            convertTextToHex();
7
        else
8
            convertHexToText();
9
    });
10

11
    // Hex 模式下，每次文本改变时自动添加空格、过滤非法字符
12
    connect(ui->TxEdit, &QTextEdit::textChanged, this, [=]() {
13
        if (ui->HexTxBox->isChecked())
14
            formatTxEditForHex();
15
    });
16
}
17

18
void Widget::formatTxEditForHex()
19
{
20
    // 实现细节参考最终源码：提取十六进制字符、每两个加空格、保持光标位置
21
    // 此处省略完整代码
22
}
23

24
void Widget::convertTextToHex()
25
{
26
    QString plainText = ui->TxEdit->toPlainText();
27
    QByteArray bytes = plainText.toLocal8Bit();
28
    QString hexStr = bytes.toHex(' ').toUpper();
29
    ui->TxEdit->blockSignals(true);
30
    ui->TxEdit->setPlainText(hexStr);
31
    ui->TxEdit->blockSignals(false);
32
}
33

34
void Widget::convertHexToText()
35
{
36
    QString hexText = ui->TxEdit->toPlainText();
37
    QString pureHex = hexText;
38
    pureHex.remove(' ');
39
    QByteArray bytes = QByteArray::fromHex(pureHex.toUtf8());
40
    if (bytes.isEmpty() && !pureHex.isEmpty()) {
41
        QMessageBox::warning(this, "错误", "无效的十六进制数据，无法转换为文本");
42
        return;
43
    }
44
    QString plainText = QString::fromLocal8Bit(bytes);
45
    if (plainText.isEmpty() && !bytes.isEmpty())
46
        plainText = QString::fromLatin1(bytes);
47
    ui->TxEdit->blockSignals(true);
48
    ui->TxEdit->setPlainText(plainText);
49
    ui->TxEdit->blockSignals(false);
50
}

关键说明：

界面层负责数据格式转换，SerialManager 保持简洁（只发送原始字节）。

Hex 模式下，提供实时格式化（自动插入空格、限制输入字符）和模式切换时的内容转换，提升用户体验。

3.6 实现数据接收与显示#

接收数据通过连接 SerialManager::dataReceived 信号完成。我们可以在槽函数中根据用户设置（Hex显示、时间戳、自动换行）格式化数据并追加到接收文本框。

添加槽函数：

1
private slots:
2
    void handleDataReceived(const QByteArray &data);

构造函数中连接信号：

1
connect(manager, &SerialManager::dataReceived, this, &Widget::handleDataReceived);

实现接收处理：

1
void Widget::handleDataReceived(const QByteArray &data)
2
{
3
    if (data.isEmpty()) return;
4

5
    // 根据 Hex 复选框决定显示格式
6
    QString display;
7
    if (ui->HexRxBox->isChecked()) {
8
        display = data.toHex(' ').toUpper();
9
        if (!display.isEmpty()) display += ' ';
10
    } else {
11
        display = QString::fromUtf8(data);
12
        if (display.isEmpty()) display = QString::fromLatin1(data);
13
    }
14

15
    ui->RxEdit->moveCursor(QTextCursor::End);
16

17
    // 时间戳
18
    if (ui->TimeBox->isChecked()) {
19
        QString timestamp = QDateTime::currentDateTime().toString("[yyyy/MM/dd hh:mm:ss] ");
20
        ui->RxEdit->insertPlainText(timestamp);
21
    }
22

23
    ui->RxEdit->insertPlainText(display);
24

25
    // 自动换行
26
    if (ui->AWBox->isChecked())
27
        ui->RxEdit->insertPlainText("\n");
28

29
    ui->RxEdit->moveCursor(QTextCursor::End);
30
}

说明：

使用 data.toHex(' ') 将字节数组转换为带空格的十六进制字符串，便于阅读。

文本模式优先尝试 UTF-8 解码，失败则回退到 Latin1。

支持可选的时间戳和自动换行，所有选项实时生效。

3.7 实现定时发送#

定时发送功能利用 QTimer 周期性调用发送按钮的槽函数。用户可通过复选框启用/禁用，并通过数值调节框改变间隔。

添加成员和槽函数：

1
private:
2
    QTimer *m_sendTimer = nullptr;
3
private slots:
4
    void onTRBoxToggled(bool checked);
5
    void onTimeoutSend();

构造函数中初始化定时器并连接信号：

1
// 在 Widget 构造函数中添加
2
m_sendTimer = new QTimer(this);
3
m_sendTimer->setSingleShot(false);
4
connect(m_sendTimer, &QTimer::timeout, this, &Widget::onTimeoutSend);
5
connect(ui->TRBox, &QCheckBox::toggled, this, &Widget::onTRBoxToggled);
6
connect(ui->TVBox, QOverload<int>::of(&QSpinBox::valueChanged), this, [=](int value) {
7
    if (m_sendTimer->isActive())
8
        m_sendTimer->setInterval(value);
9
});

实现槽函数：

1
void Widget::onTRBoxToggled(bool checked)
2
{
3
    if (checked) {
4
        int interval = ui->TVBox->value();
5
        if (interval <= 0) {
6
            QMessageBox::warning(this, "警告", "定时发送间隔必须大于0");
7
            ui->TRBox->setChecked(false);
8
            return;
9
        }
10
        m_sendTimer->setInterval(interval);
11
        m_sendTimer->start();
12
    } else {
13
        m_sendTimer->stop();
14
    }
15
}
16

17
void Widget::onTimeoutSend()
18
{
19
    onSendButtonClicked();   // 复用发送逻辑
20
}

设计说明：

定时器周期根据 ui->TVBox 的值动态调整。

启用定时发送前检查间隔合法性。

复用 onSendButtonClicked 避免重复代码。

3.8 附加功能：清空发送/接收编辑框#

为了界面友好，添加两个清空按钮非常简单，使用 Lambda 表达式直接连接。

在构造函数中添加：

1
connect(ui->ClearRxBtn, &QPushButton::clicked, this, [=]() { ui->RxEdit->clear(); });
2
connect(ui->ClearTxBtn, &QPushButton::clicked, this, [=]() { ui->TxEdit->clear(); });

四、回顾与总结#

通过本教程的三部分，我们完成了一个多线程串口通信模块：

SerialWorker：封装串口底层操作，利用延迟聚合优化接收效率，并提供打开、关闭、发送、错误处理等完整功能。
SerialManager：将工作对象移至独立线程，通过信号槽提供线程安全的公开接口，并将工作对象的状态信号转发给上层，实现了界面与串口逻辑的完全解耦。
**Widget **：展示了如何使用 SerialManager 构建一个串口调试助手，包括参数配置、串口扫描、数据收发（支持文本/十六进制、时间戳、自动换行）、定时发送等功能。

完整工程地址

daitcl

Qt-demo

Waiting for api.github.com...

00K

Waiting...