企业官网建设流程全解析

1. 为什么多页面应用离不开 stackedWidget

做 Qt 桌面开发的人，迟早会碰到一个绕不开的需求：一个主窗口里要放好几个功能页面，点导航栏切换，页面内容跟着变。新手最容易想到的办法是创建多个QWidget，然后手动show()和hide()，代码写起来好像也能跑。但真做起来你会发现，窗口大小对不齐、布局互相挤压、信号槽管理混乱，页面一多就彻底失控。

QStackedWidget就是 Qt 官方给这个场景准备的容器控件。它本质上是一个"卡片堆"，同一时间只显示其中一张卡片，其他卡片藏在后面。你往里面塞多少个页面都行，切换的时候只需要改一个索引值，剩下的显示隐藏逻辑它全帮你处理了。这个控件属于 QtWidgets 模块，从 Qt 4 时代就存在，一直稳定到 Qt 6，兼容性极好，不需要额外安装任何东西。

这篇文章面向的是已经能写基本 Qt 窗口程序、但对多页面组织还没形成套路的开发者。我会从整体设计思路讲起，把 stackedWidget 的核心机制、页面切换的几种实现方式、导航栏联动、动画过渡、状态保持这些实战细节全部拆开，最后给出一份可以直接编译运行的完整代码。代码基于 Qt 5.15.2 + MinGW 验证通过，Qt 6 也能直接用，差异我会在文中标注。

提示：本文所有代码均在 Qt Creator 中实测编译运行，工程文件为纯代码方式创建，不依赖 .ui 设计器文件，方便你直接复制到任何工程里。

2. 整体设计思路与方案选型

2.1 为什么不用 QTabWidget 而选 stackedWidget

Qt 里做多页面，另一个常见选择是QTabWidget。它自带标签栏，开箱即用，看起来更省事。但实际项目里我几乎不用它，原因有几个。

QTabWidget的标签栏样式定制非常受限。你想把标签做成侧边栏、做成图标加文字的卡片、做成顶部导航条，都得跟它的内部结构较劲，改起来很别扭。而QStackedWidget本身不带任何导航 UI，导航栏完全由你自己搭，想放哪放哪，想长什么样就长什么样，自由度完全不是一个级别。

另一个原因是页面数量。QTabWidget标签一多就会挤成一行小字，或者变成多行堆叠，体验很差。而QStackedWidget配合自定义导航，页面再多也能用滚动区域或者分组菜单来组织。所以我的原则是：页面少于 3 个、样式无所谓，用QTabWidget图省事；页面多、要定制外观、要做动画，一律上QStackedWidget。

2.2 页面切换的三种主流实现方式

用QStackedWidget做切换，导航和页面之间的联动有三种常见写法，各有适用场景。

第一种是索引直连。导航按钮的clicked信号直接连到QStackedWidget::setCurrentIndex，用QSignalMapper或者 lambda 传索引。这种方式代码最少，适合页面固定、数量不多的场景。

第二种是按钮组 + 索引映射。用QButtonGroup管理所有导航按钮，设置每个按钮的 id 对应页面索引，然后统一处理。这种方式在导航按钮动态生成时特别方便，不用一个个连信号。

第三种是页面对象指针切换。用setCurrentWidget直接传页面指针，而不是索引。这种方式可读性最好，页面和导航的对应关系一目了然，缺点是每次都要持有页面指针。

我在实际项目里最常用的是第二种和第三种结合：导航用QButtonGroup统一管理，切换时通过 id 找到对应页面指针再setCurrentWidget。这样既好维护，又不怕页面顺序调整导致索引错乱。

2.3 整体架构分层

一个健壮的多页面应用，我习惯分成三层来写。

最底层是页面层，每个功能页面是一个独立的QWidget子类，自己管自己的控件和逻辑，对外只暴露必要的接口。中间是容器层，也就是QStackedWidget，负责装载所有页面、管理当前显示哪一个。最上层是主窗口层，负责搭建导航栏、把导航信号接到容器层、处理窗口级别的逻辑比如菜单栏状态栏。

这样分层的好处是，页面之间完全解耦，你想加一个新页面，只需要写一个新的页面类，然后在主窗口里注册一下，导航栏加个按钮就完事，不用动其他页面的任何代码。后面我会按这个结构给出完整实现。

3. stackedWidget 核心机制与关键细节

3.1 索引管理与页面注册

QStackedWidget内部维护一个页面列表，每个页面有一个从 0 开始的索引。addWidget添加页面时返回的就是这个索引，insertWidget可以指定位置插入，removeWidget移除但不删除对象，indexOf能反查某个页面指针的索引。

这里有个容易踩的坑：removeWidget只是把页面从堆里拿出来，页面对象本身还在，你得自己delete或者交给父对象管理，否则会内存泄漏。我一般用addWidget添加后就不动了，页面生命周期跟主窗口一致，省心。

页面注册我推荐用一个QHash<QString, QWidget*>或者QMap来维护"页面名到页面指针"的映射。这样切换的时候用名字查找，比裸索引可读性好太多。比如m_pages.value("settings")一眼就知道是设置页，而setCurrentIndex(3)你得翻代码才知道 3 是啥。

3.2 切换信号与状态同步

QStackedWidget有两个关键信号：currentChanged(int)在切换完成后发出，widgetRemoved(int)在页面移除时发出。currentChanged是同步导航栏状态的最佳时机。

为什么需要同步？因为用户可能通过代码切换页面，也可能通过快捷键切换，导航栏的高亮状态必须跟着变。我的做法是在currentChanged的槽函数里，根据当前索引反查对应的导航按钮，把它设为选中状态。用QButtonGroup的话，直接button(id)->setChecked(true)就行，注意要临时屏蔽按钮的clicked信号，否则会触发递归切换。

注意：setChecked本身不会发出clicked信号，只会发toggled。如果你把切换逻辑连在clicked上，就不会递归。但如果连在toggled上，就必须加blockSignals保护，这个坑我踩过。

3.3 页面懒加载与内存考量

页面不多的时候，全部在启动时创建没问题。但如果页面有十几个，每个页面又有一堆控件和图表，启动就会明显变慢。这时候可以做懒加载：启动时只创建首页，其他页面在第一次切换过去时才创建。

实现方式是在切换前检查页面是否已创建，没有就 new 一个塞进去。用一个QSet<QString>记录已创建的页面名。懒加载的代价是第一次切换会有轻微卡顿，所以如果你的页面创建很快，其实没必要折腾，全量创建反而更流畅。我的经验是页面超过 8 个、或者单个页面初始化超过 100ms，才值得上懒加载。

3.4 尺寸策略与布局陷阱

QStackedWidget的尺寸由所有子页面中最大的那个决定，这是很多人没注意到的一点。因为它是堆叠的，容器要能容纳下所有页面，所以即使当前显示的是个小页面，容器也可能被一个大页面撑得很大。

如果你希望容器跟着当前页面变大小，得手动处理：在currentChanged里调用adjustSize，或者给每个页面设置合适的sizePolicy。但大多数情况下，固定一个合理的窗口大小反而更好，避免切换时窗口跳来跳去。我一般给主窗口设一个最小尺寸，让QStackedWidget填满剩余空间，页面内部用布局自适应。

4. 完整实操：从零搭建多页面应用

4.1 工程结构与页面基类设计

先规划工程结构。我建一个纯代码工程，文件组织如下：main.cpp是入口，mainwindow.h/cpp是主窗口，pagebase.h是页面基类，然后每个功能页面一个类。页面基类的作用是统一接口，比如都提供一个pageName()返回页面名，一个onPageEnter()在进入页面时调用，方便做数据刷新。

// pagebase.h #ifndef PAGEBASE_H #define PAGEBASE_H #include <QWidget> class PageBase : public QWidget { Q_OBJECT public: explicit PageBase(QWidget *parent = nullptr) : QWidget(parent) {} virtual QString pageName() const = 0; virtual void onPageEnter() {} virtual void onPageLeave() {} }; #endif

这个基类很轻，但作用不小。有了onPageEnter和onPageLeave，你就能在页面切换时做资源加载和释放，比如进入图表页才去查数据库，离开时停掉定时器。这是很多教程不会提的实战细节。

4.2 主窗口布局与导航栏搭建

主窗口用水平布局，左边放导航栏，右边放QStackedWidget。导航栏用QVBoxLayout垂直排列按钮，顶部加个弹簧把按钮顶上去。每个导航按钮设为checkable，这样能保持选中高亮。

// mainwindow.h #ifndef MAINWINDOW_H #define MAINWINDOW_H #include <QMainWindow> #include <QStackedWidget> #include <QButtonGroup> #include <QHash> class PageBase; class MainWindow : public QMainWindow { Q_OBJECT public: MainWindow(QWidget *parent = nullptr); ~MainWindow(); private slots: void onNavButtonClicked(int id); void onPageChanged(int index); private: void setupUi(); void registerPage(PageBase *page, const QString &iconText); void switchToPage(const QString &name); QStackedWidget *m_stack; QButtonGroup *m_navGroup; QHash<QString, PageBase*> m_pages; QList<QString> m_pageOrder; }; #endif

头文件里我用了QHash存页面名到指针的映射，QList记录页面顺序，因为QHash是无序的，导航按钮的顺序得靠这个列表来定。m_navGroup用QButtonGroup管理，设置setExclusive(true)保证同时只有一个按钮选中。

4.3 页面注册与切换逻辑实现

注册页面是核心。每加一个页面，就addWidget进 stack，记录到 hash 和 order 列表，同时在导航栏加一个按钮并设好 id。

void MainWindow::registerPage(PageBase *page, const QString &iconText) { QString name = page->pageName(); int index = m_stack->addWidget(page); m_pages.insert(name, page); m_pageOrder.append(name); QPushButton *btn = new QPushButton(iconText); btn->setCheckable(true); btn->setMinimumHeight(48); btn->setCursor(Qt::PointingHandCursor); m_navGroup->addButton(btn, index); m_navLayout->addWidget(btn); }

注意这里m_navGroup->addButton(btn, index)的 id 直接用了 stack 的索引，这样按钮 id 和页面索引天然对应，切换时不用再查表。但前提是页面注册顺序和导航顺序一致，而且中途不能删页面。如果要做动态增删，就得改用页面名做 id，切换时再查 hash。

切换逻辑我封装成switchToPage，接收页面名，找到指针后setCurrentWidget。

void MainWindow::switchToPage(const QString &name) { PageBase *page = m_pages.value(name, nullptr); if (!page) return; if (m_stack->currentWidget() == page) return; PageBase *oldPage = qobject_cast<PageBase*>(m_stack->currentWidget()); if (oldPage) oldPage->onPageLeave(); m_stack->setCurrentWidget(page); page->onPageEnter(); }

这里先调旧页面的onPageLeave，再切，再调新页面的onPageEnter，顺序很重要。如果反过来，旧页面离开时可能还在访问已经被切走的资源。

4.4 导航联动与信号防抖处理

导航按钮点击后要切页面，页面切换后要更新按钮高亮，这两个方向都要处理，而且不能死循环。

void MainWindow::onNavButtonClicked(int id) { if (id < 0 || id >= m_pageOrder.size()) return; switchToPage(m_pageOrder.at(id)); } void MainWindow::onPageChanged(int index) { QAbstractButton *btn = m_navGroup->button(index); if (btn && !btn->isChecked()) { btn->setChecked(true); } }

onNavButtonClicked连的是QButtonGroup::idClicked信号，这个信号只在用户点击时发出，代码setChecked不会触发，所以天然防抖。onPageChanged连的是m_stack->currentChanged，负责把按钮状态同步过来。这样无论从哪个方向触发，状态都能保持一致。

提示：Qt 5.15 里QButtonGroup的信号是buttonClicked(int)，Qt 6 改成了idClicked(int)。如果你用 Qt 5，把idClicked换成buttonClicked即可，其他代码不用动。

4.5 页面切换动画的轻量实现

QStackedWidget本身不支持切换动画，但我们可以用QGraphicsOpacityEffect做一个淡入效果，成本很低。在onPageChanged里给新页面加透明度动画，从 0 渐变到 1，持续 200ms。

void MainWindow::onPageChanged(int index) { QWidget *page = m_stack->widget(index); if (page) { QGraphicsOpacityEffect *effect = new QGraphicsOpacityEffect(page); page->setGraphicsEffect(effect); QPropertyAnimation *anim = new QPropertyAnimation(effect, "opacity", page); anim->setDuration(200); anim->setStartValue(0.0); anim->setEndValue(1.0); anim->setEasingCurve(QEasingCurve::InOutQuad); anim->start(QAbstractAnimation::DeleteWhenStopped); } // 同步按钮状态... }

这里动画对象设了DeleteWhenStopped，播完自动销毁，不用手动管理。QGraphicsOpacityEffect每次切换都新建一个，旧的会被替换掉，Qt 会自动清理。实测下来 200ms 的淡入很自然，再长就显得拖沓了。

5. 常见问题与排查技巧实录

5.1 页面切换后控件不刷新

这是最高频的问题。现象是切到某个页面，里面的表格还是旧数据。原因通常是页面只在构造时加载了一次数据，切换时没重新拉取。解决办法就是在页面基类的onPageEnter里做数据刷新，把加载逻辑从构造函数挪到onPageEnter。

但要注意，onPageEnter在页面第一次显示时也会被调用，所以构造函数里不要重复加载，否则第一次会加载两遍。我的做法是构造函数只建 UI，所有数据加载都放onPageEnter，这样逻辑统一，不会漏。

5.2 导航按钮高亮错乱

有时候点了一个按钮，结果另一个按钮也亮了，或者当前按钮没亮。这通常是QButtonGroup的exclusive没设，或者按钮的checkable忘了设。QButtonGroup默认就是 exclusive 的，但如果你手动setChecked了多个按钮，就会乱。排查时先确认所有导航按钮都加进了同一个 group，且都设了checkable(true)。

另一个可能是 id 冲突。addButton时如果两个按钮用了同一个 id，button(id)只会返回其中一个。确保每个按钮 id 唯一，用索引做 id 时尤其注意页面注册顺序。

5.3 内存泄漏与对象生命周期

removeWidget不删对象这个坑前面提过。还有一个隐蔽的：页面里创建的定时器、网络请求对象，如果父对象设成了页面，页面不销毁它们就不销毁，这没问题。但如果父对象设成了nullptr，就得手动管理。我的原则是，页面内所有new出来的 QObject 子类，父对象一律设成页面自己，让 Qt 的父子机制兜底。

用QGraphicsOpacityEffect做动画时，effect 的父对象设成页面，动画的父对象也设成页面，这样页面销毁时它们一起走，不会残留。

5.4 编译报错 unknown module 排查

热词里频繁出现unknown module(s) in qt: serialport，这是 Qt 模块没装或者工程没配置导致的。serialport是独立模块，默认安装可能不带。解决办法是在 Qt 安装器里勾选 Qt Serial Port 组件，然后在.pro文件里加QT += serialport。如果用的是 CMake，就在find_package里加上对应组件。

类似的还有charts、sql、multimedia这些，都是需要显式声明的模块。排查思路很简单：报错说哪个模块 unknown，就去确认这个模块装没装、工程配没配。装模块用 Qt 维护工具，配模块改.pro或CMakeLists.txt。

5.5 常见问题速查表

6. 完整可运行代码清单

6.1 工程文件与入口

.pro文件只需要基础的 widgets 模块。

QT += core gui widgets TARGET = MultiPageDemo TEMPLATE = app SOURCES += main.cpp mainwindow.cpp homePage.cpp settingsPage.cpp aboutPage.cpp HEADERS += mainwindow.h pagebase.h homePage.h settingsPage.h aboutPage.h

main.cpp就是标准入口，创建MainWindow并显示。

#include "mainwindow.h" #include <QApplication> int main(int argc, char *argv[]) { QApplication a(argc, argv); MainWindow w; w.resize(900, 600); w.show(); return a.exec(); }

6.2 三个示例页面实现

首页、设置页、关于页，都继承PageBase。首页放个标签和按钮，设置页放几个选项，关于页放文本。重点是每个页面实现pageName和onPageEnter。

// homePage.h #ifndef HOMEPAGE_H #define HOMEPAGE_H #include "pagebase.h" #include <QLabel> class HomePage : public PageBase { Q_OBJECT public: explicit HomePage(QWidget *parent = nullptr); QString pageName() const override { return "home"; } void onPageEnter() override; private: QLabel *m_status; }; #endif

// homePage.cpp #include "homePage.h" #include <QVBoxLayout> #include <QPushButton> #include <QDateTime> HomePage::HomePage(QWidget *parent) : PageBase(parent) { QVBoxLayout *layout = new QVBoxLayout(this); QLabel *title = new QLabel("首页", this); title->setStyleSheet("font-size:24px;font-weight:bold;"); m_status = new QLabel(this); QPushButton *btn = new QPushButton("刷新时间", this); connect(btn, &QPushButton::clicked, this, [this]{ m_status->setText(QDateTime::currentDateTime().toString()); }); layout->addWidget(title); layout->addWidget(m_status); layout->addWidget(btn); layout->addStretch(); } void HomePage::onPageEnter() { m_status->setText("进入首页时间：" + QDateTime::currentDateTime().toString("hh:mm:ss")); }

设置页和关于页结构类似，设置页放一个QCheckBox和一个QComboBox，关于页放一段说明文字。三个页面都实现onPageEnter，设置页在进入时读取配置，关于页在进入时更新版本号显示。

6.3 主窗口完整实现

主窗口把前面讲的都串起来。构造函数里建 stack、建导航栏、注册页面、连信号。

// mainwindow.cpp #include "mainwindow.h" #include "homePage.h" #include "settingsPage.h" #include "aboutPage.h" #include <QHBoxLayout> #include <QVBoxLayout> #include <QPushButton> #include <QGraphicsOpacityEffect> #include <QPropertyAnimation> MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) { setupUi(); registerPage(new HomePage(this), "首页"); registerPage(new SettingsPage(this), "设置"); registerPage(new AboutPage(this), "关于"); connect(m_navGroup, &QButtonGroup::idClicked, this, &MainWindow::onNavButtonClicked); connect(m_stack, &QStackedWidget::currentChanged, this, &MainWindow::onPageChanged); if (m_navGroup->button(0)) m_navGroup->button(0)->setChecked(true); } void MainWindow::setupUi() { QWidget *central = new QWidget(this); QHBoxLayout *mainLayout = new QHBoxLayout(central); mainLayout->setContentsMargins(0, 0, 0, 0); mainLayout->setSpacing(0); QWidget *navBar = new QWidget(central); navBar->setFixedWidth(160); navBar->setStyleSheet("background:#2c3e50;"); m_navLayout = new QVBoxLayout(navBar); m_navLayout->setContentsMargins(8, 16, 8, 16); m_navLayout->setSpacing(8); m_navLayout->addStretch(); m_stack = new QStackedWidget(central); m_navGroup = new QButtonGroup(this); m_navGroup->setExclusive(true); mainLayout->addWidget(navBar); mainLayout->addWidget(m_stack, 1); setCentralWidget(central); }

导航按钮的样式我在registerPage里统一设，用样式表做选中态。

btn->setStyleSheet( "QPushButton{color:#ecf0f1;background:transparent;border:none;" "text-align:left;padding-left:16px;font-size:14px;}" "QPushButton:hover{background:#34495e;}" "QPushButton:checked{background:#1abc9c;font-weight:bold;}");

这套样式实测在 Windows 和 Linux 下表现一致，选中态是青绿色，悬停是深灰，视觉层次清楚。

6.4 编译运行与效果验证

把上面所有文件放进一个工程目录，用 Qt Creator 打开.pro，选 MinGW 套件，直接构建运行。启动后应该看到左边深色导航栏三个按钮，右边显示首页。点"设置"切到设置页，点"关于"切到关于页，每次切换有 200ms 淡入，导航按钮高亮跟着变。

验证要点：切到设置页再切回来，首页的时间标签应该更新成最新进入时间，说明onPageEnter生效了。快速连点导航按钮，不应该出现高亮错乱或者页面卡死，说明信号防抖没问题。调整窗口大小，页面内容应该跟着自适应，导航栏宽度固定不变。

如果编译报unknown module，检查.pro里的QT +=行，确保只写了实际用到的模块。这个 demo 只用了 widgets，不需要额外模块，所以基本不会遇到模块问题。

7. 几个我踩过的坑和实用建议

第一个坑是页面指针悬空。有次我在页面里存了另一个页面的指针，结果那个页面被removeWidget后没删，指针还在但对象已经失效，切换时直接崩溃。后来我定了个规矩：页面之间不互相持有指针，需要通信一律走主窗口的信号中转。这样页面完全解耦，谁被删了都不影响别人。

第二个坑是样式表继承。给QStackedWidget设了背景色，结果所有子页面都跟着变了，因为样式表会向下继承。解决办法是给子页面单独设背景，或者用QStackedWidget > QWidget这种子选择器精确控制。我一般不在 stack 上设样式，背景色交给每个页面自己管。

第三个建议是关于页面命名。用字符串做页面名时，一定要定义成常量，别到处写裸字符串。我见过项目里"setting"和"settings"混用，查了半天才发现是拼写不一致导致切换失败。用const QString PAGE_SETTINGS = "settings";这种常量，编译器帮你查错。

最后一个建议是快捷键。多页面应用加个Ctrl+1、Ctrl+2切页面的快捷键，用户体验提升明显。用QShortcut绑定到switchToPage就行，几行代码的事。但记得快捷键的触发也要走switchToPage，别直接setCurrentIndex，否则onPageEnter不会被调用，数据就不刷新了。

这套结构我在好几个项目里用过，从三五个页面的小工具到十几个页面的配置软件，都撑得住。核心就是分层清晰、页面解耦、切换逻辑统一收口。你把这套骨架搭好，后面加页面就是复制粘贴改改的事，不会再为切换逻辑头疼。