QTabWidget Class
QTabWidget 类提供了一组标签页控件。更多内容...
| 标题： | #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 |
详细说明
标签页控件提供了一个标签栏（参见QTabBar ）和一个“页面区域”，用于显示与每个标签页相关的页面。默认情况下，标签栏显示在页面区域上方，但也可进行其他配置（参见TabPosition ）。每个标签页都与一个不同的控件（称为页面）相关联。 页面区域中仅显示当前页面；所有其他页面均被隐藏。用户可以通过点击相应标签页，或按下相应的Alt+字母快捷键（如有）来显示其他页面。
使用 QTabWidget 的常规方法如下：
- 创建一个 QTabWidget。
- 为标签页对话框中的每个页面创建一个QWidget ，但不要为其指定父控件。
- 将子控件插入页面控件中，并使用布局像往常一样定位它们。
- 调用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::North | 0 | 选项卡绘制在页面上方。 |
QTabWidget::South | 1 | 选项卡绘制在页面下方。 |
QTabWidget::West | 2 | 标签显示在页面左侧。 |
QTabWidget::East | 3 | 标签显示在页面右侧。 |
enum QTabWidget::TabShape
此枚举类型定义了选项卡的形状：
| 常量 | 值 | 描述 |
|---|---|---|
QTabWidget::Rounded | 0 | 标签以圆角样式绘制。这是默认形状。 |
QTabWidget::Triangular | 1 | 标签以三角形样式绘制。 |
属性文档
[read-only] count : int
该属性存储标签栏中的标签页数量
默认情况下，此属性的值为 0。
访问函数：
| int | count() const |
currentIndex : int
该属性存储当前标签页的索引位置
如果没有当前小部件，则当前索引为 -1。
默认情况下，该属性的值为 -1，因为小部件初始时没有标签页。
访问函数：
| int | currentIndex() const |
| void | setCurrentIndex(int index) |
通知信号：
| void | currentChanged(int index) |
documentMode : bool
该属性控制标签控件是否以适合文档页面的模式进行渲染。这与 macOS 中的“文档模式”相同。
当设置此属性时，标签控件的边框不会被渲染。此模式适用于显示文档类页面，此时页面会占据标签控件区域的大部分空间。
访问函数：
| 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 个时，该标签栏将自动隐藏。
默认情况下，此属性为 false。
访问函数：
| bool | tabBarAutoHide() const |
| void | setTabBarAutoHide(bool enabled) |
另请参阅 QWidget::visible 。
tabPosition : TabPosition
该属性用于存储此标签控件中各标签的位置
该属性的可能取值由TabPosition 枚举定义。
默认情况下，此属性设置为North 。
访问函数：
| QTabWidget::TabPosition | tabPosition() const |
| void | setTabPosition(QTabWidget::TabPosition position) |
另请参阅 TabPosition 。
tabShape : TabShape
该属性用于定义此选项卡控件中选项卡的形状
该属性的可能取值为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 的带标签页的小部件。
[virtual noexcept] QTabWidget::~QTabWidget()
销毁带标签的小部件。
int QTabWidget::addTab(QWidget *page, const QString &label)
向标签控件添加一个具有指定page 和label 的标签页，并返回该标签页在标签栏中的索引。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
返回小部件w 所占用的页面索引位置；如果找不到该小部件，则返回-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)
在指定位置index 的标签控件中插入一个标签页，该标签页具有指定的label 和page ，并返回该标签页在标签栏中的索引。page 的所有权将传递给QTabWidget 。
标签将显示在标签页中，其外观可能因标签页控件的配置而异。
如果标签的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 的访问函数。
返回标签控件的合适最小尺寸。
[override virtual protected] void QTabWidget::paintEvent(QPaintEvent *event)
重写：QWidget::paintEvent(QPaintEvent *event)。
响应绘制事件event ，绘制选项卡控件的选项卡栏。
void QTabWidget::removeTab(int index)
从该小部件堆栈中移除位于位置index 的标签页。页面小部件本身不会被删除。
[override virtual protected] void QTabWidget::resizeEvent(QResizeEvent *e)
重写了：QWidget::resizeEvent(QResizeEvent *event)。
void QTabWidget::setCornerWidget(QWidget *widget, Qt::Corner corner = Qt::TopRightCorner)
将给定的widget 设置为在标签页控件的指定corner 中显示。控件的几何属性基于控件的sizeHint()和style()确定。
仅使用corner 的水平元素。
传递nullptr 将导致角落处不显示任何控件。
之前设置的任何角控件都会被隐藏。
除非您在设置其他角小部件（或nullptr ）后单独重新将小部件设置为父对象，否则此处设置的所有小部件都将在标签页小部件被销毁时被删除。
注意：角控件专为North 和South 标签位置设计；已知其他方向无法正常工作。
另请参阅 cornerWidget() 和setTabPosition()。
[slot] void QTabWidget::setCurrentWidget(QWidget *widget)
将widget 设为当前控件。所使用的widget 必须是该标签页控件中的一个页面。
另请参阅 addTab()、setCurrentIndex() 和currentWidget()。
[protected] void QTabWidget::setTabBar(QTabBar *tb)
将对话框的QTabBar 标题替换为标签栏tb 。请注意，必须在添加任何标签之前调用此方法，否则行为将无法确定。
另请参阅 tabBar()。
void QTabWidget::setTabEnabled(int index, bool enable)
如果 `enable ` 为真，则位置为 `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 的页面标签页定义一个新的label 。
如果提供的文本中包含“&”字符，系统会自动为其创建一个快捷键。“&”后面的字符将用作快捷键。如果该文本定义了快捷键，则会覆盖之前的快捷键；如果文本中未定义快捷键，则会清除该快捷键。 详情请参阅QShortcut 文档（若要显示真正的“&”符号，请使用 '&&'）。
另请参阅 tabText()。
void QTabWidget::setTabToolTip(int index, const QString &tip)
将位置为index 的页面标签工具提示设置为tip 。
另请参阅 tabToolTip()。
void QTabWidget::setTabVisible(int index, bool visible)
如果visible 为真，则位置为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 。
© 2026 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.
