QTabWidget，是一个容器类控件。由一个QTabBar和一个QStackedWidget共同组织而成。

  • QTabBar：选项卡栏，用来切换界面；
  • QStackedWidget：页面区域，用来显示与每个选项卡相关的界面。
    默认情况下：
  • 选项卡栏显示在页面区域上方，可以通过配置修改显示位置。
  • 每个选项卡关联一个页面，在页面区域中只会显示当前页面，其他页面隐藏。
  • 用户可以单击选项卡或使用快捷键来切换页面。

枚举

作用 枚举 namespace 枚举值 描述
标签显示位置值 enum TabPosition; QtabWidget North 北
South 南
West 西
East 东
标签页形状值 enum TabShape;
 QtabWidget Rounded 圆角
Triangular 三角形
文本过多时的省略号位置 enum TextElideMode; Qt ElideLeft 文本开头
ElideRight 文本结尾
ElideMiddle 文本中间
ElideNone 无省略号
矩形角位置 enum Corner; Qt TopLeftCorner 矩形左上角
TopRightCorner 矩形右上角
BottomLeftCorner 矩形左下角
BottomRightCorner 矩形右下角

属性

属性名 属性类型 默认值 作用
count int 0 tab数量
currentIndex int -1 当前tab索引
tabPosition QTabWidget::TabPosition North tab方向
tabShape QTabWidget::TabShape Rounded tab形状
iconSize QSize / 标签图标的最大尺寸
elideMode Qt::TextElideMode / 是否省略多余的标签文本
movable bool false 是否可移动tab
tabsClosable bool false 是否显示关闭tab按钮
usesScrollButtons bool / 是否启用滚动按钮
tabBarAutoHide bool false 是否自动隐藏标签栏
documentMode bool false 是否启用阅读模式

函数

获取标签页个数

函数：获取标签页个数。

1
int count() const;

添加标签页

添加一个新标签页。标签页由 widget + label + icon 组成，widget是放入标签页的控件，label是标签文本，icon是标签图标。

1
2
int addTab(QWidget *widget, const QString& label);
int addTab(QWidget *widget, const QIcon& icon, const QString& label);

插入标签页

在指定索引位置idx处插入一个标签页，并返回标签页的索引。

1
2
int insertTab(int idx, QWidget *widget, const QString& label);
int insertTab(int idx, QWidget *widget, const QIcon& icon, const QString& label);

注意事项；

  • 当idx超出索引范围时，会变为追加标签页操作，因此返回值不一定是传入的参数idx。
  • 若label中包含&，则其后的首个字符会被作为移动到该tab的快捷键。如label为”HL&A”，则使用Alt+A会将焦点移动到该tab上。
  • 若在show()之后调用insertTab()，布局系统在调整widget的层次结构时可能导致界面闪烁。因此为了避免这一情况，建议执行以下操作： 
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    /*
    * 将QWidget::updateEnabled设置为false，使widget不接收绘制事件；
    * 调用insertTab()；
    * 将QWidget::updateEnabled设置为true，使widget接收绘制事件。
    */
    QTabWidget tabWidget = new QTabWidget(this);
    tabWidget->show();
    setUpdatesEnabled(false);
    QWidget widget = new QWidget(this);
    tabWidget->insertTab(2, widget, "tab-2");
    setUpdatesEnabled(true);

移除标签页

移除指定索引位置idx的标签页，但不删除该标签页的widget。

1
void removeTab(int idx);

清空标签页

移除所有标签页，但不删除所有的widget。

1
void clear();

获取/设置当前标签页索引

获取当前标签页的索引；

1
int currentIndex() const;

设置当前标签页的索引；

1
void setCurrentIndex(int index);

获取/设置当前标签页控件

获取当前标签页的控件；

1
QWidget* currentWidget() const;

设置当前标签页的控件，该控件必须是其中一个页面。

1
void setCurrentWidget(QWidget* w);

设置指定标签页控件

设置指定标签页的控件；

1
void setTabWidget(itn index, QWidget* w);

获取/设置标签页方向

获取/设置标签页当前方向。

1
2
TabPosition tabPosition() const;
void setTabPosition(TabPosition pos);

获取/设置标签页形状

获取/设置标签页当前形状。

1
2
TabShape tabShape() const;
void setTabShape(TabShape s);

获取/设置标签文本

获取指定索引位置的标签文本。

1
QString tabText(int idx) const;

设置指定索引位置的标签文本。

1
void setTabText(int idx, const QString& text);

获取/设置标签图标

获取指定标签的图标。

1
QIcon tabIcon(int idx) const;

设置指定标签的图标。

1
void setTabIcon(int idx, const QIcon& icon);

获取标签的图标的最大尺寸。

1
QSize iconSize() const;

设置标签的图标的最大尺寸，当图标尺寸较小时，不会等比例放大。

1
void setIconSize(const QSize& size);

可移动（拖拽）标签

获取标签是否可移动。

1
bool isMovable() const;

设置标签是否可移动。

1
void setMovable(bool movable);

自动隐藏标签栏

设置是否自动隐藏标签栏，当标签页数为1时，使得标签栏自动隐藏。

1
void setTabBarAutoHide(bool autoHide);

设置是否启用文档模式，标签栏会在没有活动标签时自动隐藏。

1
void setDocumentMode(bool enabled);

标签页的关闭按钮

1
void setTabClosable(bool closable);

启用/禁用指定标签页

1
void setTabEnabled(int idx, bool enabled);

启用/禁用滚动按钮

当标签过多时，可以选择扩展标签栏大小或添加滚动标签的按钮。
获取是否启用滚动按钮。

1
bool usesScrollButtons() const;

设置是否启用滚动按钮。

1
void setUsesScrollButtons(bool useButtons);

获取/设置指定位置的角落控件

角落控件仅生效于南北选项卡，不生效于东西选项卡。
获取指定位置的角落控件。

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

设置指定位置的角落控件。

1
void setCornerWidget(QWidget *w, Qt::Corner corner = Qt::TopRightCorner);

信号

当页面索引发生变化时发出此信号，idx为新的当前页面索引。若没有页面，则idx为-1。
该信号是currentIndex属性的通信信号。

1
void currentChanged(int idx);

单击标签时发出此信号。idx表示单击的标签，若光标下无标签，则idx为-1。

1
void tabBarClicked(int idx);

双击标签时发出此信号。idx表示双击的标签，若光标下无标签，则idx为-1。

1
void tabBarDoubleClicked(int idx);

单击标签的关闭按钮时发出此信号，idx为被移除的标签页索引。

1
void tabCloseRequested(int idx);