PySide6.QtWidgets.QTabWidget

class QTabWidget

QTabWidget 类提供了一组带有标签的窗口部件堆栈。更多…

PySide6.QtWidgets.QTabWidget 的继承图

概要

属性

  • countᅟ - 标签栏中的标签数量

  • currentIndexᅟ - 当前标签页的索引位置

  • documentModeᅟ - 选项卡小部件是否以适合文档页面的模式呈现。这与macOS上的文档模式相同

  • elideModeᅟ - 如何在标签栏中省略文本

  • iconSizeᅟ - 标签栏中图标的大小

  • movableᅟ - 此属性表示用户是否可以在标签栏区域内移动标签

  • tabBarAutoHideᅟ - 如果为true，当标签栏包含少于2个标签时，标签栏会自动隐藏

  • tabPositionᅟ - 此选项卡小部件中选项卡的位置

  • tabShapeᅟ - 此选项卡小部件中选项卡的形状

  • tabsClosableᅟ - 是否自动为每个标签页添加关闭按钮

  • usesScrollButtonsᅟ - 当标签栏有很多标签时，是否应该使用按钮来滚动标签

方法

虚拟方法

插槽

信号

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述

../../_images/fusion-tabwidget.png

选项卡小部件提供了一个选项卡栏（参见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 标签对话框示例

class TabPosition

此枚举类型定义了QTabWidget绘制标签行的位置：

常量

描述

QTabWidget.North

标签绘制在页面上方。

QTabWidget.South

标签绘制在页面下方。

QTabWidget.West

标签绘制在页面的左侧。

QTabWidget.East

标签绘制在页面的右侧。
class TabShape

此枚举类型定义了标签的形状：

常量

描述

QTabWidget.Rounded

选项卡以圆角外观绘制。这是默认的形状。

QTabWidget.Triangular

标签以三角形外观绘制。

注意

当使用from __feature__ import true_property时，属性可以直接使用，否则通过访问器函数使用。

property countᅟ: int

此属性保存标签栏中的标签数量。

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

Access functions:
property currentIndexᅟ: int

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

如果没有当前的小部件，当前索引为-1。

默认情况下，此属性包含的值为-1，因为小部件最初没有选项卡。

Access functions:
property documentModeᅟ: bool

此属性保存选项卡小部件是否以适合文档页面的模式呈现。这与macOS上的文档模式相同。

当设置此属性时，标签小部件的框架不会被渲染。此模式适用于显示文档类型的页面，其中页面覆盖了标签小部件的大部分区域。

Access functions:
property elideModeᅟ: Qt.TextElideMode

此属性控制如何在标签栏中省略文本。

此属性控制在给定标签栏大小下，当没有足够空间显示项目时，如何省略项目。

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

Access functions:
property iconSizeᅟ: QSize

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

默认值是样式相关的。这是图标将具有的最大尺寸。如果图标尺寸较小，则不会放大。

另请参阅

iconSize

Access functions:
property movableᅟ: bool

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

默认情况下，此属性为 false;

Access functions:
property tabBarAutoHideᅟ: bool

此属性表示如果为真，当标签栏包含少于2个标签时，标签栏将自动隐藏。

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

另请参阅

visible

Access functions:
property tabPositionᅟ: QTabWidget.TabPosition

此属性保存此选项卡小部件中选项卡的位置。

此属性的可能值由TabPosition枚举描述。

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

另请参阅

TabPosition

Access functions:
property tabShapeᅟ: QTabWidget.TabShape

此属性保存此选项卡小部件中选项卡的形状。

此属性的可能值为 Rounded（默认）或 Triangular。

另请参阅

TabShape

Access functions:
property tabsClosableᅟ: bool

此属性保存是否为每个选项卡自动添加关闭按钮。

另请参阅

tabsClosable()

Access functions:
property usesScrollButtonsᅟ: bool

此属性决定当标签栏有多个标签时，是否应使用按钮来滚动标签。

当标签栏中的标签过多以至于超出其大小时，标签栏可以选择扩展其大小或添加按钮，以便您可以滚动浏览标签。

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

Access functions:
__init__([parent=None])
Parameters:

父级 – QWidget

构建一个带有父级 parent 的标签小部件。

addTab(widget, label)
Parameters:
Return type:

整数

向标签小部件添加一个带有给定page和label的标签，并返回标签在标签栏中的索引。page的所有权将传递给QTabWidget。

如果标签的label包含一个&符号，&符号后面的字母将用作标签的快捷键，例如，如果标签是“Bro&wse”，那么Alt+W将成为一个快捷键，用于将焦点移动到此标签。

注意

如果在show()之后调用addTab()，布局系统将尝试调整其小部件层次结构中的更改，并可能导致闪烁。为了防止这种情况，您可以在更改之前将updatesEnabled属性设置为false；更改完成后记得将该属性设置为true，使小部件再次接收绘制事件。

另请参阅

insertTab()

addTab(widget, icon, label)
Parameters:
Return type:

整数

这是一个重载函数。

向标签小部件添加一个带有给定page、icon和label的标签，并返回该标签在标签栏中的索引。page的所有权将传递给QTabWidget。

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

clear()

移除所有页面，但不会删除它们。调用此函数相当于调用removeTab()直到标签部件为空。

cornerWidget([corner=Qt.TopRightCorner])
Parameters:

角落 – Corner

Return type:

QWidget

返回标签部件角落中显示的小部件或None。

另请参阅

setCornerWidget()

count()
Return type:

整数

属性 countᅟ 的获取器。

currentChanged(index)
Parameters:

索引 – int

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

属性 currentIndexᅟ 的通知信号。

currentIndex()
Return type:

整数

另请参阅

setCurrentIndex()

属性 currentIndexᅟ 的获取器。

currentWidget()
Return type:

QWidget

返回指向当前由标签对话框显示的页面的指针。标签对话框会尽力确保此值永远不会为0（但如果你足够努力，它可能会是）。

documentMode()
Return type:

布尔

另请参阅

setDocumentMode()

属性 documentModeᅟ 的获取器。

elideMode()
Return type:

TextElideMode

另请参阅

setElideMode()

属性 elideModeᅟ 的获取器。

iconSize()
Return type:

QSize

另请参阅

setIconSize()

属性 iconSizeᅟ 的获取器。

indexOf(widget)
Parameters:

widget – QWidget

Return type:

整数

返回小部件w占用的页面索引位置，如果找不到小部件则返回-1。

initStyleOption(option)
Parameters:

选项 – QStyleOptionTabWidgetFrame

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

insertTab(index, widget, label)
Parameters:

  • index – 整数

  • widget – QWidget

  • label – str

Return type:

整数

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

标签显示在选项卡中，其外观可能会根据选项卡小部件的配置而有所不同。

如果标签的label包含一个&符号，&符号后面的字母将用作标签的快捷键，例如，如果标签是“Bro&wse”，那么Alt+W将成为一个快捷键，用于将焦点移动到此标签。

如果index超出范围，标签将简单地附加。否则，它将被插入到指定的位置。

如果在调用此函数之前QTabWidget为空，则新页面将成为当前页面。在当前索引小于或等于当前索引的位置插入新标签页将增加当前索引，但保持当前页面不变。

注意

如果在show()之后调用insertTab()，布局系统将尝试调整其小部件层次结构中的更改，并可能导致闪烁。为了防止这种情况，您可以在更改之前将updatesEnabled属性设置为false；更改完成后记得将该属性设置为true，使小部件再次接收绘制事件。

另请参阅

addTab()

insertTab(index, widget, icon, label)
Parameters:

  • index – 整数

  • widget – QWidget

  • 图标 – QIcon

  • label – str

Return type:

整数

这是一个重载函数。

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

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

isMovable()
Return type:

布尔

属性 movableᅟ 的获取器。

isTabEnabled(index)
Parameters:

索引 – int

Return type:

布尔

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

isTabVisible(index)
Parameters:

索引 – int

Return type:

布尔

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

另请参阅

setTabVisible()

removeTab(index)
Parameters:

索引 – int

从这个小部件堆栈中移除位置为index的标签。页面小部件本身不会被删除。

另请参阅

addTab() insertTab()

setCornerWidget(w[, corner=Qt.TopRightCorner])
Parameters:

将给定的widget设置为在标签小部件的指定corner中显示。小部件的几何形状由小部件的sizeHint()和style()决定。

仅使用corner的水平元素。

传递 None 在角落不显示小部件。

任何先前设置的角落小部件都被隐藏。

除非在设置其他角落小部件（或None）后单独重新设置小部件的父级，否则在此设置的所有小部件将在选项卡小部件销毁时被删除。

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

setCurrentIndex(index)
Parameters:

索引 – int

另请参阅

currentIndex()

属性 currentIndexᅟ 的设置器。

setCurrentWidget(widget)
Parameters:

widget – QWidget

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

setDocumentMode(set)
Parameters:

set – 布尔值

另请参阅

documentMode()

属性 documentModeᅟ 的设置器。

setElideMode(mode)
Parameters:

mode – TextElideMode

另请参阅

elideMode()

属性 elideModeᅟ 的设置器。

setIconSize(size)
Parameters:

大小 – QSize

另请参阅

iconSize()

属性 iconSizeᅟ 的设置器。

setMovable(movable)
Parameters:

movable – 布尔值

另请参阅

isMovable()

属性 movableᅟ 的设置器。

setTabBar(tb)
Parameters:

tb – QTabBar

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

另请参阅

tabBar()

setTabBarAutoHide(enabled)
Parameters:

enabled – 布尔值

另请参阅

tabBarAutoHide()

属性 tabBarAutoHideᅟ 的设置器。

setTabEnabled(index, enabled)
Parameters:

  • index – 整数

  • enabled – 布尔值

如果 enable 为 true，则启用位置 index 处的页面；否则禁用位置 index 处的页面。页面的标签会相应地重新绘制。

QTabWidget 内部使用 setEnabled()，而不是维护一个单独的标志。

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

setTabIcon(index, icon)
Parameters:

  • index – 整数

  • 图标 – QIcon

设置位于位置 index 的标签页的 icon。

另请参阅

tabIcon()

setTabPosition(position)
Parameters:

位置 – TabPosition

另请参阅

tabPosition()

属性 tabPositionᅟ 的设置器。

setTabShape(s)
Parameters:

s – TabShape

另请参阅

tabShape()

属性 tabShapeᅟ 的设置器。

setTabText(index, text)
Parameters:

  • index – 整数

  • 文本 – str

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

如果提供的文本包含一个&符号（'&'），则会自动为其创建一个快捷键。'&'后面的字符将用作快捷键。任何先前的快捷键将被覆盖，如果文本没有定义快捷键，则会被清除。详情请参阅QShortcut文档（要显示实际的&符号，请使用'&&'）。

另请参阅

tabText()

setTabToolTip(index, tip)
Parameters:

  • index – 整数

  • 提示 – str

将位置 index 处的页面的标签工具提示设置为 tip。

另请参阅

tabToolTip()

setTabVisible(index, visible)
Parameters:

  • index – 整数

  • visible – 布尔值

如果 visible 为 true，则位置 index 处的页面可见；否则位置 index 处的页面隐藏。页面的标签会相应地重新绘制。

另请参阅

isTabVisible()

setTabWhatsThis(index, text)
Parameters:

  • index – 整数

  • 文本 – str

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

另请参阅

tabWhatsThis()

setTabsClosable(closeable)
Parameters:

closeable – 布尔值

另请参阅

tabsClosable()

属性 tabsClosableᅟ 的设置器。

setUsesScrollButtons(useButtons)
Parameters:

useButtons – 布尔值

另请参阅

usesScrollButtons()

属性 usesScrollButtonsᅟ 的设置器。

tabBar()
Return type:

QTabBar

返回当前的 QTabBar 。

另请参阅

setTabBar()

tabBarAutoHide()
Return type:

布尔

另请参阅

setTabBarAutoHide()

属性 tabBarAutoHideᅟ 的获取器。

tabBarClicked(index)
Parameters:

索引 – int

当用户点击选项卡时，会发出此信号，选项卡位于index。

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

tabBarDoubleClicked(index)
Parameters:

索引 – int

当用户双击选项卡上的index时，会发出此信号。

index 是点击的选项卡的索引，如果光标下没有选项卡，则为 -1。

tabCloseRequested(index)
Parameters:

索引 – int

当点击标签页上的关闭按钮时，会发出此信号。index 是要移除的索引。

另请参阅

setTabsClosable()

tabIcon(index)
Parameters:

索引 – int

Return type:

QIcon

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

另请参阅

setTabIcon()

tabInserted(index)
Parameters:

索引 – int

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

另请参阅

tabRemoved()

tabPosition()
Return type:

TabPosition

另请参阅

setTabPosition()

获取属性 tabPositionᅟ 的Getter。

tabRemoved(index)
Parameters:

索引 – int

当标签从位置 index 移除后，将调用此虚拟处理程序。

另请参阅

tabInserted()

tabShape()
Return type:

TabShape

另请参阅

setTabShape()

属性 tabShapeᅟ 的获取器。

tabText(index)
Parameters:

索引 – int

Return type:

字符串

返回页面中位置为index的选项卡的标签文本。

另请参阅

setTabText()

tabToolTip(index)
Parameters:

索引 – int

Return type:

字符串

返回位于位置 index 的页面的标签工具提示，如果未设置工具提示，则返回空字符串。

另请参阅

setTabToolTip()

tabWhatsThis(index)
Parameters:

索引 – int

Return type:

字符串

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

另请参阅

setTabWhatsThis()

tabsClosable()
Return type:

布尔

另请参阅

setTabsClosable()

属性 tabsClosableᅟ 的获取器。

usesScrollButtons()
Return type:

布尔

另请参阅

setUsesScrollButtons()

属性 usesScrollButtonsᅟ 的获取器。

widget(index)
Parameters:

索引 – int

Return type:

QWidget

返回索引位置为 index 的标签页，如果 index 超出范围则返回 None。