桌面应用 / 系统课时
理解 ui 指针和生成代码
理解 ui 指针和生成代码
本篇解决 Qt Designer 界面文件与 C++ 代码之间如何连接的问题。通过理解 setupUi 和自动生成的界面类,可以正确使用 Designer 提升开发效率,并避免直接修改会被覆盖的生成文件。
学习目标
- 理解
.ui文件、生成界面类和ui指针之间的关系 - 掌握
setupUi初始化界面的执行过程 - 知道哪些文件可以修改,哪些生成文件应该避免直接编辑
Designer 界面到 C++ 对象的转换过程
Qt Designer 保存的界面通常以 .ui 文件存在,本质上是一个 XML 描述文件,记录窗口结构、控件类型、布局关系以及属性设置。编译项目时,Qt 的构建工具会调用 uic 工具,把 .ui 文件转换成 C++ 头文件。
例如,一个名为 mainwindow.ui 的文件通常会生成类似 ui_mainwindow.h 的文件,其中包含一个界面类,例如 Ui::MainWindow。
应用程序并不是直接运行 .ui 文件,而是在窗口对象创建时,通过生成类中的 setupUi 方法创建控件并完成布局。

setupUi 如何初始化窗口
setupUi 是自动生成代码中的核心方法,它负责创建控件对象、设置属性、建立布局,并把控件加入父窗口。
典型的窗口类会通过组合方式持有一个 ui 指针:
#include "ui_mainwindow.h"
#include <QMainWindow>
class MainWindow : public QMainWindow
{
Q_OBJECT
public:
explicit MainWindow(QWidget *parent = nullptr)
: QMainWindow(parent), ui(new Ui::MainWindow)
{
ui->setupUi(this);
}
~MainWindow()
{
delete ui;
}
private:
Ui::MainWindow *ui;
};这里的执行顺序是:先创建 Ui::MainWindow 对象,再调用 setupUi(this),最后窗口中才存在 Designer 中设计的控件。
预期结果
MainWindow 创建成功,Designer 中添加的控件已经显示在窗口中。为什么不要修改生成文件
ui_mainwindow.h 属于自动生成代码。每次重新构建项目或修改 .ui 文件后,生成文件都可能重新创建,手动修改会丢失。
正确方式是在自己的窗口类中扩展逻辑,例如响应按钮点击、修改控件属性或读取输入内容。
不推荐:
// 不建议直接修改 ui_mainwindow.h
pushButton->setText("修改后的按钮");推荐:
// 在 MainWindow.cpp 中编写业务代码
ui->pushButton->setText("保存");这样 Designer 负责界面结构,业务代码负责运行逻辑,两者职责更加清晰。
生成代码变化时如何定位问题
当界面显示异常时,不应该首先打开生成文件修改,而应该检查以下位置:
.ui文件中控件是否存在- 控件对象名称是否正确
- 布局关系是否符合预期
setupUi是否在窗口初始化阶段调用
如果控件名称发生变化,例如 Designer 中把 pushButton 改成 saveButton,原来的业务代码也需要同步修改,否则会出现找不到成员的问题。
理解 ui 指针和生成代码的关系后,后续访问 Designer 控件时只需要关注窗口类中的业务代码,不需要参与维护自动生成文件。