1. 从 Designer 到纯代码我为什么抛弃拖拽式界面设计做 Qt 开发这些年我见过太多人一上来就用 Qt Designer 拖控件拖完.ui文件再用uic编译配合ui_xxx.h用ui-btn访问控件。这套流程本身没问题官方也推荐但如果你做的项目稍微复杂一点——比如界面需要动态增删控件、根据用户角色显示不同板块、或者要做一套可换肤的客户端纯代码界面设计的优势就彻底体现出来了。先说个真实经历。我之前做一个工业上位机项目界面里有个“设备列表”区域设备数量不是固定的客户要求支持运行时动态加载设备卡片每张卡片上有名称、状态灯、实时数据、操作按钮。用 Designer 做这种界面要么预先塞满QFrame然后隐藏/显示要么就得new一堆控件手动布局最后还是回到了纯代码这条路。试过一次之后后面的项目我基本全部采用纯代码方式设计界面只在极少数特殊场景比如快速验证原型才打开 Designer。这篇文章我就以纯代码方式为核心聊聊 Qt 界面设计的具体落地思路和实操过程包括布局管理、QSS 样式美化、事件处理、窗口缩放适配以及一些我在实际项目里踩过的坑。无论你是刚接触 Qt 的新人还是已经用 Designer 写过一阵子界面的开发者这篇文章都能给你一个清晰的“纯代码做 UI”的完整路线。这里我说明一下文章适用的范围环境是 Qt 5.15.2 MinGW 64 位编译器是 C17IDE 是 Qt Creator。如果你是 Qt 6 基本也通用差异点我会在文中一并提一下。代码我也会全部贴出来可以直接复制到工程里跑。2. 纯代码界面设计的核心思路布局先行的设计法2.1 为什么纯代码界面比 Designer 更适合复杂项目首先我们得搞清楚纯代码界面设计不是让你从零手写每一个像素而是通过QLayout体系来管理控件位置和尺寸。这个思路的核心是不指定控件的绝对坐标而是指定控件之间的相对关系。比如“按钮 A 在按钮 B 的右边”“输入框占满窗口剩余空间”“左侧面板宽度固定 240px”这些用布局都能直接表达。对比 Designer纯代码有几个实打实的优势第一动态界面容易实现。添加一个控件就是layout-addWidget(new QPushButton(...))一行代码移除一个控件也简单运行时循环遍历删除即可。Designer 的.ui文件里控件列表是静态的运行时动态增删要手动处理很多东西。第二代码审查和团队协作更友好。.ui文件本质是 XML合并分支的时候经常冲突而.ui文件的冲突基本没法手工合并只能重新拖一遍。纯代码方式就是普通的 C 代码Git diff 清晰review 时可以明确看到某次修改动了哪个控件的什么属性。第三可复用性高。封装一个自定义控件类继承QWidget在构造函数里完成布局和初始化然后到任何一个界面里都能new一个出来用跟普通控件一样。Designer 虽然也支持“提升控件”但流程繁琐很多团队都不愿意用。当然纯代码也有一些代价比如界面调整后不能立即可视化预览要运行起来才能看到初期代码量比 Designer 稍大对初学者理解布局机制的要求更高。但从长期维护角度看我认为是值得的。2.2 先画结构图手写界面之前必须做的步骤很多初学者上手就写代码结果写出来界面混乱。我现在的习惯是在写代码之前先在纸上或者文档里把界面结构图抠出来。你不需要画得多专业但一定要明确以下几点窗口整体分成哪几个区域比如顶部工具栏、左侧导航、中间内容区、底部状态栏每个区域内部是哪种布局水平排列、垂直排列、网格排列、表单排列哪些控件的尺寸是固定的哪些是要随窗口拉伸的控件之间的间距和对齐方式拿到结构图之后再动手敲代码就非常有底了。说句实在话我见过不少同学的界面问题不是代码写错了而是布局关系从一开始就没想明白写出来的布局嵌套逻辑混乱窗口一缩放就完全崩掉。我来用一个例子说明。假设我们要做一个“设备监控卡片”界面结构图大概是这样的主窗口垂直布局主布局标题栏QLabel固定高度滚动区域QScrollArea占据剩余空间网格布局QGridLayout动态添加设备卡片这样的结构明确了之后代码写起来就顺理成章下面我们实际写一遍。3. 从零搭建项目布局、控件与样式表的完整实现3.1 工程初始化首先用 Qt Creator 创建一个新的 Qt Widgets Application 项目基类选择QMainWindow或者QWidget都可以我这里选QMainWindow方便后续加菜单栏和状态栏。注意创建向导会让你勾选“生成 .ui 文件”纯代码方案这里取消勾选直接生成一个带.pro和main.cpp、mainwindow.cpp的空壳工程。工程文件.pro里确保有这几行QT core gui greaterThan(QT_MAJOR_VERSION, 4): QT widgets TARGET PureCodeUiDemo TEMPLATE app DEFINES QT_DEPRECATED_WARNINGS SOURCES \ main.cpp \ mainwindow.cpp HEADERS \ mainwindow.h这里有个小细节如果项目后续需要用到串口、网络、打印等模块在.pro里逐一添加对应的 QT 模块就行。比如加串口就写成QT serialport网络是QT network。经常有人在 Qt 里遇到unknown module(s) in qt: serialport这个报错绝大多数情况就是.pro里没写这个模块声明直接补上即可。另外 Qt 5.14 之后serialport模块是随官方安装包一起分发的基础模块不需要额外下载库所以不用慌。3.2 main.cpp 入口#include QApplication #include mainwindow.h int main(int argc, char *argv[]) { QApplication a(argc, argv); MainWindow w; w.show(); return a.exec(); }这段是标准入口没什么好讲的。如果你要做高端一点的软件可以在w.show()之前设置全局字体比如QFont font(Microsoft YaHei, 9); a.setFont(font);这个设置对你的界面观感影响非常大。默认 Qt 在 Windows 上用的字体是宋体显示效率高但美观度确实不行换成微软雅黑之后整个界面的气质都不一样了。公司项目里我一律用雅黑Linux 上可以根据系统换成Noto Sans CJK SC之类的中文字体。3.3 主窗口的纯代码界面骨架接下来就是核心部分。先看mainwindow.h#ifndef MAINWINDOW_H #define MAINWINDOW_H #include QMainWindow class QLabel; class QPushButton; class QGridLayout; class QScrollArea; class QTimer; class MainWindow : public QMainWindow { Q_OBJECT public: explicit MainWindow(QWidget *parent nullptr); ~MainWindow(); private slots: void onAddDevice(); void onRemoveDevice(); private: void setupUi(); QLabel *m_titleLabel; QPushButton *m_addButton; QPushButton *m_removeButton; QWidget *m_deviceContainer; QGridLayout *m_deviceGrid; QScrollArea *m_scrollArea; int m_deviceCount 0; }; #endif // MAINWINDOW_H注意这里我用了前置声明class QLabel;只在头文件里声明指针。头文件里尽量不#include具体的控件头文件而是包含QMainWindow这种基类。这样做有几个好处编译速度快因为不需要每次都解析大段 Qt 头文件依赖关系更清晰避免头文件互相包含造成死循环。实现文件.cpp里再具体引入头文件即可。然后看mainwindow.cpp构造函数和窗口初始化#include mainwindow.h #include QWidget #include QLabel #include QPushButton #include QGridLayout #include QVBoxLayout #include QHBoxLayout #include QScrollArea #include QFrame #include QTimer #include QDebug MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) { setupUi(); } MainWindow::~MainWindow() { } void MainWindow::setupUi() { setWindowTitle(QStringLiteral(纯代码界面设计示例 - 设备监控)); resize(900, 600); // 创建中心组件 QWidget *centralWidget new QWidget(this); setCentralWidget(centralWidget); // 主布局垂直方向 QVBoxLayout *mainLayout new QVBoxLayout(centralWidget); mainLayout-setContentsMargins(12, 12, 12, 12); mainLayout-setSpacing(10); // 顶部区域标题 操作按钮水平布局 QHBoxLayout *topLayout new QHBoxLayout(); m_titleLabel new QLabel(QStringLiteral(设备实时状态), centralWidget); m_titleLabel-setStyleSheet(font-size: 16px; font-weight: bold; color: #333333;); m_addButton new QPushButton(QStringLiteral(添加设备), centralWidget); m_removeButton new QPushButton(QStringLiteral(移除设备), centralWidget); m_addButton-setFixedSize(90, 30); m_removeButton-setFixedSize(90, 30); topLayout-addWidget(m_titleLabel); topLayout-addStretch(); topLayout-addWidget(m_addButton); topLayout-addWidget(m_removeButton); // 中部的滚动区域 m_scrollArea new QScrollArea(centralWidget); m_scrollArea-setWidgetResizable(true); m_scrollArea-setFrameShape(QFrame::NoFrame); m_deviceContainer new QWidget(); m_deviceContainer-setObjectName(deviceContainer); m_deviceGrid new QGridLayout(m_deviceContainer); m_deviceGrid-setContentsMargins(0, 0, 0, 0); m_deviceGrid-setSpacing(12); m_deviceGrid-setAlignment(Qt::AlignTop | Qt::AlignLeft); m_scrollArea-setWidget(m_deviceContainer); // 底部状态栏用 QStatusBar statusBar()-showMessage(QStringLiteral(就绪)); // 把布局组合起来 mainLayout-addLayout(topLayout); mainLayout-addWidget(m_scrollArea, 1); // 信号连接 connect(m_addButton, QPushButton::clicked, this, MainWindow::onAddDevice); connect(m_removeButton, QPushButton::clicked, this, MainWindow::onRemoveDevice); }布局设计的几个关键点解读mainLayout-addWidget(m_scrollArea, 1)里的参数1是伸缩因子stretch factor。意思是当主窗口高度变化时滚动区域会优先吃掉所有多余空间而顶部布局保持固定高度。这个机制是纯代码布局的精华用好伸缩因子你就不需要手动处理控件位置。topLayout-addStretch()会在标题和按钮之间插入一个弹簧把按钮们推到最右边。如果你希望标题居中可以两边各加一个addStretch()或者直接用addWidget(..., 0, Qt::AlignCenter)。m_scrollArea-setWidgetResizable(true)这个必须设置。如果忘了内部容器和滚动区域的联动会导致内容不跟随宽度调整窗口拉宽时卡片不会自动重新排列很多人第一次用 QScrollArea 都会踩到这里。m_deviceGrid-setAlignment(Qt::AlignTop | Qt::AlignLeft)让网格布局的内容在容器里靠左上对齐而不是居中或拉伸。因为滚动区域内部的容器高度默认是跟随内容的高度但宽度会撑满。对齐方式不对的话内容稀少时卡片可能被拉到中间看起来很奇怪。3.4 动态添加/移除卡片的核心逻辑下面实现动态增删控件。每一张卡片我封装成一个函数createDeviceCard()返回QFrame*QFrame *MainWindow::createDeviceCard(const QString name, int deviceId) { // 卡片容器 QFrame *card new QFrame(); card-setObjectName(QString(deviceCard_%1).arg(deviceId)); card-setFixedSize(240, 140); card-setFrameShape(QFrame::NoFrame); // 卡片内使用垂直布局 QVBoxLayout *cardLayout new QVBoxLayout(card); cardLayout-setContentsMargins(12, 10, 12, 10); cardLayout-setSpacing(6); // 设备名称 QLabel *nameLabel new QLabel(name, card); nameLabel-setObjectName(deviceNameLabel); nameLabel-setStyleSheet(font-size: 14px; font-weight: bold; color: #ffffff;); // 设备状态 QLabel *statusLabel new QLabel(QStringLiteral(状态在线), card); statusLabel-setObjectName(statusLabel); statusLabel-setStyleSheet(color: #a0ffa0; font-size: 12px;); // 实时数据随便写几个 QLabel *dataLabel new QLabel(QStringLiteral(温度36.5°C 湿度52%), card); dataLabel-setStyleSheet(color: #dddddd; font-size: 12px;); cardLayout-addWidget(nameLabel); cardLayout-addWidget(statusLabel); cardLayout-addWidget(dataLabel); cardLayout-addStretch(); return card; }注意这里我给卡片设置了setFixedSize(240, 140)固定大小。实际项目里可能有不同尺寸的卡片你可以改成根据内容自适应也可以做成横竖两种规格看需求。然后动态添加函数void MainWindow::onAddDevice() { m_deviceCount; QString deviceName QString(设备 #%1).arg(m_deviceCount); QFrame *card createDeviceCard(deviceName, m_deviceCount); int columns qMax(1, m_deviceGrid-geometry().width() / 260); int row (m_deviceCount - 1) / columns; int col (m_deviceCount - 1) % columns; m_deviceGrid-addWidget(card, row, col); }这里的列数计算我用了个取巧方式geometry().width()获取当前网格宽度除以每个卡片间距的宽度24020260得到当前宽度下能放几列。这样窗口缩放后添加的卡片会自动排列到正确位置。当然你需要在resizeEvent里刷新已有卡片的位置否则只有新卡片按新列排老卡片还在旧网格里。更稳妥的做法是每次窗口大小变化时重新计算列数把所有卡片从布局中取出再重新addWidget。这段代码放在主窗口的resizeEvent里void MainWindow::resizeEvent(QResizeEvent *event) { QMainWindow::resizeEvent(event); if (!m_deviceContainer) return; int columns qMax(1, m_deviceContainer-width() / 260); QListQWidget * cards; while (QLayoutItem *item m_deviceGrid-takeAt(0)) { if (QWidget *w item-widget()) { cards.append(w); } delete item; } int count cards.size(); for (int i 0; i count; i) { int row i / columns; int col i % columns; m_deviceGrid-addWidget(cards[i], row, col); } }这个思路很实用布局里的控件调整只需要“抽出再插入”新位置根据行列号计算即可。缺点是不能直接delete控件否则后面cards列表里变成悬空指针所以这里只是移动、不销毁。移除设备的逻辑void MainWindow::onRemoveDevice() { if (m_deviceCount 0) return; QLayoutItem *item m_deviceGrid-takeAt(m_deviceGrid-count() - 1); if (item) { QWidget *widget item-widget(); if (widget) { widget-deleteLater(); } delete item; m_deviceCount--; } }注意这里用的是deleteLater()而不是delete。原因是控件可能正在处理事件比如按钮点击的当前事件循环还没结束直接delete可能导致崩溃或野指针。deleteLater()会确保在当前事件处理后安全销毁。这个习惯在 Qt 里很重要凡是事件槽里删控件一律deleteLater()。3.5 QSS 样式表不用 Designer 也能做出漂亮的界面纯代码不意味着界面就一定生硬。Qt 的 QSSQt Style Sheets机制从 Qt 4 就开始有了语法和 CSS 几乎一样你可以给QPushButton、QWidget、QFrame等设置背景、边框、字体、圆角等样式搜一下setStyleSheet就能找到大量用法。我习惯在main.cpp启动时加载整份 QSS 文件这样方便集中管理QFile qssFile(:/style/global.qss); if (qssFile.open(QFile::ReadOnly | QFile::Text)) { QTextStream ts(qssFile); a.setStyleSheet(ts.readAll()); qssFile.close(); }这里的:/是 Qt 资源系统的前缀你需要把.qss文件放进.qrc资源文件里。如果没有资源文件也可以用相对路径读取但发布时路径容易出问题推荐放进资源。下面是上面设备卡片界面用的 QSSQMainWindow, QWidget { background-color: #2b2b2b; color: #e0e0e0; font-family: Microsoft YaHei; font-size: 13px; } QPushButton { background-color: #3c3f41; border: 1px solid #555555; border-radius: 4px; padding: 4px 12px; color: #e0e0e0; } QPushButton:hover { background-color: #4b4f52; border-color: #777777; } QPushButton:pressed { background-color: #2d2f30; } QLabel { background: transparent; } QScrollArea { background: transparent; border: none; } QFrame#deviceCard_ { background-color: #3a3d3e; border-radius: 8px; border: 1px solid #4e5152; }注意一个细节动态添加的QFrame有不同 objectName比如deviceCard_1、deviceCard_2QSS 里可以用通配符QFrame[objectName^deviceCard_]来选中前缀匹配的对象。写法如下QFrame[objectName^deviceCard_] { background-color: #3a3d3e; border-radius: 8px; border: 1px solid #4e5152; }这一点我觉得很实用因为动态生成控件的 objectName 肯定带变化的后缀属性选择器是匹配它们的首选方案。还有个小技巧给多个卡片设置不同的状态颜色可以用setProperty()加动态属性比如card-setProperty(status, online)然后 QSS 里写QFrame[statusonline] { border-left: 4px solid #00aa00; } QFrame[statusoffline] { border-left: 4px solid #aa0000; }setProperty以后再设置样式表需要调用style()-unpolish(card); style()-polish(card);来刷新否则样式不生效。这个小坑很常见很多新手在这里卡半天最后才发现是没刷新样式。4. 核心知识点拆解布局、事件与绘图等高频场景4.1 布局管理器的底层逻辑Qt 的布局系统核心是QLayoutItem这个抽象类。QVBoxLayout、QHBoxLayout、QGridLayout都持有若干QLayoutItem当窗口resize的时候布局管理器会依据控件的尺寸策略SizePolicy、最小/最大尺寸、伸缩因子来计算每个控件的实际几何位置。理解这个机制对纯代码设计很重要。你不需要精确计算每个控件的坐标只要设置好控件的尺寸策略即可。常用策略有QSizePolicy::Fixed控件尺寸固定不考虑拉伸QSizePolicy::Expanding尽量占用更多空间QSizePolicy::Preferred控件有推荐尺寸但可以被拉伸/压缩QSizePolicy::Ignored忽略控件的推荐尺寸比如一个输入框你希望它水平方向能自动拉伸垂直方向保持固定高度就可以写lineEdit-setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Fixed);这种细致控制在 Designer 里反而不太好操作纯代码就是一行 setter 的事。4.2 QScrollArea 动态内容排版技巧QScrollArea是纯代码界面中经常用到的容器它包含一个viewport和一个内部的widget。关键要理解滚动区域只负责滚动内部 widget 的布局和大小是分开管理的。常见组合方式QScrollArea *scrollArea new QScrollArea; QWidget *container new QWidget; QVBoxLayout *vLayout new QVBoxLayout(container); scrollArea-setWidget(container); scrollArea-setWidgetResizable(true);注意setWidgetResizable(true)的含义内部 widget 会自动跟随滚动区域的大小调整。如果设为 false内部 widget 就保持自身 sizeHint内容超出就会出滚动条但你手动调整布局时通常希望它自适应宽度所以这个值要设 true。另一个实用技巧是设置滚动条样式QScrollBar:vertical { background: #2b2b2b; width: 8px; } QScrollBar::handle:vertical { background: #555555; border-radius: 4px; min-height: 30px; } QScrollBar::add-line:vertical, QScrollBar::sub-line:vertical { height: 0; }这样滚动条会更精致一些Windows 默认的滚动条在深色界面下非常突兀。把add-line和sub-line的宽高设成 0可以隐藏上下箭头按钮这是深色界面比较干净的滚动条做法。4.3 自定义控件不用 Designer 怎么画特殊的界面元素纯代码界面最强大的地方是可以随意创造自定义控件尤其是那些用现成 QC 控件不好拼出来的元素。比如仪表盘、波形图、饼图、状态指示灯、滑块轨道等直接在paintEvent()里用QPainter绘制就行。以状态灯为例一个圆形的绿色/红色指示灯直接继承QWidget重写paintEventclass StatusLight : public QWidget { Q_OBJECT public: explicit StatusLight(QWidget *parent nullptr) : QWidget(parent) { setFixedSize(16, 16); m_color QColor(0, 170, 0); } void setColor(const QColor color) { m_color color; update(); } protected: void paintEvent(QPaintEvent *) override { QPainter painter(this); painter.setRenderHint(QPainter::Antialiasing); painter.setPen(Qt::NoPen); painter.setBrush(m_color); painter.drawEllipse(rect().adjusted(1, 1, -1, -1)); } private: QColor m_color; };QPainter 默认的抗锯齿要手动开否则画出来的圆会有锯齿边缘在深色背景下尤其明显。而update()是用于告诉 Qt 需要重绘的颜色变化后不调用它界面不会刷新。这个思路可以扩展到很多场景比如绘制波形曲线、进度环、开关滑块等等。核心就是继承 QWidget、重写paintEvent()、在事件里调用update()。如果数据量很大比如每秒刷新几百次波形可以单独开一个线程准备数据再通过信号槽把数据传递给界面线程触发update()不要在 UI 线程里做重型计算避免界面卡顿。4.4 信号槽与事件处理在纯代码中的应用纯代码界面和信号槽是天生一对。用 Designer 时界面上的控件 event 连接一般通过connect()在代码里做但控件本身的 objectName、类型、 parent 关系都不透明纯代码方式创建控件时可以直接new后立刻 connect代码自文档化看着顺序很清楚m_addButton new QPushButton(QStringLiteral(添加设备), this); connect(m_addButton, QPushButton::clicked, this, MainWindow::onAddDevice);这里我推荐使用新式信号槽语法QPushButton::clicked不要用老式的SIGNAL/SLOT宏因为新式语法在编译期就能检测信号和槽是否匹配类型安全。很多人第一次接触 Qt 是老教程学会了connect(button, SIGNAL(clicked()), this, SLOT(onClick()))这种写法在参数变化时容易踩坑且没有编译期检查我建议新项目全部用新式写法。事件层面的高级玩法还包括事件过滤eventFilter用于拦截鼠标、键盘事件或实现全局快捷键。比如实现“点击空白区域隐藏某个面板”bool MainWindow::eventFilter(QObject *obj, QEvent *event) { if (event-type() QEvent::MouseButtonPress) { QMouseEvent *mouseEvent static_castQMouseEvent *(event); if (!m_panel-geometry().contains(mouseEvent-pos())) { m_panel-hide(); } } return QMainWindow::eventFilter(obj, event); }安装事件过滤用installEventFilter(this)注意过滤事件后要返回基类的处理结果否则会阻断正常流程。4.5 动态刷新与子线程更新 UIQt 中最大的隐蔽坑之一就是“不能在子线程直接操作 UI 控件”。很多人直接从工作线程调用label-setText(...)结果界面不刷新、随机崩溃、或者出现各种诡异的“Cannot create children for a parent that is in a different thread”报错。正解是用信号槽跨线程通信。一个标准的写法是// 工作线程内部 emit dataReady(value); // 主线程的对象中 connect(worker, Worker::dataReady, this, MainWindow::onDataReady);这里信号传输默认使用QueuedConnection自动排队槽函数在主线程执行此时操作 UI 就是安全的。要注意自定义类型比如某个结构体在线程间传递时需要提前注册qRegisterMetaTypeMyData(MyData);这是经典易忽略的点。如果你在跨线程信号槽里传递自定义类型不注册的话运行时 Qt 会报错“Dont know how to handle ... use qRegisterMetaType”。遇到这个报错别想复杂了加一行注册即可。5. 项目实战一个可运行的完整示例代码5.1 完整代码结构一览为了让你更快地上手这里我把上面讲到的内容整合成一个可以直接运行的完整例子。主体结构是PureCodeUiDemo/ ├── PureCodeUiDemo.pro ├── main.cpp ├── mainwindow.h ├── mainwindow.cpp ├── devicecard.h ├── devicecard.cpp └── style.qssDeviceCard 是我单独封装的卡片控件类它比直接在函数里创建QFrame更符合面向对象思路也方便后续扩展。devicecard.h#ifndef DEVICECARD_H #define DEVICECARD_H #include QFrame class QLabel; class DeviceCard : public QFrame { Q_OBJECT public: explicit DeviceCard(const QString deviceName, QWidget *parent nullptr); void setStatus(bool online); void updateTemperature(double value); private: QLabel *m_nameLabel; QLabel *m_statusLabel; QLabel *m_temperatureLabel; }; #endifdevicecard.cpp#include devicecard.h #include QVBoxLayout #include QLabel DeviceCard::DeviceCard(const QString deviceName, QWidget *parent) : QFrame(parent) { setObjectName(DeviceCard); setFixedSize(240, 140); QVBoxLayout *layout new QVBoxLayout(this); layout-setContentsMargins(12, 10, 12, 10); layout-setSpacing(8); m_nameLabel new QLabel(deviceName, this); m_nameLabel-setObjectName(deviceNameLabel); m_statusLabel new QLabel(QStringLiteral(在线), this); m_statusLabel-setObjectName(deviceStatusOnline); m_temperatureLabel new QLabel(QStringLiteral(温度--°C), this); m_temperatureLabel-setObjectName(deviceDataLabel); layout-addWidget(m_nameLabel); layout-addWidget(m_statusLabel); layout-addWidget(m_temperatureLabel); layout-addStretch(); } void DeviceCard::setStatus(bool online) { if (online) { m_statusLabel-setText(QStringLiteral(在线)); m_statusLabel-setProperty(status, online); } else { m_statusLabel-setText(QStringLiteral(离线)); m_statusLabel-setProperty(status, offline); } style()-unpolish(m_statusLabel); style()-polish(m_statusLabel); } void DeviceCard::updateTemperature(double value) { m_temperatureLabel-setText(QStringLiteral(温度%1°C).arg(value, 0, f, 1)); }这里有个关键点setStatus里修改属性后必须调用style()-unpolish和style()-polish强制刷新样式否则 QSS 里设置的[statusoffline]规则不会生效。这是setProperty QSS 组合最常见的坑我用加粗提醒一下。mainwindow.cpp里把之前的创建卡片改成void MainWindow::onAddDevice() { m_deviceCount; DeviceCard *card new DeviceCard(QString(设备 #%1).arg(m_deviceCount)); connect(card, DeviceCard::somethingChanged, this, ...); // 按需连接 int columns qMax(1, m_deviceGrid-geometry().width() / 260); int row (m_deviceCount - 1) / columns; int col (m_deviceCount - 1) % columns; m_deviceGrid-addWidget(card, row, col); }5.2 模拟数据刷新演示纯代码界面的另一个优势是方便接模拟数据和真机数据。这里我再加一个QTimer每秒钟模拟刷新一次温度数据并更新到卡片上m_timer new QTimer(this); m_timer-setInterval(1000); connect(m_timer, QTimer::timeout, this, [this]() { for (int i 0; i m_deviceGrid-count(); i) { QLayoutItem *item m_deviceGrid-itemAt(i); if (DeviceCard *card qobject_castDeviceCard *(item-widget())) { double temp 20.0 (qrand() % 150) / 10.0; card-updateTemperature(temp); card-setStatus((qrand() % 5) ! 0); } } }); m_timer-start();注意这里用了 lambda 表达式和qobject_cast安全类型转换。itemAt(i)返回的是QLayoutItem*可能是空指针也可能是普通 widget 或嵌套布局所以要先判断类型。每次刷新都遍历整个网格布局对几十个卡片来说性能完全没问题如果卡片数量到了上千的级别建议用视图模型的方式优化。6. 常见问题与排查技巧实录6.1 编译期报错 unknown module(s) in qt: serialport这个报错在 Qt 5.15 时代特别常见。根本原因就是.pro文件里没有声明对应模块。比如你用到了QSerialPort却在.pro里没有写QT serialport。检查步骤是打开.pro文件确认QT行是否包含对应模块名如果没有补上即可如果补了还是报错检查你的 Qt 安装包是否勾选了对应模块安装时可以重新运行安装向导添加模块另一个常见易混的是 Qt Creator 里只单独构建了某个 Kit而该 Kit 对应的 Qt 版本里缺少该模块。解决方法是更换 Kit或重新安装带该模块的 Qt 版本。6.2 控件显示不出来或者位置错乱这个问题的原因多半出在布局未生效上。常见情况控件创建后设置了父对象但没有加入布局。比如new QPushButton(this)但没有layout-addWidget它会被动地放置在窗口的某个位置甚至根本不可见。窗口在setupUi里设置了中央控件但后面又用setLayout会把之前的布局替换掉。用setGeometry手动设置控件坐标视图拉伸后控件不会跟着走。排查时可以试着临时调用widget-show()看看是否真的创建了或者用 Qt 的自动布局调试信息——在 Qt Creator 中开启 “Debug QDebug” 或临时打印控件的geometry()。不过大多数情况下把控件加入布局、正确设置父对象问题就解决了。6.3 程序启动崩溃signal/slot 连接错误或空指针纯代码界面里最常见的崩溃原因是槽函数中访问了一个尚未初始化的成员指针。比如在setupUi()中new了m_deviceGrid但在构造函数之前某个信号被触发槽函数里用了m_addButton而m_addButton还是 nullptr。排查方式是断点调试看崩溃调用栈在槽函数里增加空指针判断在构造中统一先初始化所有成员再连接信号再触发任何可能立即执行的逻辑另外还有一个常见的崩溃场景是在paintEvent中创建了QPainter对象但忘了调用begin()/end()或者绘制时不匹配导致资源泄漏。QPainter 的正确用法是在 paintEvent 内创建局部变量构造时传入 widget 指针析构时自动结束绘制。6.4 界面刷新卡顿误在 UI 线程做耗时操作界面代码写好了运行起来却卡顿尤其是窗口缩放、拖拽时卡得厉害。这时候要从两个角度排查是不是在paintEvent里面干了重活比如加载图片、解析 JSON、读文件绝对不能在绘制事件里做这些应该提前缓存。是不是主线程里有无限循环、QThread::sleep、或大 try/catch 阻塞了事件循环信号槽连接的槽函数如果执行时间过长UI 无法及时响应。解决思路是把耗时任务移到子线程用信号槽回传结果或者用QtConcurrent异步执行并在主线程更新 UI。6.5 中文字体显示为方块或乱码Qt 默认字体在某些 Linux 环境缺少中文字体或者 Windows 下使用默认宋体后界面不美观。之前我提过解决办法就是在main.cpp中设置全局字体QFont font(Microsoft YaHei, 9); a.setFont(font);如果没有微软雅黑可以用QFontDatabase枚举系统中的中文字体选择一种可用字体作为备选。另外程序发布的机器上也要确保有对应字体否则界面在不同机器上显示效果会不一致。6.6 发布后按钮点击没反应这不是发布特有问题通常是因为信号没连接成功或者连接错了对象。常见情况是控件在创建时传入的 parent 不对信号连接时机过早比如控件还没创建就 connect或者槽函数访问了不存在的对象导致没执行。排查信号连接问题最直接的方法是在槽函数第一行加qDebug() clicked;如果打印了说明连接正常如果没打印检查 connect 语句及发送信号的对象是否和接收对象匹配。如果你是用 lambda 连接信号注意捕获方式。[this]在对象生命周期结束后执行 lambda 可能会访问悬空 this 指针。更好的方式是在连接时检查上下文对象比如connect(button, QPushButton::clicked, this, [this] { ... });这样 button 被销毁时连接自动断开。7. 一些我的个人习惯最后再分享一点我自己用纯代码写界面的习惯不一定所有人都认同但至少能帮你少走弯路。第一给每个控件设置一个有意义的objectName。这不是给 Qt 内部用的而是为了后续 QSS 选中和调试方便。ui-btnSaveLayout比ui-pushButton_3直观得多出问题也能快速定位。第二把界面的配置尽量外置。比如卡片颜色、按钮文案、背景色等尽量不在代码里散落字符串。要么放进 QSS 统一管理要么放在配置文件/常量表里。改起来方便也避免后期为了调整一个颜色翻遍整个文件。第三把每个界面模块封装成独立的QWidget子类。像DeviceCard一样自定义控件内部自己处理布局和事件暴露必要的接口和信号。这样主窗口代码只是把这些模块拼装起来逻辑清晰、可扩展性高。一个很典型的状态是主窗口的setupUi()函数控制在两百行以内每个区域就是一个自包含的 widget需要替换或者新增功能时只是增删一个类的问题。第四尽量用QFrame作为容器而不是直接用QWidget。QFrame 自带边框和样式能力视觉调试更方便而且可以和 QSS 的选择器配合做漂亮的卡片效果。当然这个不是绝对的只是我在实际项目里更习惯用 QFrame。第五不要害怕调试 QSS。纯代码布局写好了之后样式表是可以反复微调的运行起来看效果哪里不满意改哪里比 Designer 里改完还要重新编译.ui文件要快很多。这也是纯代码界面的一大潜在优势开发时每次改动因为不需要重新生成 ui 代码编译期反而更短。如果你想在这个示例基础上继续精进可以试试把 DeviceCard 扩展成可点击的卡片订阅鼠标事件、发送信号给主窗口、加上卡片拖拽排序重写 mousePressEvent/mouseMoveEvent 结合QDrag、或者给卡片增加“置顶”“删除”的按钮。这个方向能延伸出去的内容非常多每一种玩法都能练到 Qt 的核心机制。我从接触 Qt 到现在真正把纯代码界面用顺手之后就再也没靠 Designer 拖过一个正式项目界面。希望这篇分享能给你一些启发。