简介面向Qt5初学者与桌面界面开发者的多UI切换与弹窗示例工程围绕主窗口内嵌多个子界面、按钮触发切换以及模态弹窗展示等常见需求提供可参考的实现组织方式。压缩包共29个文件以cpp源文件、h头文件、ui界面描述和o编译产物为主并含pro工程配置与Makefile整体约57KB便于直接打开对照编译与运行。已有182人学习适合需要理解窗口管理、界面切换和弹窗交互的读者。内容涉及QWidget的显示隐藏切换、QDialog自定义弹窗、QMessageBox提示、信号与槽通信及窗口过渡动画等要点也保留了多窗口协作与事件传递的工程结构可帮助读者快速定位界面切换逻辑、弹窗调用位置和编译配置差异作为课程设计或小型桌面项目的参考底稿较实用。1. Qt5 多 UI 页面切换与弹窗显示从一个用 hide/show 手动切换的老项目说起接手过一个 Qt5 的配置工具登录、设备列表、参数配置、日志四块界面全挤在主窗口里原作者用的是 hide 一个、show 一个的办法切几次之后窗口尺寸开始乱弹窗还盖不住父窗口的工具栏。后来把四份 .ui 拆成独立页面类交给 QStackedWidget 托管确认框和输入框统一走 QDialog界面层的代码从八百多行降到三百行出头。这套 qt ui 示例就是按这个思路整理的多份 .ui 各自独立编译、主窗口只负责调度、弹窗负责取值和确认一步一步都能跑起来。适合刚上手 Qt5、正被多界面切换和弹窗返回值折腾的开发者也适合手上有个界面层写乱了想重做一遍的人。2. 工程骨架.pro、ui/ 与 src/ 怎么对齐先把目录定下来后面所有问题都好排查。Qt5 里多 UI 项目的坑一大半不在代码逻辑而在“文件放哪、FORMS 里写没写、生成的头文件在哪”。这三个地方对齐了编译期就不会莫名其妙报ui_xxx.h: No such file。2.1 目录结构与 qmake 配置我一般把界面描述和业务代码分开放.ui 统一扔 ui/页面类放 src/主窗口只管调度。这样设计师改完界面重新保存不会和手写代码混在一个目录里互相覆盖。路径职责容易出问题的地方src/main.cpp入口设置高 DPI 属性后拉起主窗口属性必须在 QApplication 构造之前设置src/mainwindow.*主窗口持有 QStackedWidget做页面调度构造函数里别做耗时的数据初始化src/pagebase.h页面基类统一 onEnter / onLeave 与跳转信号忘了 Q_OBJECT信号连不上且不报错src/loginpage.*登录页独立 .ui控件 objectName 改了代码要同步改src/homepage.*主页/列表页数据刷新放在 onEnter别放构造函数ui/*.ui各页面与弹窗的界面描述文件名大小写要和 FORMS 里完全一致对应的 .pro 写起来并不复杂关键是 FORMS 和 HEADERS/SOURCES 三处要能对得上QT core gui widgets greaterThan(QT_MAJOR_VERSION, 4): QT widgets TARGET MultiPageDemo TEMPLATE app CONFIG c11 # 一份 .ui 对应一个页面漏写哪一行编译期就会报 ui_xxx.h 找不到 FORMS ui/mainwindow.ui \ ui/loginpage.ui \ ui/homepage.ui \ ui/settingpage.ui \ ui/confirmdialog.ui HEADERS src/mainwindow.h \ src/pagebase.h \ src/loginpage.h \ src/homepage.h \ src/settingpage.h \ src/confirmdialog.h SOURCES src/main.cpp \ src/mainwindow.cpp \ src/loginpage.cpp \ src/homepage.cpp \ src/settingpage.cpp \ src/confirmdialog.cpp INCLUDEPATH srcQT widgets这行是 Qt5 相对 Qt4 最直观的变化Qt4 时代 QtGui 里就有 QWidgetQt5 把它拆出去了漏写会得到一堆“QMainWindow 未定义”的报错。greaterThan(QT_MAJOR_VERSION, 4)是为了让同一份 .pro 在 Qt4 环境下也能编过纯 Qt5 项目里其实可以直接删掉。.ui 放在 ui/ 子目录时uic 生成的头文件会落到构建目录的同名子目录下qmake 会自动把它加进 include path所以代码里照常写#include ui_loginpage.h就行。但这里有个前提改过 FORMS 之后必须重新执行一次 qmake。只点构建按钮qmake 的工程文件缓存不会刷新你会对着一个明明写对了的 FORMS 条目怀疑人生。入口文件里顺手把高 DPI 打开不然后面每个页面都要单独处理缩放#include mainwindow.h #include QApplication int main(int argc, char *argv[]) { // 高 DPI 属性必须在 QApplication 构造前设置构造之后再设是无效的 QApplication::setAttribute(Qt::AA_EnableHighDpiScaling, true); QApplication::setAttribute(Qt::AA_UseHighDpiPixmaps, true); QApplication a(argc, argv); a.setApplicationName(QStringLiteral(MultiPageDemo)); MainWindow w; w.show(); return a.exec(); }AA_EnableHighDpiScaling打开后Qt 会按屏幕的 devicePixelRatio 缩放控件和字体AA_UseHighDpiPixmaps决定 2x 这类多倍图能不能被自动选中。两个都开1080p 和 4K 屏上界面的观感才不会差太多。注意这两个是静态函数写在 QApplication 构造之后就完全无效属于那种“代码看着没问题、现象却对不上”的情况。2.2 两种加载 .ui 的写法单继承还是多继承Qt Designer 生成的ui_xxx.h里其实就一个类里面全是控件指针和setupUi()。用它有两种姿势选错了后期改界面会很别扭。单继承has-a是把 Ui 对象当成员持有页面类本身还是干干净净的 QWidget// 单继承Ui 对象是成员需要自己管理生命周期 class LoginPage : public PageBase { Q_OBJECT public: explicit LoginPage(QWidget *parent nullptr); signals: void loginSuccess(const QString user); private slots: void onLoginClicked(); private: Ui::LoginPage *ui; // 用 new 创建父对象析构时要 delete };LoginPage::LoginPage(QWidget *parent) : PageBase(parent) , ui(new Ui::LoginPage) { ui-setupUi(this); // 这一行之后ui-xxx 才不是野指针 // 控件在 setupUi 之后才存在connect 必须写在这后面 connect(ui-btnLogin, QPushButton::clicked, this, LoginPage::onLoginClicked); } LoginPage::~LoginPage() { delete ui; }多继承is-a是让页面类同时继承 QWidget 和 Ui 生成的那个类好处是 Ui 里的控件名直接变成页面类的成员写起来短// 多继承Ui 里的控件直接成为自己的成员短但容易撞名 class SettingPage : public PageBase, private Ui::SettingPage { Q_OBJECT public: explicit SettingPage(QWidget *parent nullptr) : PageBase(parent) { setupUi(this); // 不需要 ui- 前缀直接用 btnSave } };两种都能跑我一般选单继承。原因是多继承下ui_settingpage.h会跟着settingpage.h一起被别的文件包含改一次界面就触发一大片重编译而且多继承时 Ui 里的控件名字直接进了类作用域页面一复杂就容易和自己的成员重名编译器报的错还挺绕。单继承多写一个ui-换来的隔离性值这个价。还有一个隐形的顺序问题setupUi(this)之前ui-btnLogin是未初始化的指针这时候 connect 不会报错运行时才崩。血泪经验是——页面构造函数里凡是出现ui-的地方先确认它在setupUi之后。2.3 容器选型QStackedWidget、QTabWidget 还是手动 show/hide多界面切换至少有四种常见做法选之前先想清楚页面之间是平级还是分步、用户能不能直接跳。方案适合场景代价手动 hide/show页面只有两三个、切换逻辑极简尺寸跟着当前页乱跳重叠区域容易漏刷QTabWidget页面平级、用户需要在标签间自由来回标签栏样式受限不适合全屏页面流QStackedWidget有明确流程登录→主页→设置页面全屏切换页面常驻内存需要自己管刷新时机QML StackView界面动效多、动画要求高和 Widgets 混用成本高得另起一套这套示例用的是 QStackedWidget。它内部只显示currentIndex指向的那一个子控件其余全部隐藏但对象还在所以页面状态天然保留——用户从设置页切回主页滚动位置、输入内容都还在。这个特性用好了很省事用不好就是“页面数据永远停在第一次进来时的样子”后面 3.3 会专门处理。手动 hide/show 的问题在窗口尺寸上最明显隐藏的控件不参与布局计算主窗口会随着当前页“缩”成不同的形状用户拖一下窗口大小切个页又变回去。QStackedWidget 的尺寸取所有子页的最大值窗口大小稳定代价是空页面也会把最小尺寸撑大这一点在 5.1 里会讲怎么处理。3. 页面切换核心QStackedWidget 与信号槽的完整链路容器选好之后真正要解决的是“页面怎么告诉主窗口我要跳转”。让页面直接持有主窗口指针是最省事也最容易失控的写法页面之间会互相耦合最后变成一团。这套示例的做法是页面只发信号主窗口决定跳到哪。3.1 主窗口里搭一个页面栈主窗口只做三件事创建页面、加进栈、连信号。页面的构造参数一律传this让 Qt 的父子对象树接管生命周期不用手写 delete。MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) , ui(new Ui::MainWindow) { ui-setupUi(this); // 1. 页面各自独立构造父对象先挂主窗口 m_loginPage new LoginPage(this); m_homePage new HomePage(this); m_settingPage new SettingPage(this); // 2. 按顺序入栈索引就是添加顺序别写死枚举值 ui-stackedWidget-addWidget(m_loginPage); // 0 ui-stackedWidget-addWidget(m_homePage); // 1 ui-stackedWidget-addWidget(m_settingPage); // 2 ui-stackedWidget-setCurrentIndex(0); // 3. 页面只负责喊一声跳不跳、跳到哪由主窗口说了算 connect(m_loginPage, LoginPage::loginSuccess, this, MainWindow::switchToPage); connect(m_homePage, PageBase::requestPage, this, MainWindow::switchToPage); connect(m_settingPage, PageBase::requestPage, this, MainWindow::switchToPage); // 4. 切换完成后再做收尾不要拦截 currentChanged 去改索引 connect(ui-stackedWidget, QStackedWidget::currentChanged, this, MainWindow::onPageChanged); }addWidget会自动把页面的父对象改成栈容器所以前面传this只是为了构造阶段有个归属最终归属还是栈。这一步不用纠结Qt 会处理好。真正值得写清楚的是switchToPage索引越界和重复切换这两个边界不处理早晚会出问题void MainWindow::switchToPage(int index) { // 越界直接吞掉setCurrentIndex 传非法值不会崩溃但界面会停在原地 // 上层逻辑以为切过去了后面查起来很难受 if (index 0 || index ui-stackedWidget-count()) { qWarning() invalid page index: index; return; } // 同一页重复切换会触发两次 currentChangedonEnter 里的耗时操作会跑两遍 if (index ui-stackedWidget-currentIndex()) { return; } ui-stackedWidget-setCurrentIndex(index); }count()是当前栈里的页面数量setCurrentIndex越界时 Qt 只会打印一条警告然后什么都不做返回值是 void你没法判断成没成功。所以在入口处主动挡一道比事后查“为什么点了没反应”省事得多。3.2 页面基类 PageBase把“我要跳转”抽成信号如果每个页面都自己定义一套跳转信号主窗口里就要写 N 个 connect加一个页面改一次主窗口。抽一个基类出来信号统一主窗口只连一次。// pagebase.h class PageBase : public QWidget { Q_OBJECT public: explicit PageBase(QWidget *parent nullptr) : QWidget(parent) {} ~PageBase() override default; // 被切进来 / 切走时由主窗口调用子类按需重写 virtual void onEnter() {} virtual void onLeave() {} signals: // 页面想跳转时统一发这个信号参数是目标页索引 void requestPage(int index); };页面里发信号就一行void HomePage::onSettingClicked() { emit requestPage(2); // 2 是设置页在栈里的位置 }这里有个设计取舍信号参数用 int 索引写起来最直接但页面必须知道自己在栈里的位置加一个页面就要回头核对所有魔法数字。第 6 章的改造会把 int 换成 QString 路由名彻底解耦。用索引也不是不行前提是把索引集中定义成枚举别散落在各个 .cpp 里// 集中在一个头文件里改顺序时只需要动这里 namespace PageId { enum Index { Login 0, Home 1, Setting 2 }; }Q_OBJECT宏不能省。省了之后类里声明的 signal 只是一个普通函数声明connect编译期能过运行时打印 “QObject::connect: signal not found”属于隐蔽性很强的问题。3.3 页面进出时机onEnter / onLeave 与数据回填QStackedWidget 的页面是常驻的构造之后就一直活着。这意味着构造函数只跑一次如果把“拉取最新数据”写在构造函数里用户第一次进来看到的是数据切走再切回来看到还是一小时前的。所以页面数据刷新要挂在“被切进来”这个时机上。Qt 本身有showEvent/hideEvent但栈里的页面在切换时不一定触发这两个事件取决于具体实现和窗口状态用自定义的 onEnter 更可控void MainWindow::onPageChanged(int index) { QWidget *w ui-stackedWidget-widget(index); if (!w) { return; } // 先把上一页的 onLeave 走完再走新页的 onEnter if (m_currentPage m_currentPage ! w) { m_currentPage-onLeave(); } if (auto *page qobject_castPageBase *(w)) { page-onEnter(); // 数据刷新、定时器启动都放这里 } m_currentPage qobject_castPageBase *(w); ui-statusBar-showMessage(tr(当前页面%1).arg(w-objectName())); }对应的页面实现void HomePage::onEnter() { // 每次进来都刷新避免展示过期数据 m_model-reload(); m_timer-start(5000); // 只有当前页需要轮询 } void HomePage::onLeave() { m_timer-stop(); // 切走一定要停否则后台一直在查库 }onLeave里停定时器这一步很容易被忽略。页面常驻内存定时器也跟着一直活着如果每页都开一个 5 秒轮询四个页面就是后台四路查询同时跑在嵌入式板子上很直观地表现为“切到哪页都卡”。4. 弹窗显示QMessageBox、自定义 QDialog 与非模态窗口多页面结构里弹窗往往比页面切换更容易出状况因为它的生命周期短、返回值要马上用指针一不小心就野了。这块先分清三种用法再看清父子关系和内存归属。4.1 QMessageBox 够用的场景别急着写 QDialog只提示、只确认、只报错这几种需求QMessageBox完全够静态函数一行搞定还会自动处理模态和本地化按钮。void HomePage::onDeleteClicked() { // 静态函数是模态的返回值就是用户点了哪个按钮 auto ret QMessageBox::question( this, tr(确认删除), tr(删除后不可恢复是否继续), QMessageBox::Yes | QMessageBox::No, QMessageBox::No); // 默认焦点放在 No 上防误触 if (ret QMessageBox::Yes) { doDelete(); } }最后一个参数是默认按钮。删除这种不可逆操作默认焦点一定给取消项这是产品层面的基本要求代码里也就多写一个参数。QMessageBox::warning/information用起来更简单但它们只有“确定”一个按钮拿不到用户的选择只能做提示。需要用户做决定的场合还是得用question或者自定义对话框。还有一种情况值得单独提错误提示如果是在exec()的对话框内部弹出的不要用QMessageBox::exec()套着弹Qt 允许但栈会越来越深调试时容易迷失。用open()让它是窗口模态、不阻塞当前调用栈会舒服很多。4.2 自定义 QDialog返回值、校验与数据回传需要用户输入内容的时候QMessageBox 就不够用了。自定义 QDialog 的关键在于数据通过构造函数进去通过成员函数出来中间用accept()/reject()决定结果。// confirmdialog.h class ConfirmDialog : public QDialog { Q_OBJECT public: explicit ConfirmDialog(QWidget *parent nullptr); ~ConfirmDialog() override; QString value() const { return m_value; } // 外部通过它取结果 private slots: void onOkClicked(); private: Ui::ConfirmDialog *ui; QString m_value; };ConfirmDialog::ConfirmDialog(QWidget *parent) : QDialog(parent) , ui(new Ui::ConfirmDialog) { ui-setupUi(this); setWindowTitle(tr(新建条目)); setModal(true); // 显式声明模态含义比 setWindowModality 清楚 connect(ui-btnOk, QPushButton::clicked, this, ConfirmDialog::onOkClicked); connect(ui-btnCancel, QPushButton::clicked, this, QDialog::reject); } void ConfirmDialog::onOkClicked() { m_value ui-lineEditName-text().trimmed(); // 校验不过就别 accept弹窗留在原地让用户改 if (m_value.isEmpty()) { QMessageBox::warning(this, tr(提示), tr(名称不能为空)); ui-lineEditName-setFocus(); return; } accept(); // 关闭弹窗并把 exec() 的返回值置为 QDialog::Accepted }外面调用的时候栈上分配就够了void HomePage::onNewItemClicked() { ConfirmDialog dlg(this); // 栈上对象离开作用域自动析构不存在泄漏 if (dlg.exec() QDialog::Accepted) { addItem(dlg.value()); // 只有用户确认过才取数据 } }exec()会阻塞在调用处内部起一个局部事件循环直到accept()或reject()才返回。这就是模态的本质——不是把父窗口“锁住”而是让调用处停下来等结果。反过来说如果exec()里面又调了另一个exec()就会出现嵌套事件循环关闭顺序一旦搞错主界面会失去响应。这种情况在“弹窗里再弹确认框”时最容易出现注意检查。accept()和reject()除了关闭窗口还会设置result()。要返回更丰富的结果可以在 accept 前把数据存进成员或者用QDialog::setResult(int)自定义返回码外面按码分支。4.3 非模态弹窗的父子关系与内存归属有些弹窗不该阻塞操作比如“实时预览”“详细日志”这类窗口用户希望它开着的时候还能点主界面。这时候用show()问题就从“返回值”变成了“什么时候销毁”。void HomePage::onDetailClicked() { // 已经开着就提到前台别每次都 new 一个新的 if (m_detailDlg) { m_detailDlg-raise(); m_detailDlg-activateWindow(); return; } m_detailDlg new DetailDialog(this); // 父对象是主窗口跟着主窗口一起销毁 m_detailDlg-setAttribute(Qt::WA_DeleteOnClose); // 关闭时自动 deleteLater // 关键对象被销毁后把指针置空否则下一次点击就是野指针 connect(m_detailDlg, QObject::destroyed, this, [this]() { m_detailDlg nullptr; }); m_detailDlg-show(); }这里有两个点必须同时做缺一个都会出问题。一是父对象。传了this弹窗的父对象就是主窗口主窗口析构时会连带删掉弹窗不传父对象弹窗就是独立顶层窗口主窗口关掉它还留着程序退不干净。二是WA_DeleteOnClose。开了这个属性弹窗关闭时 Qt 会调deleteLater()而不是立刻删这在槽函数里关闭自身时特别重要——立刻 delete 会把正在执行的栈帧连根拔掉。但开了属性之后m_detailDlg就变成了悬空指针必须靠destroyed信号清掉。少这一步第二次点“详情”就是必崩。还有一点如果弹窗是用new出来又传了父对象同时又手动delete那就是双重释放。父对象析构时会再删一次。规则很简单——要么栈上分配要么 new 父对象 不手动删别混着来。5. 避坑与排查切换和弹窗环节最容易翻车的五个地方这些是我在实际项目里真的遇到过的按“现象 → 原因 → 解决”整理对号入座基本能定位。5.1 切换环节的三个坑现象一切到某个页面后一片空白窗口尺寸也跟着变了。原因通常是这个页面没有真正加进 QStackedWidget而是在外面单独new出来直接show()了另一种情况是addWidget之后又把这个页面设了独立父窗口从栈里被“抢”走了。排查方法是在switchToPage里打印ui-stackedWidget-count()和widget(i)-objectName()数量对不上就是没加进去。解决就是统一走addWidget别手动改父对象。另外如果某个页面本身内容为空它的sizeHint很小栈的尺寸会被其他大页面决定看着像是“白屏”实际上是页面没内容这个要靠setMinimumSize给个下限。现象二点一次按钮槽函数执行了两次甚至多次。原因是页面在每次进入时重新connect了一遍而旧的连接从来没断开信号一发就触发 N 个槽。这种情况在没有用基类、各页面自己连主窗口的项目里特别常见。解决有两个方向一是把 connect 全部收进构造函数只在构造时连一次之后不再重复连二是必须动态连接时connect的最后一个参数加Qt::UniqueConnection重复连接会被吞掉。注意UniqueConnection对 lambda 写法不生效要用成员函数指针那种写法才行。定位手段是QObject::receivers()或者直接在槽里打日志看执行次数。现象三编译时报ui_loginpage.h: No such file or directory。三种可能FORMS 里漏了这份 .ui.ui 文件名在磁盘上是小写、在 FORMS 里写成了大写Linux 下大小写敏感Windows 下不报错换环境就出问题改过 FORMS 之后没有重新执行 qmake。解决顺序是——先在 .pro 里核对文件名再删掉构建目录重来一次最后检查构建目录下有没有生成ui_loginpage.h。这里没有捷径构建目录里的中间文件是判断问题出在 qmake 还是代码的唯一依据。5.2 弹窗环节的两个坑现象四弹窗关掉之后再点同一个按钮程序直接闪退。这是野指针的典型表现弹窗设了WA_DeleteOnClose关闭时对象已经销毁但成员指针还指着原来那块内存下一次raise()或者show()就崩了。解决就是前面 4.3 那套——连destroyed信号把指针置空或者在每次使用前判断if (m_dlg m_dlg-isVisible())。注意isVisible()判断不了已销毁的对象指针本身野了照样崩所以清空指针这一步不能省。现象五弹窗没有模态效果父窗口还能点用户连点两下开了两个窗。原因通常是该用exec()的地方用了show()或者构造时传的父对象是nullptr。show()本身不阻塞模态属性是在QDialog里通过setModal(true)或exec()体现的只调show()的话默认是非模态。解决是需要等结果的用exec()确实要非模态的就按 4.3 那套做单例拦截重复点击时raise()已有窗口。还有一种隐蔽情况——弹窗是exec()了但父对象传错成了另一个窗口模态范围就不对表现为“这个窗口点不动了那个还能点”排查时把父子关系打印出来最快。6. 二次开发把写死的索引换成一张路由表跑通之后最先想改的多半是那些散落各处的emit requestPage(2)。加一个页面就要回头数一遍索引改一次顺序全网崩这种写法撑不住三轮需求变更。我的做法是加一层极薄的路由表页面用名字注册按名字跳转第一次访问才构造。// router.h一条路由 名字 懒创建工厂 class Router : public QObject { Q_OBJECT public: explicit Router(QStackedWidget *stack, QObject *parent nullptr); void addRoute(const QString name, std::functionPageBase *(QWidget *) factory); bool go(const QString name); // 未注册返回 false别静默失败 QString current() const; private: QStackedWidget *m_stack; QHashQString, std::functionPageBase *(QWidget *) m_routes; QHashQString, PageBase * m_cache; // 访问过的常驻没访问过的不创建 };bool Router::go(const QString name) { if (!m_routes.contains(name)) { qWarning() route not found: name; return false; } PageBase *page m_cache.value(name, nullptr); if (!page) { // 第一次访问才构造启动阶段不用把七八个页面全建一遍 page m_routes.value(name)(m_stack); page-setObjectName(name); // 日志、样式表、自动化测试都靠它定位 m_stack-addWidget(page); m_cache.insert(name, page); connect(page, PageBase::requestPage, this, Router::go); } m_stack-setCurrentWidget(page); return true; }配套改两处PageBase::requestPage(int)改成requestPage(const QString )页面里写emit requestPage(setting)主窗口构造时集中注册一遍页面和索引彻底解绑。加页面只动注册表不动任何已有页面。改造前改造后收益emit requestPage(2)emit requestPage(setting)增删页面不影响已有调用构造时全部 new首次访问才创建启动时间随页面数线性下降索引散落在各 .cpp注册表集中一处路由关系一眼看全验证方法很简单启动后打印所有注册的路由名去掉一个页面看警告有没有正常打出来再给go()加个耗时日志确认二次进入同一页面没有重新构造——如果每次都新建m_cache那行就写错了。另外setCurrentWidget传的是指针页面被误删时它会静默失败所以哪怕路由表兜住了也建议在go()里加一句Q_ASSERT(page)。从那以后我每次新建页面都是先把路由名和注册行写完再去拖界面控件。中途返工过一次——页面做完了才发现名字和别处重了十几个 connect 全要改那种感觉不想再体验第二遍。这套骨架不复杂但顺序错了就要重来希望帮到你。本文还有配套的精品资源点击获取