Back to Qt.io
Contact Us Blog Download Qt

QTabWidget Class

QTabWidget 类提供了一个标签式 widget 堆栈。更多

Header： #include <QTabWidget>
CMake： find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake： QT += widgets
继承： QWidget

公共类型

enum TabPosition { North, South, West, East }
enum TabShape { Rounded, Triangular }

属性

公共函数

QTabWidget(QWidget *parent = nullptr)
virtual ~QTabWidget()
int addTab(QWidget *page, const QString &label)
int addTab(QWidget *page, const QIcon &icon, const QString &label)
void clear()
QWidget *cornerWidget(Qt::Corner corner = Qt::TopRightCorner) const
int count() const
int currentIndex() const
QWidget *currentWidget() const
bool documentMode() const
Qt::TextElideMode elideMode() const
QSize iconSize() const
int indexOf(const QWidget *w) const
int insertTab(int index, QWidget *page, const QString &label)
int insertTab(int index, QWidget *page, const QIcon &icon, const QString &label)
bool isMovable() const
bool isTabEnabled(int index) const
bool isTabVisible(int index) const
void removeTab(int index)
void setCornerWidget(QWidget *widget, Qt::Corner corner = Qt::TopRightCorner)
void setDocumentMode(bool set)
void setElideMode(Qt::TextElideMode mode)
void setIconSize(const QSize &size)
void setMovable(bool movable)
void setTabBarAutoHide(bool enabled)
void setTabEnabled(int index, bool enable)
void setTabIcon(int index, const QIcon &icon)
void setTabPosition(QTabWidget::TabPosition position)
void setTabShape(QTabWidget::TabShape s)
void setTabText(int index, const QString &label)
void setTabToolTip(int index, const QString &tip)
void setTabVisible(int index, bool visible)
void setTabWhatsThis(int index, const QString &text)
void setTabsClosable(bool closeable)
void setUsesScrollButtons(bool useButtons)
QTabBar *tabBar() const
bool tabBarAutoHide() const
QIcon tabIcon(int index) const
QTabWidget::TabPosition tabPosition() const
QTabWidget::TabShape tabShape() const
QString tabText(int index) const
QString tabToolTip(int index) const
QString tabWhatsThis(int index) const
bool tabsClosable() const
bool usesScrollButtons() const
QWidget *widget(int index) const

重新实现的公共函数

virtual bool hasHeightForWidth() const override
virtual int heightForWidth(int width) const override
virtual QSize minimumSizeHint() const override
virtual QSize sizeHint() const override

公共插槽

void setCurrentIndex(int index)
void setCurrentWidget(QWidget *widget)

信号

void currentChanged(int index)
void tabBarClicked(int index)
void tabBarDoubleClicked(int index)
void tabCloseRequested(int index)

受保护函数

virtual void initStyleOption(QStyleOptionTabWidgetFrame *option) const
void setTabBar(QTabBar *tb)
virtual void tabInserted(int index)
virtual void tabRemoved(int index)

重新实现的受保护函数

virtual void changeEvent(QEvent *ev) override
virtual bool event(QEvent *ev) override
virtual void keyPressEvent(QKeyEvent *e) override
virtual void paintEvent(QPaintEvent *event) override
virtual void resizeEvent(QResizeEvent *e) override
virtual void showEvent(QShowEvent *) override

详细说明

标签 Widget 提供一个标签栏（参见QTabBar ）和一个 "页面区域"，用于显示与每个标签相关的页面。默认情况下，标签栏显示在页面区域上方，但也有不同的配置（参见TabPosition ）。每个选项卡都与不同的部件（称为页面）相关联。页面区域只显示当前页面，所有其他页面都是隐藏的。用户可以通过点击标签页或按Alt+字母快捷键（如果有的话）来显示不同的页面。

使用 QTabWidget 的常规方法如下：

  1. 创建一个 QTabWidget。
  2. 为标签对话框中的每个页面创建一个QWidget ，但不要为它们指定父窗口部件。
  3. 将子窗口部件插入页面窗口部件，使用布局将其正常定位。
  4. 调用addTab() 或insertTab() 将页面部件放入选项卡部件中，为每个选项卡添加一个合适的标签，并可选择键盘快捷键。

标签的位置由tabPosition 定义，形状由tabShape 定义。

当用户选择一个页面时，将发出currentChanged() 信号。

当前页面索引可通过currentIndex() 获得，当前页面部件可通过currentWidget() 获得。使用widget() 可以获取指向给定索引的页面部件的指针，使用indexOf() 可以查找部件的索引位置。使用setCurrentWidget() 或setCurrentIndex() 可以显示特定页面。

使用setTabText() 或setTabIcon() 可以更改标签页的文本和图标。可以使用removeTab() 删除标签页及其相关页面。

每个标签页在任何时候都可以启用或禁用（请参阅setTabEnabled() ）。如果启用了选项卡，则会正常绘制选项卡文本，用户可以选择该选项卡。如果禁用，则以另一种方式绘制制表符，用户无法选择该制表符。需要注意的是，即使禁用了标签，页面仍然是可见的，例如，如果所有标签都被禁用了。

标签部件是分割复杂对话框的好方法。另一种方法是使用QStackedWidget ，为其提供一些在页面间导航的方法，例如QToolBar 或QListWidget 。

QTabWidget 的大部分功能由QTabBar （位于顶部，提供标签）和QStackedWidget （大部分区域，组织各个页面）提供。

另请参阅 QTabBar,QStackedWidget,QToolBox 和标签对话框示例。

成员类型文档

enum QTabWidget::TabPosition

该枚举类型定义QTabWidget 在何处绘制制表符行：

常量值说明
QTabWidget::North0标签绘制在页面上方。
QTabWidget::South1选项卡绘制在页面下方。
QTabWidget::West2选项卡绘制在页面左侧。
QTabWidget::East3选项卡绘制在页面右侧。

enum QTabWidget::TabShape

该枚举类型定义了制表符的形状：

常量值描述
QTabWidget::Rounded0绘制的标签为圆形。这是默认形状。
QTabWidget::Triangular1绘制的标签为三角形。

属性文档

[read-only] count : const int

该属性用于保存标签栏中标签的数量

默认情况下，此属性的值为 0。

访问功能：

int count() const

currentIndex : int

该属性保存当前标签页的索引位置。

如果没有当前 widget，则当前索引为-1。

默认情况下，该属性的值为-1，因为该 widget 中最初没有标签页。

访问函数：

int currentIndex() const
void setCurrentIndex(int index)

通知信号：

void currentChanged(int index)

documentMode : bool

此属性表示标签 Widget 是否以适合文档页面的模式呈现。这与 macOS 上的文档模式相同。

设置该属性后，将不呈现选项卡 widget 框架。该模式适用于显示文档类型的页面，在这种情况下，页面会覆盖大部分标签 Widget 区域。

访问功能：

bool documentMode() const
void setDocumentMode(bool set)

另请参阅 elideMode,QTabBar::documentMode,QTabBar::usesScrollButtons 和QStyle::SH_TabBar_PreferNoArrows 。

elideMode : Qt::TextElideMode

如何在标签栏中隐藏文本

该属性可控制在给定的标签栏尺寸下，如果没有足够的空间显示项目，则如何将其隐藏。

默认情况下，该值取决于样式。

访问功能：

Qt::TextElideMode elideMode() const
void setElideMode(Qt::TextElideMode mode)

另请参阅 QTabBar::elideMode,usesScrollButtons, 和QStyle::SH_TabBar_ElideMode 。

iconSize : QSize

此属性用于保存标签栏中图标的大小

默认值取决于样式。这是图标的最大尺寸。如果图标尺寸较小，则不会按比例放大。

访问功能：

QSize iconSize() const
void setIconSize(const QSize &size)

另请参阅 QTabBar::iconSize 。

movable : bool

该属性表示用户是否可以在标签栏区域内移动标签。

默认情况下，该属性为false ；

访问功能：

bool isMovable() const
void setMovable(bool movable)

tabBarAutoHide : bool

如果为 "true"，当标签栏包含的标签少于 2 个时，标签栏会自动隐藏。

默认情况下，此属性为假。

访问功能：

bool tabBarAutoHide() const
void setTabBarAutoHide(bool enabled)

另请参阅 QWidget::visible 。

tabPosition : TabPosition

该属性用于保存标签在该标签 Widget 中的位置。

TabPosition 枚举描述了该属性的可能值。

默认情况下，此属性设置为North 。

访问功能：

QTabWidget::TabPosition tabPosition() const
void setTabPosition(QTabWidget::TabPosition position)

另请参阅 TabPosition 。

tabShape : TabShape

此属性用于保存此选项卡 widget 中选项卡的形状。

该属性的可能值为QTabWidget::Rounded （默认值）或QTabWidget::Triangular 。

访问功能：

QTabWidget::TabShape tabShape() const
void setTabShape(QTabWidget::TabShape s)

另请参阅 TabShape 。

tabsClosable : bool

该属性用于确定是否为每个标签页自动添加关闭按钮。

访问功能：

bool tabsClosable() const
void setTabsClosable(bool closeable)

另请参阅 QTabBar::tabsClosable().

usesScrollButtons : bool

当标签栏中有很多标签页时，该属性将决定标签栏是否应使用按钮来滚动标签页。

当标签栏中的标签过多时，标签栏可以选择扩大尺寸或添加按钮来滚动标签。

默认情况下，该值取决于样式。

访问功能：

bool usesScrollButtons() const
void setUsesScrollButtons(bool useButtons)

另请参阅 elideMode,QTabBar::usesScrollButtons, 和QStyle::SH_TabBar_PreferNoArrows 。

成员函数文档

[explicit] QTabWidget::QTabWidget(QWidget *parent = nullptr)

通过父parent 构建一个标签式 widget。

[virtual noexcept] QTabWidget::~QTabWidget()

销毁标签式 widget。

int QTabWidget::addTab(QWidget *page, const QString &label)

将带有给定page 和label 的标签页添加到标签 widget，并返回标签栏中标签页的索引。page 的所有权将传递给QTabWidget 。

如果标签页的label 含有逗号，则逗号后面的字母将用作标签页的快捷方式，例如，如果标签页的标签为 "Bro&wse"，则 Alt+W 将成为快捷方式，将焦点移至该标签页。

注意： 如果在show() 之后调用 addTab()，布局系统将尝试调整以适应窗口部件层次结构的变化，并可能导致闪烁。为避免这种情况，可以在更改之前将QWidget::updatesEnabled 属性设置为 false；切记在更改完成后将该属性设置为 true，使窗口部件再次接收绘制事件。

另请参阅 insertTab().

int QTabWidget::addTab(QWidget *page, const QIcon &icon, const QString &label)

这是一个重载函数。

使用给定的page 、icon 和label 向标签部件添加标签，并返回标签栏中标签的索引。page 的所有权将传递给QTabWidget 。

该函数与 addTab() 相同，但多了一个icon 。

[override virtual protected] void QTabWidget::changeEvent(QEvent *ev)

重实现：QWidget::changeEvent(QEvent *event).

void QTabWidget::clear()

删除所有页面，但不删除它们。调用该函数等同于调用removeTab() 直到标签部件为空。

QWidget *QTabWidget::cornerWidget(Qt::Corner corner = Qt::TopRightCorner) const

返回显示在corner 标签部件或nullptr 中的部件。

另请参阅 setCornerWidget()。

[signal] void QTabWidget::currentChanged(int index)

每当当前页面索引发生变化时，就会发出该信号。参数是当前页面index 的新位置，如果没有新位置，则为-1（例如，如果QTabWidget 中没有小部件）。

注： 属性currentIndex 的通知信号。

另请参阅 currentWidget() 和currentIndex 。

QWidget *QTabWidget::currentWidget() const

返回标签对话框当前显示页面的指针。选项卡对话框会尽力确保该值永远不会为 0（但如果您足够努力，也有可能为 0）。

另请参阅 currentIndex() 和setCurrentWidget()。

[override virtual protected] bool QTabWidget::event(QEvent *ev)

重实现：QWidget::event(QEvent *event).

[override virtual] bool QTabWidget::hasHeightForWidth() const

重实现：QWidget::hasHeightForWidth() const.

[override virtual] int QTabWidget::heightForWidth(int width) const

重实现：QWidget::heightForWidth(int w) const.

int QTabWidget::indexOf(const QWidget *w) const

返回 widgetw 所占页面的索引位置，如果找不到该 widget，则返回-1。

[virtual protected] void QTabWidget::initStyleOption(QStyleOptionTabWidgetFrame *option) const

使用此QTabWidget 中的值初始化option 。当子类需要QStyleOptionTabWidgetFrame ，但又不想自己填写所有信息时，该方法非常有用。

另请参阅 QStyleOption::initFrom() 和QTabBar::initStyleOption()。

int QTabWidget::insertTab(int index, QWidget *page, const QString &label)

使用给定的label 和page 在指定的index 处的标签部件中插入标签，并返回已插入标签在标签栏中的索引。page 的所有权将传递给QTabWidget 。

标签显示在标签页中，其外观可能因标签页 widget 的配置而异。

如果标签页的label 包含一个逗号，逗号后面的字母将用作该标签页的快捷方式，例如，如果标签为 "Bro&wse"，则 Alt+W 将成为快捷方式，将焦点移至该标签页。

如果index 不在范围内，则会直接附加标签页。否则就会在指定位置插入。

如果QTabWidget 在调用此函数前为空，则新页面将成为当前页面。如果在小于或等于当前索引的位置插入新制表符，则会递增当前索引，但保留当前页面。

注意： 如果在show() 之后调用 insertTab()，布局系统将尝试调整以适应其部件层次结构的变化，并可能导致闪烁。为避免这种情况，可以在更改之前将QWidget::updatesEnabled 属性设置为 false；切记在更改完成后将该属性设置为 true，使窗口部件再次接收绘制事件。

另请参阅 addTab().

int QTabWidget::insertTab(int index, QWidget *page, const QIcon &icon, const QString &label)

这是一个重载函数。

使用给定的label 、page 和icon 在指定的index 处的标签部件中插入标签，并返回插入标签在标签栏中的索引。page 的所有权将传递给QTabWidget 。

该函数与 insertTab() 相同，但多了一个icon 。

bool QTabWidget::isTabEnabled(int index) const

如果位置index 上的页面已启用，则返回true ；否则返回false 。

另请参阅 setTabEnabled() 和QWidget::isEnabled()。

bool QTabWidget::isTabVisible(int index) const

如果index 位置的页面可见，则返回 true；否则返回 false。

另请参阅 setTabVisible().

[override virtual protected] void QTabWidget::keyPressEvent(QKeyEvent *e)

重实现：QWidget::keyPressEvent(QKeyEvent *event).

[override virtual] QSize QTabWidget::minimumSizeHint() const

重新实现属性：QWidget::minimumSizeHint 的访问函数。

返回标签 Widget 的合适最小尺寸。

[override virtual protected] void QTabWidget::paintEvent(QPaintEvent *event)

重实现：QWidget::paintEvent(QPaintEvent *event).

响应 paintevent ，绘制标签 Widget 的标签栏。

void QTabWidget::removeTab(int index)

从窗口部件堆栈中删除位于index 位置的标签页。页面部件本身不会被删除。

另请参阅 addTab() 和insertTab()。

[override virtual protected] void QTabWidget::resizeEvent(QResizeEvent *e)

重实现：QWidget::resizeEvent(QResizeEvent *event).

void QTabWidget::setCornerWidget(QWidget *widget, Qt::Corner corner = Qt::TopRightCorner)

设置给定的widget ，使其显示在标签 Widget 的指定corner 中。窗口小部件的几何形状是根据窗口小部件的sizeHint() 和style() 确定的。

只使用corner 的水平元素。

传递nullptr 时，角落里不会显示任何部件。

之前设置的任何角落部件都将被隐藏。

此处设置的所有部件都将在标签部件销毁时被删除，除非您在设置其他角落部件（或nullptr ）后单独重新指定该部件。

注意：边角部件是为North 和South 标签位置设计的；其他方向的部件可能无法正常工作。

另请参阅 cornerWidget() 和setTabPosition()。

[slot] void QTabWidget::setCurrentWidget(QWidget *widget)

使widget 成为当前 widget。所使用的widget 必须是此标签 Widget 中的一个页面。

另请参阅 addTab()、setCurrentIndex() 和currentWidget()。

[protected] void QTabWidget::setTabBar(QTabBar *tb)

用选项卡栏tb 替换对话框的QTabBar 标题。请注意，必须在添加任何选项卡之前调用此操作，否则行为将是未定义的。

另请参阅 tabBar()。

void QTabWidget::setTabEnabled(int index, bool enable)

如果enable 为 true，位于index 位置的页面将被启用；否则，位于index 位置的页面将被禁用。页面的标签页将适当重绘。

QTabWidget 内部使用 () 而不是保留一个单独的标记。QWidget::setEnabled

请注意，即使禁用的标签页/页面也可能是可见的。如果页面已经可见，QTabWidget 将不会隐藏它；如果所有页面都被禁用，QTabWidget 将显示其中一个页面。

另请参见 isTabEnabled() 和QWidget::setEnabled()。

void QTabWidget::setTabIcon(int index, const QIcon &icon)

为位置index 的制表符设置icon 。

另请参阅 tabIcon() 。

void QTabWidget::setTabText(int index, const QString &label)

为index's 标签位置的页面定义一个新的label 。

如果提供的文本中包含"&"字符，则会自动为其创建快捷键。&"后面的字符将被用作快捷键。之前的快捷键将被覆盖，如果文本没有定义快捷键，则会被清除。有关详细信息，请参阅QShortcut 文档（要显示实际的"&&"，请使用"&&"）。

另请参见 tabText().

void QTabWidget::setTabToolTip(int index, const QString &tip)

将位置index 的页面的制表符工具提示设置为tip 。

另请参阅 tabToolTip() 。

void QTabWidget::setTabVisible(int index, bool visible)

如果visible 为 true，则位于index 位置的页面可见；否则，位于index 位置的页面隐藏。页面的标签页将适当重绘。

另请参见 isTabVisible().

void QTabWidget::setTabWhatsThis(int index, const QString &text)

将index 位置页面的 "这是什么 "帮助文本设置为text 。

另请参阅 tabWhatsThis() 。

[override virtual protected] void QTabWidget::showEvent(QShowEvent *)

重实现：QWidget::showEvent(QShowEvent *event).

[override virtual] QSize QTabWidget::sizeHint() const

重构属性访问函数：QWidget::sizeHint 。

QTabBar *QTabWidget::tabBar() const

返回当前的QTabBar 。

另请参阅 setTabBar() 。

[signal] void QTabWidget::tabBarClicked(int index)

当用户点击index 上的标签页时，会发出该信号。

index 指点击的标签页，如果光标下没有标签页，则为-1。

[signal] void QTabWidget::tabBarDoubleClicked(int index)

当用户双击index 上的标签页时，将发出该信号。

index 是被点击标签页的索引，如果光标下没有标签页，则为-1。

[signal] void QTabWidget::tabCloseRequested(int index)

点击标签页上的关闭按钮时会发出该信号。index 是应删除的索引。

另请参阅 setTabsClosable() 。

QIcon QTabWidget::tabIcon(int index) const

返回位于index 位置的页面标签的图标。

另请参阅 setTabIcon() 。

[virtual protected] void QTabWidget::tabInserted(int index)

在index 位置添加或插入新标签页后，会调用此虚拟处理程序。

另请参阅 tabRemoved() 。

[virtual protected] void QTabWidget::tabRemoved(int index)

从index 位置移除一个制表符后，将调用此虚拟处理程序。

另请参见 tabInserted()。

QString QTabWidget::tabText(int index) const

返回位于index 位置的页面标签页的标签文本。

另请参阅 setTabText() 。

QString QTabWidget::tabToolTip(int index) const

返回位于index 位置的页面的制表符工具提示，如果没有设置工具提示，则返回空字符串。

另请参阅 setTabToolTip().

QString QTabWidget::tabWhatsThis(int index) const

返回index 位置页面的 "这是什么 "帮助文本，如果未设置帮助文本，则返回空字符串。

另请参阅 setTabWhatsThis().

QWidget *QTabWidget::widget(int index) const

返回索引位置index 上的标签页，如果index 不在范围内，则返回nullptr 。

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.