前言导航栏Navigation Bar是应用骨架里最显眼的部分用户靠它知道自己在哪、能去哪。一个设计良好的导航栏应该做到三件事——清楚标出当前位置、点击立刻响应、状态永远和内容区一致。Qt 里做导航栏最省事的是QToolBar最好看的是用按钮 QStackedWidget手搓最原生的是用QTabBar或QListWidget当导航项。但不管用哪种核心机制都是同一个一组互斥的按钮当前只有一个被选中驱动一个堆叠内容区。本文会把这个机制讲透QButtonGroup的互斥原理、QStackedWidget的联动、QSS 定制的要点以及实现中最典型的几个坑。一、导航栏的几种形态先做技术选型。按官方组件 vs 自绘排开形态实现方式外观可控性开发成本适用场景工具栏QToolBarQAction中QSS 受限低传统桌面软件、菜单式功能标签栏QTabBar独立使用中低浏览器式顶部标签导航列表导航QListWidget高低侧边栏式导航VSCode 风自绘按钮组QPushButtonQButtonGroup极高中需要图标文字角标等定制本文重点讲最后一种——自绘按钮组因为它是外观问题最多、也最能学到东西的方案其他几种掌握原理后都是它的简化版。QToolBar若只是要个能用的工具栏addToolBar()addAction()两行就够它会自动停靠到QMainWindow顶部但它的样式受QStyle影响很大跨平台表现不一致深度定制比较痛苦这正是很多人转向自绘的原因。二、核心原理互斥按钮组导航栏当前选中项唯一这个约束用QButtonGroup一个属性就能实现auto *group new QButtonGroup(this); group-setExclusive(true); // 关键互斥 group-addButton(btnHome, 0); // 第二个参数是 id group-addButton(btnMsg, 1); group-addButton(btnSet, 2);QButtonGroup本身不是 widget不可见它只是一组按钮的管理器职责有三互斥setExclusive(true)后点一个自动取消其他ID 映射给每个按钮绑一个 int id用idClicked(int)拿到统一信号不用给每个按钮单独连信号只连组的信号即可。这里有个必须提醒的 API 差异信号Qt5Qt6按钮点击带 idbuttonClicked(int)idClicked(int)按钮按下buttonPressed(int)idPressed(int)按钮释放buttonReleased(int)idReleased(int)按钮切换buttonToggled(QAbstractButton*, bool)idToggled(int, bool)Qt6 把传指针的重载去掉了统一改成传 id。Qt5 代码里写QButtonGroup::buttonClickedQt6 会编译不过得换成idClicked。这是 Qt5 迁移到 Qt6 时的高频报错点。按钮必须设 checkable❌ 错误写法auto *btn new QPushButton(QStringLiteral(首页)); group-addButton(btn, 0); // 按钮不可选中互斥机制无从谈起永远看不出当前在哪✅ 正确写法auto *btn new QPushButton(QStringLiteral(首页)); btn-setCheckable(true); // 必须否则不会被 checked btn-setChecked(true); // 默认选中首页 group-addButton(btn, 0);setCheckable(true)是导航按钮和普通按钮的唯一区别。忘了这一句症状是点了没反应、看不出选中状态这是导航栏最经典的坑。三、实战顶部导航 内容区联动实现一个带 QSS 样式的导航栏顶部横向排列点击切换下方内容区。cmake_minimum_required(VERSION 3.16) project(NavbarDemo LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_AUTOMOC ON) set(CMAKE_AUTORCC ON) # 有 .qrc 资源文件时必须 find_package(Qt6 REQUIRED COMPONENTS Widgets) add_executable(NavbarDemo main.cpp mainwindow.cpp mainwindow.h resources.qrc) target_link_libraries(NavbarDemo PRIVATE Qt6::Widgets)qmake 版本QT widgets CONFIG c17 TARGET NavbarDemo SOURCES main.cpp mainwindow.cpp HEADERS mainwindow.h RESOURCES resources.qrc头文件// mainwindow.h #ifndef MAINWINDOW_H #define MAINWINDOW_H #include QWidget class QButtonGroup; class QStackedWidget; class MainWindow : public QWidget { Q_OBJECT public: explicit MainWindow(QWidget *parent nullptr); private: void buildNavBar(); void buildContent(); QWidget *m_navBar nullptr; QButtonGroup *m_group nullptr; QStackedWidget *m_stack nullptr; }; #endif // MAINWINDOW_H实现// mainwindow.cpp #include mainwindow.h #include QButtonGroup #include QPushButton #include QStackedWidget #include QLabel #include QVBoxLayout #include QHBoxLayout #include QDebug namespace { struct NavItem { QString text; QString iconPath; QString pageTip; }; const NavItem kNavItems[] { {QStringLiteral(首页), QStringLiteral(:/icons/home.png), QStringLiteral(欢迎回到首页)}, {QStringLiteral(消息), QStringLiteral(:/icons/msg.png), QStringLiteral(你还没有新消息)}, {QStringLiteral(统计), QStringLiteral(:/icons/chart.png), QStringLiteral(这里是数据统计页)}, {QStringLiteral(设置), QStringLiteral(:/icons/setting.png), QStringLiteral(应用偏好设置)}, }; constexpr int kNavCount int(sizeof(kNavItems) / sizeof(kNavItems[0])); } // namespace MainWindow::MainWindow(QWidget *parent) : QWidget(parent) { setWindowTitle(QStringLiteral(导航栏示例)); resize(860, 560); buildNavBar(); buildContent(); auto *root new QVBoxLayout(this); root-setContentsMargins(0, 0, 0, 0); root-setSpacing(0); root-addWidget(m_navBar); root-addWidget(m_stack, 1); // 默认选中第一项并同步内容区 if (auto *first m_group-button(0)) { first-setChecked(true); m_stack-setCurrentIndex(0); } } void MainWindow::buildNavBar() { m_navBar new QWidget; m_navBar-setObjectName(QStringLiteral(navBar)); m_navBar-setAttribute(Qt::WA_StyledBackground, true); // 让 QSS 背景生效 m_navBar-setFixedHeight(52); // 固定高度防抖动 auto *navLayout new QHBoxLayout(m_navBar); navLayout-setContentsMargins(12, 0, 12, 0); navLayout-setSpacing(4); m_group new QButtonGroup(this); m_group-setExclusive(true); // 互斥保证同时只有一个选中 for (int i 0; i kNavCount; i) { auto *btn new QPushButton(kNavItems[i].text, m_navBar); btn-setCheckable(true); // 关键可选中 btn-setIcon(QIcon(kNavItems[i].iconPath)); btn-setIconSize(QSize(18, 18)); btn-setCursor(Qt::PointingHandCursor); btn-setFixedHeight(34); m_group-addButton(btn, i); // 绑定 id navLayout-addWidget(btn); } navLayout-addStretch(); // 把按钮推到左边 // 只连组的信号不用逐个按钮连接 connect(m_group, QButtonGroup::idClicked, this, [this](int id) { if (id 0 id m_stack-count()) m_stack-setCurrentIndex(id); }); m_navBar-setStyleSheet(R( QWidget#navBar { background-color: #1f2430; border-bottom: 1px solid #2c3346; } QPushButton { color: #b8c0d0; background: transparent; border: none; border-radius: 6px; padding: 0 16px; font-size: 14px; } QPushButton:hover { background-color: #2a3145; color: #ffffff; } QPushButton:checked { background-color: #3d6fff; color: #ffffff; font-weight: bold; } )); } void MainWindow::buildContent() { m_stack new QStackedWidget; for (int i 0; i kNavCount; i) { auto *page new QWidget; auto *label new QLabel(kNavItems[i].pageTip, page); label-setAlignment(Qt::AlignCenter); label-setStyleSheet(QStringLiteral(font-size:20px;color:#666;)); auto *layout new QVBoxLayout(page); layout-addWidget(label); m_stack-addWidget(page); } }入口// main.cpp #include mainwindow.h #include QApplication int main(int argc, char *argv[]) { QApplication app(argc, argv); MainWindow w; w.show(); return app.exec(); }资源文件resources.qrc里用qresource prefix/icons声明前缀代码里就写:/icons/home.png。注意:是资源系统前缀/icons是 qresource 的 prefix不要写成:/qresource/icons/...那是目录名不是 prefix。四、进阶让导航栏和内容区双向同步上面是单向的点按钮 → 切页面。但内容区也可能主动切页比如设置页里点按钮跳到关于页这时按钮选中状态必须跟着变。❌ 错误写法只连了单向connect(m_group, QButtonGroup::idClicked, m_stack, QStackedWidget::setCurrentIndex); // 内容区自己 setCurrentIndex 时按钮状态不会更新✅ 正确写法回连currentChanged// 反向内容区变了 → 同步按钮选中状态 connect(m_stack, QStackedWidget::currentChanged, this, [this](int index) { if (auto *btn m_group-button(index)) btn-setChecked(true); // 这不会再次触发 idClicked });为什么setChecked(true)不会造成死循环因为idClicked只在用户点击时发出程序调用setChecked()不会触发clicked。这正是clicked与toggled的区别——如果组信号用的是idToggled上面这段就会形成回环。推荐用idClicked而不是idToggled可以天然避免这种回环。信号触发条件程序setChecked会触发吗clicked/idClicked用户点击❌ 不会toggled/idToggled选中状态变化✅ 会五、样式定制要点QSS 里导航按钮的状态伪类务必都写上否则交互反馈很差伪类触发时机建议:hover鼠标悬停轻微变色:checked当前选中强调色主色:pressed按下瞬间比 hover 再深一点:disabled禁用半透明一条经验导航按钮不要用border-bottom做下划线指示器不同 DPI 下会糊改用border-radius 背景色块。高 DPI 方面Qt5 要在QApplication构造之前设AA_EnableHighDpiScaling和AA_UseHighDpiPixmapsQt6 这两个属性已默认开启且AA_EnableHighDpiScaling被标记废弃再写会有编译警告所以 Qt6 什么都不用做。图标本身推荐用 SVG矢量图或提供2x位图让 Qt 自动挑选。常见坑点坑点 1按钮忘了 setCheckable前面讲过再强调一次因为这是最高频的坑。❌ 错误写法auto *btn new QPushButton(QStringLiteral(首页)); m_group-addButton(btn, 0); // 点击后没有 :checked 状态✅ 正确写法btn-setCheckable(true); m_group-addButton(btn, 0);坑点 2QButtonGroup 的父对象设错导致泄漏QButtonGroup虽不可见但它继承自QObject必须纳入对象树管理。父对象一销毁它跟着销毁按钮的组关系也自动解除。❌ 错误写法auto *group new QButtonGroup; // 没有父对象 → 内存泄漏✅ 正确写法把它挂到导航栏所属的窗口上auto *group new QButtonGroup(this); // this 是导航栏所属的窗口坑点 3信号槽连接失败——编译通过但运行时没反应这是新手最迷惑的问题。Qt5 起推荐用函数指针语法新式语法它能在编译期检查参数匹配// ✅ 编译期检查写错直接编译不过 connect(m_group, QButtonGroup::idClicked, this, MainWindow::onNavClicked);而老式的字符串语法是运行时才报错// ❌ 运行时才失败且只在控制台打印一行警告 connect(m_group, SIGNAL(buttonClicked(int)), this, SLOT(onNavClicked(int)));如果你在 Qt6 里用字符串语法连接buttonClicked(int)会因为信号名已改而连接失败但程序照常运行、只是点了没反应。排查方法看控制台有没有QObject::connect: No such signal ...的输出。坑点 4跨线程更新导航栏导致崩溃导航状态多半是后台任务完成 → 更新角标/切页。工作线程里绝对不能碰 UI。❌ 错误写法void Worker::run() { m_mainWindow-switchToPage(2); // 工作线程直接操作 UI → 崩溃 }✅ 正确写法// Worker 声明信号 signals: void pageSwitchRequested(int index); // Worker::run() 里 emit pageSwitchRequested(2); // 主线程里接收者属于主线程跨线程自动排队 connect(worker, Worker::pageSwitchRequested, this, [this](int idx){ m_group-button(idx)-setChecked(true); m_stack-setCurrentIndex(idx); });补充跨线程时Qt::AutoConnection会自动判定为QueuedConnection但前提是接收者对象上面的this归属主线程。如果你把 lambda 的上下文对象写成了 worker 自己连接类型就会判成直连照样崩。坑点 5图标资源路径写错❌ 错误写法btn-setIcon(QIcon(:/qresource/icons/home.png)); // 多了目录名 btn-setIcon(QIcon(resources/icons/home.png)); // 少了冒号走文件系统✅ 正确写法btn-setIcon(QIcon(QStringLiteral(:/icons/home.png))); // 前缀 : qresource 的 prefix /icons 文件名另外.qrc文件改了之后必须重新构建qmake 需重跑qmakeCMake 用CMAKE_AUTORCC时自动处理否则资源不更新这也是改了图标没变化的常见原因。坑点 6导航栏高度不固定导致内容区跳动setFixedHeight(52)是必要的。如果不设导航栏高度会随其中最高的按钮变化而按钮又可能因字体/图标尺寸变化最终导致内容区上下抖动。给导航栏一个固定高度配合按钮用setFixedHeight布局就稳了。总结导航栏的实现可以拆成四个零件缺一不可零件作用关键 API容器承载按钮QWidgetsetFixedHeight按钮组互斥 id 映射QButtonGroup::setExclusive(true)按钮可选中setCheckable(true)内容区显示对应页面QStackedWidget::setCurrentIndex把它们串起来的是信号槽idClicked驱动setCurrentIndexcurrentChanged反向同步按钮选中。记住idClicked不会被程序触发天然避免回环所以优先用它而不是idToggled。最后提醒两个跨版本差异Qt6 里QButtonGroup的信号统一改成了idClicked/idToggled系列Qt5 的buttonClicked(int)已不存在高 DPI 缩放属性在 Qt6 里默认开启、无需手动设置。把这两点记住Qt5 和 Qt6 的代码就不会互相水土不服。
Qt中导航栏实现的详细指南
前言导航栏Navigation Bar是应用骨架里最显眼的部分用户靠它知道自己在哪、能去哪。一个设计良好的导航栏应该做到三件事——清楚标出当前位置、点击立刻响应、状态永远和内容区一致。Qt 里做导航栏最省事的是QToolBar最好看的是用按钮 QStackedWidget手搓最原生的是用QTabBar或QListWidget当导航项。但不管用哪种核心机制都是同一个一组互斥的按钮当前只有一个被选中驱动一个堆叠内容区。本文会把这个机制讲透QButtonGroup的互斥原理、QStackedWidget的联动、QSS 定制的要点以及实现中最典型的几个坑。一、导航栏的几种形态先做技术选型。按官方组件 vs 自绘排开形态实现方式外观可控性开发成本适用场景工具栏QToolBarQAction中QSS 受限低传统桌面软件、菜单式功能标签栏QTabBar独立使用中低浏览器式顶部标签导航列表导航QListWidget高低侧边栏式导航VSCode 风自绘按钮组QPushButtonQButtonGroup极高中需要图标文字角标等定制本文重点讲最后一种——自绘按钮组因为它是外观问题最多、也最能学到东西的方案其他几种掌握原理后都是它的简化版。QToolBar若只是要个能用的工具栏addToolBar()addAction()两行就够它会自动停靠到QMainWindow顶部但它的样式受QStyle影响很大跨平台表现不一致深度定制比较痛苦这正是很多人转向自绘的原因。二、核心原理互斥按钮组导航栏当前选中项唯一这个约束用QButtonGroup一个属性就能实现auto *group new QButtonGroup(this); group-setExclusive(true); // 关键互斥 group-addButton(btnHome, 0); // 第二个参数是 id group-addButton(btnMsg, 1); group-addButton(btnSet, 2);QButtonGroup本身不是 widget不可见它只是一组按钮的管理器职责有三互斥setExclusive(true)后点一个自动取消其他ID 映射给每个按钮绑一个 int id用idClicked(int)拿到统一信号不用给每个按钮单独连信号只连组的信号即可。这里有个必须提醒的 API 差异信号Qt5Qt6按钮点击带 idbuttonClicked(int)idClicked(int)按钮按下buttonPressed(int)idPressed(int)按钮释放buttonReleased(int)idReleased(int)按钮切换buttonToggled(QAbstractButton*, bool)idToggled(int, bool)Qt6 把传指针的重载去掉了统一改成传 id。Qt5 代码里写QButtonGroup::buttonClickedQt6 会编译不过得换成idClicked。这是 Qt5 迁移到 Qt6 时的高频报错点。按钮必须设 checkable❌ 错误写法auto *btn new QPushButton(QStringLiteral(首页)); group-addButton(btn, 0); // 按钮不可选中互斥机制无从谈起永远看不出当前在哪✅ 正确写法auto *btn new QPushButton(QStringLiteral(首页)); btn-setCheckable(true); // 必须否则不会被 checked btn-setChecked(true); // 默认选中首页 group-addButton(btn, 0);setCheckable(true)是导航按钮和普通按钮的唯一区别。忘了这一句症状是点了没反应、看不出选中状态这是导航栏最经典的坑。三、实战顶部导航 内容区联动实现一个带 QSS 样式的导航栏顶部横向排列点击切换下方内容区。cmake_minimum_required(VERSION 3.16) project(NavbarDemo LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_AUTOMOC ON) set(CMAKE_AUTORCC ON) # 有 .qrc 资源文件时必须 find_package(Qt6 REQUIRED COMPONENTS Widgets) add_executable(NavbarDemo main.cpp mainwindow.cpp mainwindow.h resources.qrc) target_link_libraries(NavbarDemo PRIVATE Qt6::Widgets)qmake 版本QT widgets CONFIG c17 TARGET NavbarDemo SOURCES main.cpp mainwindow.cpp HEADERS mainwindow.h RESOURCES resources.qrc头文件// mainwindow.h #ifndef MAINWINDOW_H #define MAINWINDOW_H #include QWidget class QButtonGroup; class QStackedWidget; class MainWindow : public QWidget { Q_OBJECT public: explicit MainWindow(QWidget *parent nullptr); private: void buildNavBar(); void buildContent(); QWidget *m_navBar nullptr; QButtonGroup *m_group nullptr; QStackedWidget *m_stack nullptr; }; #endif // MAINWINDOW_H实现// mainwindow.cpp #include mainwindow.h #include QButtonGroup #include QPushButton #include QStackedWidget #include QLabel #include QVBoxLayout #include QHBoxLayout #include QDebug namespace { struct NavItem { QString text; QString iconPath; QString pageTip; }; const NavItem kNavItems[] { {QStringLiteral(首页), QStringLiteral(:/icons/home.png), QStringLiteral(欢迎回到首页)}, {QStringLiteral(消息), QStringLiteral(:/icons/msg.png), QStringLiteral(你还没有新消息)}, {QStringLiteral(统计), QStringLiteral(:/icons/chart.png), QStringLiteral(这里是数据统计页)}, {QStringLiteral(设置), QStringLiteral(:/icons/setting.png), QStringLiteral(应用偏好设置)}, }; constexpr int kNavCount int(sizeof(kNavItems) / sizeof(kNavItems[0])); } // namespace MainWindow::MainWindow(QWidget *parent) : QWidget(parent) { setWindowTitle(QStringLiteral(导航栏示例)); resize(860, 560); buildNavBar(); buildContent(); auto *root new QVBoxLayout(this); root-setContentsMargins(0, 0, 0, 0); root-setSpacing(0); root-addWidget(m_navBar); root-addWidget(m_stack, 1); // 默认选中第一项并同步内容区 if (auto *first m_group-button(0)) { first-setChecked(true); m_stack-setCurrentIndex(0); } } void MainWindow::buildNavBar() { m_navBar new QWidget; m_navBar-setObjectName(QStringLiteral(navBar)); m_navBar-setAttribute(Qt::WA_StyledBackground, true); // 让 QSS 背景生效 m_navBar-setFixedHeight(52); // 固定高度防抖动 auto *navLayout new QHBoxLayout(m_navBar); navLayout-setContentsMargins(12, 0, 12, 0); navLayout-setSpacing(4); m_group new QButtonGroup(this); m_group-setExclusive(true); // 互斥保证同时只有一个选中 for (int i 0; i kNavCount; i) { auto *btn new QPushButton(kNavItems[i].text, m_navBar); btn-setCheckable(true); // 关键可选中 btn-setIcon(QIcon(kNavItems[i].iconPath)); btn-setIconSize(QSize(18, 18)); btn-setCursor(Qt::PointingHandCursor); btn-setFixedHeight(34); m_group-addButton(btn, i); // 绑定 id navLayout-addWidget(btn); } navLayout-addStretch(); // 把按钮推到左边 // 只连组的信号不用逐个按钮连接 connect(m_group, QButtonGroup::idClicked, this, [this](int id) { if (id 0 id m_stack-count()) m_stack-setCurrentIndex(id); }); m_navBar-setStyleSheet(R( QWidget#navBar { background-color: #1f2430; border-bottom: 1px solid #2c3346; } QPushButton { color: #b8c0d0; background: transparent; border: none; border-radius: 6px; padding: 0 16px; font-size: 14px; } QPushButton:hover { background-color: #2a3145; color: #ffffff; } QPushButton:checked { background-color: #3d6fff; color: #ffffff; font-weight: bold; } )); } void MainWindow::buildContent() { m_stack new QStackedWidget; for (int i 0; i kNavCount; i) { auto *page new QWidget; auto *label new QLabel(kNavItems[i].pageTip, page); label-setAlignment(Qt::AlignCenter); label-setStyleSheet(QStringLiteral(font-size:20px;color:#666;)); auto *layout new QVBoxLayout(page); layout-addWidget(label); m_stack-addWidget(page); } }入口// main.cpp #include mainwindow.h #include QApplication int main(int argc, char *argv[]) { QApplication app(argc, argv); MainWindow w; w.show(); return app.exec(); }资源文件resources.qrc里用qresource prefix/icons声明前缀代码里就写:/icons/home.png。注意:是资源系统前缀/icons是 qresource 的 prefix不要写成:/qresource/icons/...那是目录名不是 prefix。四、进阶让导航栏和内容区双向同步上面是单向的点按钮 → 切页面。但内容区也可能主动切页比如设置页里点按钮跳到关于页这时按钮选中状态必须跟着变。❌ 错误写法只连了单向connect(m_group, QButtonGroup::idClicked, m_stack, QStackedWidget::setCurrentIndex); // 内容区自己 setCurrentIndex 时按钮状态不会更新✅ 正确写法回连currentChanged// 反向内容区变了 → 同步按钮选中状态 connect(m_stack, QStackedWidget::currentChanged, this, [this](int index) { if (auto *btn m_group-button(index)) btn-setChecked(true); // 这不会再次触发 idClicked });为什么setChecked(true)不会造成死循环因为idClicked只在用户点击时发出程序调用setChecked()不会触发clicked。这正是clicked与toggled的区别——如果组信号用的是idToggled上面这段就会形成回环。推荐用idClicked而不是idToggled可以天然避免这种回环。信号触发条件程序setChecked会触发吗clicked/idClicked用户点击❌ 不会toggled/idToggled选中状态变化✅ 会五、样式定制要点QSS 里导航按钮的状态伪类务必都写上否则交互反馈很差伪类触发时机建议:hover鼠标悬停轻微变色:checked当前选中强调色主色:pressed按下瞬间比 hover 再深一点:disabled禁用半透明一条经验导航按钮不要用border-bottom做下划线指示器不同 DPI 下会糊改用border-radius 背景色块。高 DPI 方面Qt5 要在QApplication构造之前设AA_EnableHighDpiScaling和AA_UseHighDpiPixmapsQt6 这两个属性已默认开启且AA_EnableHighDpiScaling被标记废弃再写会有编译警告所以 Qt6 什么都不用做。图标本身推荐用 SVG矢量图或提供2x位图让 Qt 自动挑选。常见坑点坑点 1按钮忘了 setCheckable前面讲过再强调一次因为这是最高频的坑。❌ 错误写法auto *btn new QPushButton(QStringLiteral(首页)); m_group-addButton(btn, 0); // 点击后没有 :checked 状态✅ 正确写法btn-setCheckable(true); m_group-addButton(btn, 0);坑点 2QButtonGroup 的父对象设错导致泄漏QButtonGroup虽不可见但它继承自QObject必须纳入对象树管理。父对象一销毁它跟着销毁按钮的组关系也自动解除。❌ 错误写法auto *group new QButtonGroup; // 没有父对象 → 内存泄漏✅ 正确写法把它挂到导航栏所属的窗口上auto *group new QButtonGroup(this); // this 是导航栏所属的窗口坑点 3信号槽连接失败——编译通过但运行时没反应这是新手最迷惑的问题。Qt5 起推荐用函数指针语法新式语法它能在编译期检查参数匹配// ✅ 编译期检查写错直接编译不过 connect(m_group, QButtonGroup::idClicked, this, MainWindow::onNavClicked);而老式的字符串语法是运行时才报错// ❌ 运行时才失败且只在控制台打印一行警告 connect(m_group, SIGNAL(buttonClicked(int)), this, SLOT(onNavClicked(int)));如果你在 Qt6 里用字符串语法连接buttonClicked(int)会因为信号名已改而连接失败但程序照常运行、只是点了没反应。排查方法看控制台有没有QObject::connect: No such signal ...的输出。坑点 4跨线程更新导航栏导致崩溃导航状态多半是后台任务完成 → 更新角标/切页。工作线程里绝对不能碰 UI。❌ 错误写法void Worker::run() { m_mainWindow-switchToPage(2); // 工作线程直接操作 UI → 崩溃 }✅ 正确写法// Worker 声明信号 signals: void pageSwitchRequested(int index); // Worker::run() 里 emit pageSwitchRequested(2); // 主线程里接收者属于主线程跨线程自动排队 connect(worker, Worker::pageSwitchRequested, this, [this](int idx){ m_group-button(idx)-setChecked(true); m_stack-setCurrentIndex(idx); });补充跨线程时Qt::AutoConnection会自动判定为QueuedConnection但前提是接收者对象上面的this归属主线程。如果你把 lambda 的上下文对象写成了 worker 自己连接类型就会判成直连照样崩。坑点 5图标资源路径写错❌ 错误写法btn-setIcon(QIcon(:/qresource/icons/home.png)); // 多了目录名 btn-setIcon(QIcon(resources/icons/home.png)); // 少了冒号走文件系统✅ 正确写法btn-setIcon(QIcon(QStringLiteral(:/icons/home.png))); // 前缀 : qresource 的 prefix /icons 文件名另外.qrc文件改了之后必须重新构建qmake 需重跑qmakeCMake 用CMAKE_AUTORCC时自动处理否则资源不更新这也是改了图标没变化的常见原因。坑点 6导航栏高度不固定导致内容区跳动setFixedHeight(52)是必要的。如果不设导航栏高度会随其中最高的按钮变化而按钮又可能因字体/图标尺寸变化最终导致内容区上下抖动。给导航栏一个固定高度配合按钮用setFixedHeight布局就稳了。总结导航栏的实现可以拆成四个零件缺一不可零件作用关键 API容器承载按钮QWidgetsetFixedHeight按钮组互斥 id 映射QButtonGroup::setExclusive(true)按钮可选中setCheckable(true)内容区显示对应页面QStackedWidget::setCurrentIndex把它们串起来的是信号槽idClicked驱动setCurrentIndexcurrentChanged反向同步按钮选中。记住idClicked不会被程序触发天然避免回环所以优先用它而不是idToggled。最后提醒两个跨版本差异Qt6 里QButtonGroup的信号统一改成了idClicked/idToggled系列Qt5 的buttonClicked(int)已不存在高 DPI 缩放属性在 Qt6 里默认开启、无需手动设置。把这两点记住Qt5 和 Qt6 的代码就不会互相水土不服。