📚 课程目录第4章窗口与布局

4、窗口与布局：QMainWindow、QDialog、QWidget 的区别，布局管理器（QHBoxLayout、QVBoxLayout、QGridLayout）实战

在 PySide6 项目中，窗口类型的选择与布局管理器的运用，直接决定了应用的结构骨架与界面质量。许多初学者在创建第一个窗口时，往往随意继承 QWidget 或 QMainWindow，导致后续添加菜单栏、状态栏时不得不重构代码；而在摆放控件时，又习惯使用 move() 进行定位，结果窗口一拉伸，控件便乱作一团。本章将系统梳理三种窗口基类的适用场景，并通过实战案例演示三种核心布局管理器的组合用法，帮助你在项目启动阶段就搭建出结构清晰、自适应良好的界面框架。

4.1 三种窗口基类的核心原理与选型判断

PySide6 中所有界面组件都继承自 QWidget，但 QMainWindow、QDialog 和 QWidget 作为三个最常用的顶层窗口基类，各自承担着不同的职责。理解它们的内部结构差异，是避免项目后期重构的关键。

QMainWindow 是“主窗口框架”，它内置了一套完整的窗口布局体系：顶部菜单栏（Menu Bar）、四周工具栏（Tool Bar）、底部状态栏（Status Bar）、中央部件区（Central Widget）以及可选的 Dock 停靠窗口。这套结构是 Qt 为桌面应用主界面量身定制的，但它的中央部件区必须显式设置一个 setCentralWidget()，不能直接往 QMainWindow 上添加子控件。如果你尝试在 QMainWindow 上直接 addWidget()，会得到错误提示，因为 QMainWindow 本身不是普通容器。

QDialog 是“对话框窗口”，专为短时交互设计。它没有菜单栏和状态栏，但提供了 exec() 方法实现模态阻塞——即对话框弹出后，用户必须处理完才能返回主窗口。QDialog 还内置了 accept()、reject() 信号，配合 QDialogButtonBox 可以快速实现“确定/取消”逻辑。对话框通常不嵌入主窗口，而是作为独立窗口弹出。

QWidget 是“空白画布”，它是最纯粹的容器，没有预置任何框架结构。你可以将 QWidget 作为独立窗口显示，也可以将其作为 QMainWindow 的中央部件，或者作为其他布局中的子组件。QWidget 的灵活性最高，但需要开发者自己搭建所有结构。

对比维度	QMainWindow	QDialog	QWidget
内置框架	菜单栏、工具栏、状态栏、Dock	无，但支持按钮盒	无任何预置结构
模态支持	不直接支持	支持 exec() 模态阻塞	需手动设置 windowModality
典型用途	应用主窗口	设置、确认、文件选择	自定义组件、嵌入式面板
添加子控件	必须 setCentralWidget()	直接 setLayout()	直接 setLayout()
关闭行为	close() 退出应用	reject() 返回结果	close() 仅隐藏窗口

选型判断流程：首先问自己“这个窗口是应用的主界面吗？”如果是，选择 QMainWindow；如果只是临时交互，选择 QDialog；如果是一个可复用的自定义组件（如视频播放面板、图表控件），选择 QWidget。一个常见误区是“所有窗口都用 QMainWindow”，这会导致对话框也出现菜单栏，界面显得笨重。

经验提醒：在 PySide6 项目中，建议主窗口继承 QMainWindow，所有弹窗继承 QDialog，所有自定义组件继承 QWidget。这种“三分法”能让代码结构一目了然，也便于团队协作时快速理解每个类的职责。

4.2 布局管理器：从定位到弹性布局

布局管理器（Layout Manager）是 Qt 界面自动适应窗口尺寸的核心机制。它负责计算每个子控件的位置和大小，并在窗口缩放时自动调整。PySide6 提供了三种基础布局：QHBoxLayout（水平）、QVBoxLayout（垂直）和 QGridLayout（网格），它们可以互相嵌套，形成复杂的界面结构。

QHBoxLayout 水平布局将控件按从左到右的顺序排列。它适合放置一组功能相关的按钮（如“确定”“取消”），或者“标签+输入框”的横向组合。水平布局支持 addStretch() 添加弹性空白，将控件推向左侧或右侧；也支持 setStretchFactor() 控制不同控件的伸缩比例。

QVBoxLayout 垂直布局将控件从上到下排列，常用于表单页面（每个字段占一行）或日志输出面板。垂直布局与水平布局的 API 完全对称，可以互相嵌套——例如一个垂直布局中包含两个水平布局，就能实现“两行两列”的效果。

QGridLayout 网格布局将窗口划分为行和列，控件可以放置在任意单元格中，还支持跨行跨列（addWidget(widget, row, col, rowSpan, colSpan)）。网格布局特别适合表单（标签在左列，输入框在右列）或仪表盘（多个面板按矩阵排列）。

# 三种布局的典型用法
from PySide6.QtWidgets import (QApplication, QWidget, QPushButton,
                               QHBoxLayout, QVBoxLayout, QGridLayout, QLabel, QLineEdit)

# 水平布局：按钮组
h_layout = QHBoxLayout()
h_layout.addWidget(QPushButton("确定"))
h_layout.addWidget(QPushButton("取消"))
h_layout.addStretch()  # 将按钮推到左侧

# 垂直布局：表单
v_layout = QVBoxLayout()
v_layout.addWidget(QLabel("用户名:"))
v_layout.addWidget(QLineEdit())
v_layout.addStretch()  # 底部弹性空白

# 网格布局：两行两列
grid = QGridLayout()
grid.addWidget(QLabel("姓名:"), 0, 0)
grid.addWidget(QLineEdit(), 0, 1)
grid.addWidget(QLabel("邮箱:"), 1, 0)
grid.addWidget(QLineEdit(), 1, 1)

布局嵌套原则：一个布局可以包含另一个布局（通过 addLayout()），但不能同时属于两个父布局。每个 QWidget 只能设置一个顶层布局（setLayout()），但该布局内部可以无限嵌套。合理的嵌套策略是：先确定整体是垂直还是水平方向，再在每一层细分。

风险提示：不要对同一个控件同时使用布局管理和 move() 定位。布局管理器会覆盖手动设置的位置和尺寸，导致界面行为不可预测。如果某个控件需要固定大小，使用 setFixedSize() 或 setMaximumSize()，而不是手动移动。

4.3 实战案例：构建一个用户信息录入对话框

下面通过一个完整的案例，演示如何将三种窗口基类和三种布局管理器组合使用。我们将构建一个“用户信息录入”对话框，包含姓名、邮箱、年龄三个字段，以及“保存”和“取消”按钮。这个对话框将作为 QDialog 弹出，内部使用 QGridLayout 排列表单，使用 QHBoxLayout 排列按钮。

案例背景与约束：项目需要一个用户管理模块，要求录入界面简洁、可缩放、支持回车键提交。初始设计时，团队曾尝试用 QWidget 作为独立窗口，但发现无法方便地实现模态阻塞；后来改用 QDialog，通过 exec() 完美解决了“必须处理完才能返回”的需求。

关键实现步骤：

创建 UserDialog(QDialog) 类，构造函数中初始化界面。
使用 QGridLayout 放置三个“标签+输入框”组合，设置列拉伸比例（第 0 列固定，第 1 列可伸缩）。
使用 QHBoxLayout 放置“保存”“取消”按钮，并添加弹性空白使按钮右对齐。
将按钮布局通过 addLayout() 添加到网格布局的最后一行。
连接“保存”按钮的 clicked 信号到 accept()，“取消”按钮连接到 reject()。

from PySide6.QtWidgets import (QDialog, QGridLayout, QHBoxLayout,
                               QLabel, QLineEdit, QPushButton, QMessageBox)

class UserDialog(QDialog):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.setWindowTitle("用户信息录入")
        self.setMinimumWidth(400)
        
        # 创建控件
        self.name_edit = QLineEdit()
        self.email_edit = QLineEdit()
        self.age_edit = QLineEdit()
        self.save_btn = QPushButton("保存")
        self.cancel_btn = QPushButton("取消")
        
        # 网格布局：表单区域
        grid = QGridLayout()
        grid.addWidget(QLabel("姓名:"), 0, 0)
        grid.addWidget(self.name_edit, 0, 1)
        grid.addWidget(QLabel("邮箱:"), 1, 0)
        grid.addWidget(self.email_edit, 1, 1)
        grid.addWidget(QLabel("年龄:"), 2, 0)
        grid.addWidget(self.age_edit, 2, 1)
        grid.setColumnStretch(1, 1)  # 第1列可伸缩
        
        # 水平布局：按钮区域
        btn_layout = QHBoxLayout()
        btn_layout.addStretch()
        btn_layout.addWidget(self.save_btn)
        btn_layout.addWidget(self.cancel_btn)
        
        # 将按钮布局添加到网格第3行，跨2列
        grid.addLayout(btn_layout, 3, 0, 1, 2)
        
        # 设置对话框主布局
        self.setLayout(grid)
        
        # 信号连接
        self.save_btn.clicked.connect(self.validate_and_accept)
        self.cancel_btn.clicked.connect(self.reject)
    
    def validate_and_accept(self):
        if not self.name_edit.text().strip():
            QMessageBox.warning(self, "提示", "姓名不能为空")
            return
        if not self.email_edit.text().strip():
            QMessageBox.warning(self, "提示", "邮箱不能为空")
            return
        self.accept()

结果与效果：运行后，对话框弹出时主窗口不可操作（模态）。用户填写信息后点击“保存”，对话框关闭并返回 Accepted 状态；点击“取消”则返回 Rejected。窗口拉伸时，输入框会随宽度扩展，而标签和按钮保持固定宽度，界面始终整洁。

风险与代价：网格布局中如果忘记设置 setColumnStretch()，输入框不会随窗口拉伸，界面会显得局促。此外，年龄字段没有做数字校验，实际项目中应使用 QIntValidator 或正则表达式限制输入。

  复盘经验：布局嵌套时，先画一个简单的草图，标注哪些区域是水平、哪些是垂直、哪些是网格。这个案例中，整体是网格布局，但按钮区域内部是水平布局——这种“网格+水平”的组合非常常见。另外，addLayout() 返回的布局对象不需要保存引用，因为父布局已经持有它。

4.4 常见误区与调优建议

误区一：所有窗口都用 QMainWindow。这会导致对话框出现多余的菜单栏和状态栏，且无法使用 exec() 模态功能。正确做法是：主窗口用 QMainWindow，弹窗用 QDialog。

误区二：布局管理器只能用于 QWidget。实际上，QMainWindow 的中央部件必须是一个 QWidget，你可以在该 QWidget 上设置任意布局。QDialog 同样可以直接 setLayout()。布局管理器适用于所有 QWidget 子类。

误区三：忽略伸缩因子。默认情况下，布局中的控件会按大小提示分配空间，但不会自动伸缩。如果希望某个控件占据多余空间，必须调用 setStretchFactor() 或使用 addStretch()。例如，在 QHBoxLayout 中，如果希望输入框占据所有剩余宽度，可以设置 setStretchFactor(input_widget, 1)。

误区四：嵌套布局时忘记设置父对象。使用 addLayout() 时，子布局会自动设置父布局，无需手动指定。但如果你先创建了一个布局，再将其添加到另一个布局，必须使用 addLayout() 而不是 addWidget()。

调优建议：

使用 setContentsMargins() 控制布局与窗口边缘的间距，默认值在不同平台可能不一致。
使用 setSpacing() 统一控件间距，避免每个控件单独设置 margin。
对于复杂界面，优先使用 QGridLayout 而不是多层嵌套的 QHBoxLayout/QVBoxLayout，因为网格布局更易维护。
在窗口尺寸变化时，如果布局计算开销较大，可以暂时调用 setUpdatesEnabled(False) 暂停重绘，调整完成后再恢复。

排障提示：如果发现控件没有按预期排列，首先检查是否调用了 setLayout()。其次，检查是否有控件被重复添加到多个布局中——一个控件只能有一个父布局。最后，确认没有在布局设置之后又调用 move() 或 resize()，这些操作会被布局管理器覆盖。

通过本章的学习，你应该能够根据项目需求正确选择窗口基类，并熟练运用三种布局管理器构建自适应界面。记住：窗口类型决定“骨架”，布局管理器决定“血肉”，两者配合才能打造出专业、稳定的 PySide6 应用。