在 Qt Creator 中使用 Promote 功能让 QTabWidget 显示自定义页面

 

💡 在 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

1. 打开 Qt Creator，选择 File → New Project → Qt Widgets Application；

2. 命名为 MyProject；

3. 创建完成后会自动生成 mainwindow.h / .cpp / .ui 三个文件。

---

✳️ 步骤 2：在主窗口中添加 QTabWidget

1. 打开 mainwindow.ui；

2. 从左侧 Widget Box 中拖入一个 QTabWidget；

3. 现在你会看到默认有两个标签页（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 的每个标签页显示你的自定义页面。

1. 打开 mainwindow.ui；

2. 点击第一个标签页中的 QWidget；

3. 右键 → 选择 Promote to...（提升为...）

4. 在弹出的窗口中填写：

   • 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 界面开发中非常实用的一项技巧，尤其是在大型项目中管理多个页面时。