Qt QStackedWidget 总结

概述

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

核心特性

多页面管理
- 可添加多个 QWidget 作为子页面。
- 通过索引（index）或指针（QWidget*）访问页面。
当前页面控制
- 通过 setCurrentIndex(int) 或 setCurrentWidget(QWidget*) 切换页面。
- 当前页面变化时触发 currentChanged(int) 信号。
动态增删页面
- 支持运行时动态添加（addWidget()）、插入（insertWidget()）或移除（removeWidget()）页面。
轻量级无动画
- 默认无切换动画，需结合 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)
当当前页面切换时触发，参数为新页面的索引。

基本使用示例

cpp 复制代码

// 创建 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. 结合按钮切换页面

通过按钮点击事件切换页面：

cpp 复制代码

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

2. 动态添加/移除页面

cpp 复制代码

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

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

3. 自定义切换动画

使用 QPropertyAnimation 实现滑动效果：

cpp 复制代码

// 假设 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);
});

注意事项

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

页面较多时，频繁切换可能导致内存占用高。可结合 QLazyLoading 或按需初始化页面内容。
与 QTabWidget 的区别
QTabWidget 内部使用 QStackedWidget，但自带标签栏。若需隐藏标签，使用 QStackedWidget 更灵活。
设计模式

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

适用场景

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