💡 在 Qt Creator 中使用 Promote 功能让 QTabWidget 显示自定义页面
在使用 Qt Creator 开发界面时，我们经常需要在 QTabWidget（标签页控件）中显示自己设计的自定义页面，而不是简单的 QWidget。
本篇教程将详细讲解如何通过 Promote（提升） 功能，让 QTabWidget 的每个标签页使用你自己的类。
🧩 项目结构示例
最终项目结构如下：
MyProject/
├── main.cpp
├── mainwindow.h
├── mainwindow.cpp
├── mainwindow.ui
├── tabpage1.h
├── tabpage1.cpp
├── tabpage1.ui
├── tabpage2.h
├── tabpage2.cpp
└── tabpage2.ui
✳️ 步骤 1：创建主窗口 MainWindow
-
打开 Qt Creator，选择 File → New Project → Qt Widgets Application；
-
命名为
MyProject； -
创建完成后会自动生成
mainwindow.h / .cpp / .ui三个文件。
✳️ 步骤 2：在主窗口中添加 QTabWidget
-
打开
mainwindow.ui； -
从左侧 Widget Box 中拖入一个 QTabWidget；
-
现在你会看到默认有两个标签页（
tab和tab_2），每页里是一个普通的QWidget。
✳️ 步骤 3：创建两个自定义页面类
接下来我们要创建两个页面类：TabPage1 和 TabPage2。
在 Qt Creator 中：
-
选择 File → New File or Project → Qt Designer Form Class
-
分别命名为
TabPage1和TabPage2 -
基类选择
QWidget
📄 tabpage1.h
#pragma once
#include <QWidget>namespace Ui {
class TabPage1;
}class TabPage1 : public QWidget {Q_OBJECT
public:explicit TabPage1(QWidget *parent = nullptr);~TabPage1();private:Ui::TabPage1 *ui;
};
📄 tabpage1.cpp
#include "tabpage1.h"
#include "ui_tabpage1.h"TabPage1::TabPage1(QWidget *parent): QWidget(parent), ui(new Ui::TabPage1) {ui->setupUi(this);
}TabPage1::~TabPage1() {delete ui;
}
打开 tabpage1.ui，可以随意放一个标签（QLabel）并设置文本为：
这是第一页（TabPage1）
📄 tabpage2.h
#pragma once
#include <QWidget>namespace Ui {
class TabPage2;
}class TabPage2 : public QWidget {Q_OBJECT
public:explicit TabPage2(QWidget *parent = nullptr);~TabPage2();private:Ui::TabPage2 *ui;
};
📄 tabpage2.cpp
#include "tabpage2.h"
#include "ui_tabpage2.h"TabPage2::TabPage2(QWidget *parent): QWidget(parent), ui(new Ui::TabPage2) {ui->setupUi(this);
}TabPage2::~TabPage2() {delete ui;
}
同样，在 tabpage2.ui 中放一个标签：
这是第二页（TabPage2）
✳️ 步骤 4：在 mainwindow.ui 中使用 Promote 功能
现在让 QTabWidget 的每个标签页显示你的自定义页面。
-
打开
mainwindow.ui； -
点击第一个标签页中的
QWidget； -
右键 → 选择 Promote to...（提升为...）
-
在弹出的窗口中填写：
-
Promoted class name:
TabPage1 -
Header file:
tabpage1.h -
点击 Add → Promote
-
对第二个标签页重复同样的操作：
-
Promoted class name:
TabPage2 -
Header file:
tabpage2.h
保存 .ui 文件。
✳️ 步骤 5：编写 main.cpp
#include "mainwindow.h"
#include <QApplication>int main(int argc, char *argv[])
{QApplication a(argc, argv);MainWindow w;w.show();return a.exec();
}
✅ 运行结果
运行项目后，主窗口中将显示一个 QTabWidget，包含两个标签页：
-
第一页：显示
TabPage1的内容 -
第二页：显示
TabPage2的内容
每个页面都可以独立设计自己的 UI，互不干扰，非常适合复杂界面模块化。
🧠 补充说明
-
“Promote” 功能只影响 Qt Designer 层面，不会修改
.cpp代码； -
适用于任何继承自
QWidget、QFrame、QDialog等的自定义类； -
这样做可以保持
.ui文件的整洁，同时实现强大的可复用性。
📊 示意图
MainWindow└── QTabWidget├── Tab 1 → TabPage1 (自定义 QWidget)└── Tab 2 → TabPage2 (自定义 QWidget)
🏁 总结
通过 Promote（提升） 功能：
-
你可以在 Qt Designer 中将普通控件替换成自己的类；
-
让界面更模块化、代码更清晰；
-
无需手动修改
.ui生成的代码。
这是 Qt 界面开发中非常实用的一项技巧，尤其是在大型项目中管理多个页面时。