Qt QStackedWidget 总结

Qt QStackedWidget 总结

概述

QStackedWidget 是 Qt 中的一个容器控件，用于管理多个子界面（页面），但一次只显示一个。类似于标签页，但隐藏了切换标签的 UI，需手动控制页面切换逻辑。常用于向导界面、分步表单、动态布局切换等场景。

---

核心特性

1. 多页面管理

   • 可添加多个 QWidget 作为子页面。
   • 通过索引（index）或指针（QWidget*）访问页面。

2. 当前页面控制

   • 通过 setCurrentIndex(int) 或 setCurrentWidget(QWidget*) 切换页面。
   • 当前页面变化时触发 currentChanged(int) 信号。

3. 动态增删页面

   • 支持运行时动态添加（addWidget()）、插入（insertWidget()）或移除（removeWidget()）页面。

4. 轻量级无动画

   • 默认无切换动画，需结合 QPropertyAnimation 等实现滑动、淡入淡出效果。

---

常用方法

方法	作用
addWidget(QWidget*)	添加页面，返回索引
insertWidget(int index, QWidget*)	在指定位置插入页面
removeWidget(QWidget*)	移除页面（不删除对象）
currentWidget() const	获取当前显示的页面指针
currentIndex() const	获取当前页面的索引
setCurrentIndex(int)	通过索引切换页面
setCurrentWidget(QWidget*)	通过指针切换页面
widget(int index) const	根据索引获取页面指针
count() const	获取页面总数

---

信号

• currentChanged(int index)
  当当前页面切换时触发，参数为新页面的索引。

---

基本使用示例

// 创建 QStackedWidget 实例
QStackedWidget *stackedWidget = new QStackedWidget;

// 添加页面
QWidget *page1 = new QWidget;
QWidget *page2 = new QWidget;
stackedWidget->addWidget(page1); // index 0
stackedWidget->addWidget(page2); // index 1

// 切换页面
stackedWidget->setCurrentIndex(1); // 显示 page2

// 连接信号：页面切换时打印索引
connect(stackedWidget, &QStackedWidget::currentChanged, [](int index) {
    qDebug() << "当前页面索引：" << index;
});

---

进阶用法

1. 结合按钮切换页面
通过按钮点击事件切换页面：

QPushButton *btnNext = new QPushButton("下一页");
connect(btnNext, &QPushButton::clicked, [stackedWidget]() {
    int nextIndex = stackedWidget->currentIndex() + 1;
    if (nextIndex < stackedWidget->count()) {
        stackedWidget->setCurrentIndex(nextIndex);
    }
});

2. 动态添加/移除页面

// 动态添加新页面
QWidget *newPage = new QWidget;
int newIndex = stackedWidget->addWidget(newPage);

// 动态移除页面（需确保页面不再使用）
stackedWidget->removeWidget(page1);
// 注意：removeWidget() 不会删除页面对象，需手动 delete 避免内存泄漏
delete page1;

3. 自定义切换动画
使用 QPropertyAnimation 实现滑动效果：

// 假设 stackedWidget 的父窗口是 QMainWindow
QPropertyAnimation *animation = new QPropertyAnimation(stackedWidget, "pos");
animation->setDuration(300);
animation->setStartValue(QPoint(0, 0));
animation->setEndValue(QPoint(-stackedWidget->width(), 0));
animation->start();

// 动画结束后切换页面并复位位置
connect(animation, &QPropertyAnimation::finished, [=]() {
    stackedWidget->setCurrentIndex(1);
    stackedWidget->move(0, 0);
});

---

注意事项

1. 内存管理
   removeWidget() 仅将页面从容器移除，不会删除对象。若页面不再使用，需手动 delete。

2. 性能优化
   页面较多时，频繁切换可能导致内存占用高。可结合 QLazyLoading 或按需初始化页面内容。

3. 与 QTabWidget 的区别
   QTabWidget 内部使用 QStackedWidget，但自带标签栏。若需隐藏标签，使用 QStackedWidget 更灵活。

4. 设计模式
   建议将页面切换逻辑封装在独立的类（如控制器）中，避免 UI 代码臃肿。

---

适用场景

• 向导式对话框（如安装程序）。
• 设置界面中的分类配置页。
• 根据用户权限动态显示不同功能模块。
• 需要无标签栏的多页面切换。