前言

本系列介绍如何在 Python 中使用 Qt for Python 进行 GUI 应用程序开发。

• 第一篇文章：Qt for Python学习笔记—简介
• 第二篇文章：Qt for Python学习笔记—搭建开发环境
• 第三篇文章：Qt for Python学习笔记—应用程序初探
• 第四篇文章：Qt for Python学习笔记—应用程序再探
• 第五篇文章：Qt for Python—Qt Designer 概览
• 第六篇文章：Qt for Python—可视化开发GUI应用程序
• 第七篇文章：Qt for Python布局管理(1)—概览
• 第八篇文章：Qt for Python布局管理(2)—绝对定位

本文是《Qt for Python 学习笔记》系列第九篇，对 Qt for Python 的盒式布局以及水平布局进行介绍，让读者对 Qt for Python 水平布局有个较为基本的认识。

1. 简介

1.1 术语

下表列示了本文涉及到的一些术语：

1.2 布局管理器

所有 QWidget 的子类都可以使用布局管理器来管理它们之中的子部件。

Qt for Python 提供了一组标准布局管理类（也称为标准布局管理器），这些类被用于描述如何在应用程序的用户界面中布置部件。当可用空间发生变化时，这些布局将会自动定位和调整所包含的组件的尺寸，以确保它们布局的一致性和整个用户界面保持可用。

2. 盒式布局管理器

盒式布局类（QBoxLayout）也称为盒式布局管理器。

2.1 盒式布局类的继承关系

QBoxLayout 类继承自 QLayout 类，同时又是 QHBoxLayout 类 和 QVBoxLayout 类的父类。其类的继承关系如下图示：

2.2 盒式布局类的基本信息

从 QtWidgets.pyi 文件中可以查看到 QBoxLayout 类的基本信息：

 class QBoxLayout(PySide6.QtWidgets.QLayout):
     LeftToRight              : QBoxLayout.Direction = ... # 0x0
     RightToLeft              : QBoxLayout.Direction = ... # 0x1
     Down                     : QBoxLayout.Direction = ... # 0x2
     TopToBottom              : QBoxLayout.Direction = ... # 0x2
     BottomToTop              : QBoxLayout.Direction = ... # 0x3
     Up                       : QBoxLayout.Direction = ... # 0x3
 
     class Direction(object):
         LeftToRight              : QBoxLayout.Direction = ... # 0x0
         RightToLeft              : QBoxLayout.Direction = ... # 0x1
         Down                     : QBoxLayout.Direction = ... # 0x2
         TopToBottom              : QBoxLayout.Direction = ... # 0x2
         BottomToTop              : QBoxLayout.Direction = ... # 0x3
         Up                       : QBoxLayout.Direction = ... # 0x3
 
     def __init__(self, arg__1:PySide6.QtWidgets.QBoxLayout.Direction, parent:typing.Optional[PySide6.QtWidgets.QWidget]=...) -> None: ...
 
     def addItem(self, arg__1:PySide6.QtWidgets.QLayoutItem) -> None: ...
     def addLayout(self, layout:PySide6.QtWidgets.QLayout, stretch:int=...) -> None: ...
     def addSpacerItem(self, spacerItem:PySide6.QtWidgets.QSpacerItem) -> None: ...
     def addSpacing(self, size:int) -> None: ...
     def addStretch(self, stretch:int=...) -> None: ...
     def addStrut(self, arg__1:int) -> None: ...
     @typing.overload
     def addWidget(self, arg__1:PySide6.QtWidgets.QWidget, stretch:int=..., alignment:PySide6.QtCore.Qt.Alignment=...) -> None: ...
     @typing.overload
     def addWidget(self, w:PySide6.QtWidgets.QWidget) -> None: ...
     def count(self) -> int: ...
     def direction(self) -> PySide6.QtWidgets.QBoxLayout.Direction: ...
     def expandingDirections(self) -> PySide6.QtCore.Qt.Orientations: ...
     def hasHeightForWidth(self) -> bool: ...
     def heightForWidth(self, arg__1:int) -> int: ...
     def insertItem(self, index:int, arg__2:PySide6.QtWidgets.QLayoutItem) -> None: ...
     def insertLayout(self, index:int, layout:PySide6.QtWidgets.QLayout, stretch:int=...) -> None: ...
     def insertSpacerItem(self, index:int, spacerItem:PySide6.QtWidgets.QSpacerItem) -> None: ...
     def insertSpacing(self, index:int, size:int) -> None: ...
     def insertStretch(self, index:int, stretch:int=...) -> None: ...
     def insertWidget(self, index:int, widget:PySide6.QtWidgets.QWidget, stretch:int=..., alignment:PySide6.QtCore.Qt.Alignment=...) -> None: ...
     def invalidate(self) -> None: ...
     def itemAt(self, arg__1:int) -> PySide6.QtWidgets.QLayoutItem: ...
     def maximumSize(self) -> PySide6.QtCore.QSize: ...
     def minimumHeightForWidth(self, arg__1:int) -> int: ...
     def minimumSize(self) -> PySide6.QtCore.QSize: ...
     def setDirection(self, arg__1:PySide6.QtWidgets.QBoxLayout.Direction) -> None: ...
     def setGeometry(self, arg__1:PySide6.QtCore.QRect) -> None: ...
     def setSpacing(self, spacing:int) -> None: ...
     def setStretch(self, index:int, stretch:int) -> None: ...
     @typing.overload
     def setStretchFactor(self, l:PySide6.QtWidgets.QLayout, stretch:int) -> bool: ...
     @typing.overload
     def setStretchFactor(self, w:PySide6.QtWidgets.QWidget, stretch:int) -> bool: ...
     def sizeHint(self) -> PySide6.QtCore.QSize: ...
     def spacing(self) -> int: ...
     def stretch(self, index:int) -> int: ...
     def takeAt(self, arg__1:int) -> PySide6.QtWidgets.QLayoutItem: ...

3. 水平布局管理器

子类水平布局类（QHBoxLayout）也称为水平布局管理器。

3.1 水平布局类关系

QHBoxLayout 类继承自 QBoxLayout 类，其类的继承关系如下图示：

3.2 水平布局类的基本信息

从 QtWidgets.pyi 文件中可以查看到 QHBoxLayout 类的定义信息：

 class QHBoxLayout(PySide6.QtWidgets.QBoxLayout):
 
     @typing.overload
     def __init__(self) -> None: ...
     @typing.overload
     def __init__(self, parent:PySide6.QtWidgets.QWidget) -> None: ...

4. 利用水平布局管理器对部件进行布局的基本步骤

在窗口上利用水平布局管理器对各部件进行水平布局的基本步骤如下：

• Step1：创建一个窗口部件对象；
• Step2：创建一个水平布局对象；
• Step3：将该水平布局对象设置为窗口部件对象的布局管理器。
• Step4：创建（待放置的）相关部件对象；
• Step5：将相关部件逐一添加到水平布局对象上；
• Step6（可选）：设置各部件拉伸因子、对齐方式；

注1：若在 Step2 中创建水平布局对象时未为该布局对象指定父部件（上层布局），则可以必须执行 Step3（调用 setLayout() 方法来为父部件设置该布局对象）；

注2：若在 Step2 中创建水平布局对象时为该布局对象指定了父部件（上层布局），则可以省去 Step3；

注3：不需要为添加到水平布局对象中的各部件指定父部件。

5. 水平布局管理器应用主要函数介绍

要给窗口中多个部件进行水平排列最简单的方法就是使用内置的水平布局管理器（QHBoxLayout）。

水平布局类（QHBoxLayout）中仅有构造函数，其他方法主要是继承自其父类（QBoxLayout）。

编程应用中比较常用的水平布局相关函数如下：

5.1 创建水平布局对象的函数

一、构造函数声明

class QHBoxLayout(PySide6.QtWidgets.QBoxLayout):
    @typing.overload
    def __init__(self) -> None: ...
    @typing.overload
    def __init__(self, parent:PySide6.QtWidgets.QWidget) -> None: ...

二、构造函数形式1说明

——功能：该构造函数（无传递参数 parent）将会创建一个水平布局对象，后续需要将该水平布局对象设置为一个指定部件的布局管理器。

三、构造函数形式2说明

——功能：该构造函数（带传递参数 parent）将会创建一个指定父部件（上层布局）的水平布局对象。

——参数（parent）：表示该布局对象的父部件（上层布局），类型为 QWidget 。一个部件只能有一个上层布局，其可以通过 layout() 方法返回获取。

5.2 将水平布局对象设置为部件的水平布局管理器的函数

一、函数声明

 def setLayout(self, layout:PySide6.QtWidgets.QLayout) -> None

该函数继承自 QWidget 类。

二、函数说明

——功能：将水平布局对象（layout）设置为部件的水平布局管理器。

——参数（layout）：表示已经创建好的水平布局对象，类型为 QLayout。

5.3 将部件添加到水平布局对象中的函数

一、函数声明

 @typing.overload
 def addWidget(self, widget:PySide6.QtWidgets.QWidget) -> None: ...
 @typing.overload
 def addWidget(self, widget:PySide6.QtWidgets.QWidget, stretch:int=..., alignment:PySide6.QtCore.Qt.Alignment=...) -> None: ...

上述两个函数是继承自 QBoxLayout 类中的同名重载函数。

二、函数1说明

——功能：该函数将指定部件（widget）添加到水平布局对象的末尾。

——参数（widget）：表示待添加到水平布局对象中的部件，类型为 QWidget。

三、函数2说明

——功能：该函数将指定部件（widget）添加到水平布局对象的末尾，同时设置该部件的拉伸因子（stretch）和对齐方式（alignment）。

——参数（widget）：表示待添加到水平布局对象中的部件，类型为 QWidget。

——参数（stretch）：表示部件的拉伸因子，类型为 int。该参数可省略，缺省值为0。

——参数（alignment）：表示部件的对齐方式，类型为 Qt.Alignment 枚举常量。该参数可省略，缺省值为0。

注：关于拉伸因子、对齐方式会在下一篇文章中进行详细介绍。

5.4 在水平布局对象指定位置插入指定部件的函数

一、函数声明

 def insertWidget(self, index:int, widget:PySide6.QtWidgets.QWidget, stretch:int=..., alignment:PySide6.QtCore.Qt.Alignment=...) -> None

上述函数继承自 QBoxLayout 类。

二、函数说明

——功能：该函数在水平布局对象的指定位置（index）插入指定部件（widget），同时设置该部件的拉伸因子和对齐方式。

——参数（index）：表示水平布局对象中指定位置，类型为 int。索引从0开始，0表示水平布局对象中的第一个位置（从左往右）；若索引为负值，则表示插入到水平布局对象末尾。

——参数（widget）：表示待插入到水平布局对象中的部件，类型为 QWidget。

——参数（stretch）：表示部件的拉伸因子，类型为 int。该参数可省略，缺省值为0。

——参数（alignment）：表示部件的对齐方式，类型为 Qt.Alignment 枚举常量。该参数可省略，缺省值为0。

5.5 将子布局添加到水平布局对象中的函数

一、函数声明

 def addLayout(self, layout:PySide6.QtWidgets.QLayout, stretch:int=...) -> None: ...

上述函数继承自 QBoxLayout 类。

二、函数说明

——功能：该函数将指定子布局（layout）添加到水平布局对象的末尾，同时设置该子布局的拉伸因子（stretch）

——参数（layout）：表示待添加到水平布局对象中的子布局，类型为 QLayout。

——参数（stretch）：表示子布局的拉伸因子，类型为 int。该参数可省略，缺省值为0。

5.6 在水平布局对象指定位置插入指定子布局的函数

一、函数声明

 def insertLayout(self, index:int, layout:PySide6.QtWidgets.QLayout, stretch:int=...) -> None: ...

上述函数继承自 QBoxLayout 类。

二、函数说明

——功能：该函数在水平布局对象的指定位置（index）插入指定子布局（layout），同时设置该部件的拉伸因子（stretch）。

——参数（index）：表示水平布局对象中指定位置，类型为 int。索引从0开始，0表示水平布局对象中的第一个位置（从左往右）；若索引为负值，则表示插入到水平布局对象末尾。

——参数（layout）：表示待添加到水平布局对象中的子布局，类型为 QLayout。

——参数（stretch）：表示子布局的拉伸因子，类型为 int。该参数可省略，缺省值为0。

6. 水平布局示例

6.1 示例原型

在进行 GUI 应用程序编码之前，一般建议先勾画出 GUI 框架（窗体及各部件的布局等）。本示例原型如下：

6.2 示例目标

本示例目标是创建一个 Python GUI 应用程序，在主窗口中从左往右依次放置4个标签（QLabel）。

主窗口及部件的位置、尺寸及其他属性如下：

• 主窗口

——(1) 窗口位置及尺寸采用默认提示值

——(2) 标题：水平布局示例程序

——(3) 具有窗口最小化、最大化、关闭快捷按钮

• 4个标签部件

——(1) 位置：4个标签从左往右依次排列

——(2) 尺寸：采用默认提示值

——(3) 背景色：4个标签依次为“SkyBlue”、“Pink”、“PaleGreen”、“Gold”

• 窗口缩放时各部件自动进行自适应调整

——(1) 水平方向：4个标签宽度能随窗口缩放而自适应调整（均匀填满窗口可用宽度）；

——(2) 垂直方向：4个标签高度能随窗口缩放而自适应调整（填满窗口可用高度）。

——(3) 在缩小或拉伸窗口时，标签四周的边框（左、上、右、下边框值）以及4个标签之间的水平间距始终保持不变。

注1：因为内置的 QPushButton 类（按钮部件）对其高度进行了限制，所以导致在窗口缩放时，按钮部件高度方面不能展示自动同步缩放的效果（按钮部件的高度始终保持不变，宽度方面是可以自动同步缩放的）。鉴于此，在本水平布局示例程序中使用标签部件，以便更好地随着窗口的缩放而同步缩放（宽度和高度方面）。

注2：布局具有边框属性（左、上、右、下边框值），布局内部各个子部件之间具有间距属性（水平方向为水平间距，垂直方向为垂直间距），通常情况下，边框属性和间距属性均有默认值，所以我们能看到四周的边框，以及各部件之间的间距。可以通过调用布局对象的 setContentsMargins(left, top, right, bottom) 方法来设置4个方向（左、上、右、下）上的边框值，可以通过调用布局对象的 setSpacing(spacing) 方法来设置布局中各个部件之间的间距值。

6.3 示例代码

利用 Visual Studio Code 编辑代码，并保存为文件（如：C:\MyPySide6\MyPySide6HBoxLayoutApp01.py）。

from PySide6.QtWidgets import (QApplication, QMainWindow, QWidget, QHBoxLayout, QLabel)

class MyMainWindow(QMainWindow):
    def __init__(self):
        super(MyMainWindow, self).__init__()

        window = QWidget() 
        hBoxLayout = QHBoxLayout() 
        window.setLayout(hBoxLayout) 

        label_1 = QLabel()
        label_2 = QLabel()
        label_3 = QLabel()
        label_4 = QLabel()
        label_1.setStyleSheet("background-color: SkyBlue;")
        label_2.setStyleSheet("background-color: Pink;")
        label_3.setStyleSheet("background-color: PaleGreen;")
        label_4.setStyleSheet("background-color: Gold;")
        
        hBoxLayout.addWidget(label_1)
        hBoxLayout.addWidget(label_2)
        hBoxLayout.insertWidget(2, label_4)
        hBoxLayout.insertWidget(2, label_3)

        self.setCentralWidget(window) 
        self.setWindowTitle("水平布局示例程序")
 
 if __name__ == '__main__':
     import sys
 
     app = QApplication(sys.argv)
     gui = MyMainWindow()
     gui.show()
     sys.exit(app.exec_())

6.4 代码解析

本示例代码共分三部分：

一、导入模块（或类）部分

 from PySide6.QtWidgets import (QApplication, QMainWindow, QWidget, QHBoxLayout, QLabel)

——第1行代码：表示从 PySide6.QtWidgets 模块导入后续代码中会用到的 QApplication 类、QMainWindow 类、QWidget 类、QHBoxLayout 类、QLabel 类。

二、自定义MyMainWindow类部分

其次，自定义 MyMainWindow 类（即主窗口，继承自 QMainWindow 类）：

（一）定义类的声明

 class MyMainWindow(QMainWindow):
     ...

自定义 MyMainWindow 类的声明语句。类名为 MyMainWindow，该类继承自 QMainWindow 类。

（二）定义类的构造函数

 def __init__(self):
     super(MyMainWindow, self).__init__()
 
     window = QWidget() 
     hBoxLayout = QHBoxLayout() 
     window.setLayout(hBoxLayout) 
 
    label_1 = QLabel()
    label_2 = QLabel()
    label_3 = QLabel()
    label_4 = QLabel()
    label_1.setStyleSheet("background-color: SkyBlue;")
    label_2.setStyleSheet("background-color: Pink;")
    label_3.setStyleSheet("background-color: PaleGreen;")
    label_4.setStyleSheet("background-color: Gold;")
        
    hBoxLayout.addWidget(label_1)
    hBoxLayout.addWidget(label_2)
    hBoxLayout.insertWidget(2, label_4)
    hBoxLayout.insertWidget(2, label_3)
 
     self.setCentralWidget(window) 
     self.setWindowTitle("水平布局示例程序")

上述代码定义了自定义 MyMainWindow 类的构造函数：

——第1行代码：声明一个类构造函数（ __init__(self)），有一个传递参数（self）。

——第2行代码：通过 super() 方法继承了父类（QMainWindow）构造函数中的全部属性。

——第4行代码：通过实例化 QWidget 类创建一个窗口对象（window）。

——第5行代码：通过实例化 QVBoxLayout 类创建一个水平布局对象（hBoxLayout）。

——第6行代码：通过调用窗口对象（window）的 setLayout() 方法将水平布局对象（hBoxLayout）设置为窗口对象的布局管理器。

——第8-11行代码：通过实例化 QLabel 类依次创建4个标签（这4个标签会添加到水平布局对象中，故无需设置其父部件）。

——第12-15行代码：通过调用标签对象的 setStyleSheet() 方法依次设置4个标签的背景色。

——第17行代码：调用水平布局对象的 addwidget(widget) 方法将指定部件（传入参数 widget，这里为标签1）添加到水平布局对象（hBoxLayout）末尾。此时标签1在水平布局中的位置所对应的索引值为0，即标签1放置在水平布局中的第一个位置（从左往右）。

——第18行代码：调用水平布局对象的 addwidget(widget) 方法将指定部件（传入参数 widget，这里为标签2）添加到水平布局对象（hBoxLayout）末尾。此时标签2在水平布局中的位置所对应的索引值为1，即标签2放置在水平布局中的第二个位置（从左往右）。

——第19行代码：调用水平布局对象的 insertwidget(index, widget) 方法将指定部件（传入参数 widget，这里为标签4）插入到水平布局对象（hBoxLayout）中的指定索引值（传入参数 index）为2的位置。此时标签4在水平布局中的位置所对应的索引值为2，即标签4放置在水平布局中的第三个位置（从左往右）。

注：这里是为了使用 insertwidget(index, widget) 方法，故意先添加标签4，然后接下来的语句再插入标签3。

——第20行代码：调用水平布局对象的 insertwidget(index, widget) 方法将指定部件（传入参数 widget，这里为标签3）插入到水平布局对象（hBoxLayout）中的指定索引值（传入参数 index）为2的位置。此时标签3在水平布局中的位置所对应的索引值为2，即标签3放置在水平布局中的第三个位置（从左往右）。因索引值为2的位置原来是标签4放置的位置，此时被标签3占据后，则标签4的位置需要向右移动一个位置，于是标签4在水平布局中的位置所对应的索引值变为3，即标签4放置在水平布局中的第四个位置（从左往右）。

——第22行代码：调用窗口的 setCentralWidget() 方法设置主窗口的中央部件为窗口对象（window）。

——第23行代码：调用窗口的 setWindowTitle() 方法设置主窗口的标题为"水平布局示例程序"。

三、设置文件运行入口部分

最后，在设置文件运行入口部分，完成创建应用程序、创建和显示自定义主窗口、运行应用程序直至退出。

 if __name__ == "__main__":
     import sys 
     
     app = QApplication(sys.argv)
     win = MyMainWindow()
     win.show()
     sys.exit(app.exec_())

——第1行代码：通过 if __name__ == "__main__": 语句来设置文件运行入口。

——第2行代码：导入 Python 内置的 sys 模块，接下的 sys.argv 和 sys.ext() 会用到该模块。

——第4行代码：使用 QApplication 类创建一个应用程序对象（app），括号内的 sys.argv 表示构造时含的传递参数。

——第5行代码：使用自定义的 MyMainWindow 类创建应用程序的主窗口对象（win）。

——第6行代码：调用主窗口对象（win）的 show() 方法来显示该主窗口。

——第7行代码：运行应用程序，直至退出。

6.5 示例程序运行

直接在 Visual Studio Code 上点击主窗体上运行图标按钮来运行该示例程序。

上图是程序运行后的三种窗口：

一、左上的是程序运行后提示窗口（原始窗口）

——(1) 在水平方向，4个标签部件宽度均匀填满窗口可用宽度；

——(2) 在垂直方向，4个标签部件填满窗口可用高度；

——(3) 在标签四周可以看见有边框（左、上、右、下边框值），在4个标签之间有水平间距。

二、右上的是程序运行后缩小后窗口（最小窗口）

——(1) 在水平方向，4个标签部件宽度会随窗口缩小而自适应调整，均匀填满窗口可用宽度；

——(2) 在垂直方向，4个标签部件高度会随窗口缩小而自适应调整，填满窗口可用高度；

——(3) 在缩小时，标签四周的边框（左、上、右、下边框值）以及4个标签之间的水平间距始终保持不变。

三、下面的是程序运行后拉伸后的窗口

——(1) 在水平方向，4个标签部件宽度会随窗口拉伸而自适应调整，均匀填满窗口可用宽度；

——(2) 在垂直方向，4个标签部件高度会随窗口拉伸而自适应调整，填满窗口可用高度；

——(3) 在拉伸时，标签四周的边框（左、上、右、下边框值）以及4个标签之间的水平间距始终保持不变。

注1：布局具有边框属性（左、上、右、下边框值），布局内部各个子部件之间具有间距属性（水平方向为水平间距，垂直方向为垂直间距），通常情况下，边框属性和间距属性均有默认值，所以我们能看到四周的边框，以及各部件之间的间距。

注2：可以通过调用布局对象的 setContentsMargins(left, top, right, bottom) 方法来设置4个方向（左、上、右、下）上的边框值，可以通过调用布局对象的 setSpacing(spacing) 方法来设置布局中各个部件之间的间距值。有关更多边框和间距的内容会在后续文章中加以介绍。

结束语

本文是《Qt for Python 学习笔记》系列第九篇，较为详细地介绍了 Qt for Python 的盒式布局及其子类水平布局，让读者对 Qt for Python 水平布局有个较为基本的了解和掌握。

接下来会继续介绍 Qt for Python 布局管理中的垂直布局，敬请期待！

希望本文能对您有所帮助！若文中存在疏忽不足或错误，还请不吝赐教！