如何为无标签页的QTabWidget设置背景占位Widget？

核心思路 #

通过一个占位Widget覆盖QTabWidget的内容区域，监听标签页数量变化来控制其显示/隐藏，同时通过属性设置让它不响应任何用户事件。

具体实现步骤 #

1. 创建并配置占位Widget

• 基于QWidget或QLabel创建占位控件，添加提示文本（比如“请打开标签页”），用布局让文本居中显示。
• 将该Widget设置为QTabWidget的子控件，初始时覆盖QTabWidget的内容区域（通过setGeometry(tabWidget->contentsRect())实现）。
• 设置两个关键属性，让它不处理用户事件：
  • setAttribute(Qt::WA_TransparentForMouseEvents)：鼠标事件完全穿透到下层的QTabWidget，不响应点击、双击等操作。
  • setFocusPolicy(Qt::NoFocus)：禁止获取键盘焦点，不处理任何键盘事件。

2. 监听标签页数量变化，控制占位Widget显示

有两种实现方式，根据Qt版本选择：

• Qt 5.10及以上版本：直接监听QTabBar的countChanged信号，当标签页数量为0时显示占位Widget，大于0时隐藏：

  connect(tabWidget->tabBar(), &QTabBar::countChanged, this, [=](int count) {
      placeholderWidget->setVisible(count == 0);
  });
  

• 旧版本Qt：重写QTabWidget的tabInserted和tabRemoved方法，每次标签页添加/移除后判断数量，更新占位Widget的显示状态：

  class CustomTabWidget : public QTabWidget
  {
      Q_OBJECT
  protected:
      void tabInserted(int index) override {
          QTabWidget::tabInserted(index);
          updatePlaceholder();
      }
      void tabRemoved(int index) override {
          QTabWidget::tabRemoved(index);
          updatePlaceholder();
      }
  private:
      QWidget* m_placeholder;
      void updatePlaceholder() {
          if (m_placeholder) {
              m_placeholder->setVisible(count() == 0);
          }
      }
  };
  

3. 适配QTabWidget大小变化

当QTabWidget窗口大小改变时，需要同步调整占位Widget的尺寸，避免出现错位：

connect(tabWidget, &QTabWidget::resized, this, [=]() {
    placeholderWidget->setGeometry(tabWidget->contentsRect());
});

关键注意点 #

• 占位Widget必须是QTabWidget的直接子控件，确保它能覆盖内容区域且层级正确。
• 不需要给占位Widget设置父布局，直接通过setGeometry控制位置和大小，避免干扰QTabWidget自身的布局逻辑。

内容的提问来源于stack exchange，提问作者MartinZ