PyQt5 入门实战：环境搭建、布局与常用控件详解

1.5 常见问题排查

• 无法运行：检查解释器是否正确安装了 PyQt5。
• 窗口不显示：确认调用了 window.show()。
• 报错：确保 Python 版本与 PyQt5 兼容。

第二部分：创建应用程序与布局管理

2.1 基本窗口结构

在 PyQt5 中，QWidget 是所有控件的基类，而 QMainWindow 提供了菜单栏、工具栏等高级功能。通常，我们使用 QMainWindow 作为主容器，并在其中设置一个 QWidget 作为中央部件来放置其他控件。

2.2 布局管理器

手动计算坐标非常繁琐，布局管理器能自动调整控件位置。常用类型包括：

• QVBoxLayout：垂直排列。
• QHBoxLayout：水平排列。
• QGridLayout：网格排列。
• QFormLayout：表单式排列。

2.3 布局嵌套示例

我们可以组合使用垂直和水平布局来实现复杂界面：

import sys
from PyQt5.QtWidgets import QApplication, QMainWindow, QWidget, QVBoxLayout, QHBoxLayout, QPushButton, QLabel

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("PyQt5 布局示例")
        
        # 设置中央控件
        central_widget = QWidget(self)
        self.setCentralWidget(central_widget)
        
        # 垂直布局
        vbox_layout = QVBoxLayout()
        label = QLabel("这是一个标签")
        vbox_layout.addWidget(label)
        
        # 水平布局
        hbox_layout = QHBoxLayout()
        button1 = QPushButton("按钮 1")
        button2 = QPushButton("按钮 2")
        hbox_layout.addWidget(button1)
        hbox_layout.addWidget(button2)
        
        # 嵌套布局
        vbox_layout.addLayout(hbox_layout)
        central_widget.setLayout(vbox_layout)

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec_())

这里的关键在于 addLayout 方法，它将水平布局嵌入到垂直布局中，实现了灵活的界面结构。

2.4 网格布局 (QGridLayout)

对于需要精确行列控制的场景，网格布局非常有用：

from PyQt5.QtWidgets import QApplication, QWidget, QGridLayout, QLabel, QPushButton
import sys

class MainWindow(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QGridLayout 示例")
        layout = QGridLayout()
        
        layout.addWidget(QLabel("标签 1"), 0, 0)
        layout.addWidget(QPushButton("按钮 1"), 0, 1)
        layout.addWidget(QLabel("标签 2"), 1, 0)
        layout.addWidget(QPushButton("按钮 2"), 1, 1)
        
        self.setLayout(layout)

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec_())

通过指定 (row, column) 坐标，可以精准控制每个控件的位置。

第三部分：常用控件详解

3.1 QLabel（标签）

用于显示文本或图片。可设置对齐方式、字体等属性。

from PyQt5.QtWidgets import QApplication, QLabel, QMainWindow
from PyQt5.QtCore import Qt
import sys

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QLabel 示例")
        label = QLabel("这是一个标签", self)
        label.setAlignment(Qt.AlignCenter)
        self.setCentralWidget(label)

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec_())

3.2 QPushButton（按钮）

触发交互的核心控件。需连接信号与槽函数来处理点击事件。

from PyQt5.QtWidgets import QApplication, QMainWindow, QPushButton
import sys

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QPushButton 示例")
        button = QPushButton("点击我", self)
        button.clicked.connect(self.button_clicked)
        self.setCentralWidget(button)

    def button_clicked(self):
        print("按钮被点击！")

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec_())

3.3 QLineEdit（单行文本框）

获取用户输入的文本，支持占位符提示。

from PyQt5.QtWidgets import QApplication, QMainWindow, QLineEdit
import sys

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QLineEdit 示例")
        self.line_edit = QLineEdit(self)
        self.line_edit.setPlaceholderText("请输入文本")
        self.setCentralWidget(self.line_edit)
        self.line_edit.returnPressed.connect(self.return_pressed)

    def return_pressed(self):
        text = self.line_edit.text()
        print(f"用户输入：{text}")

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec_())

3.4 QCheckBox（复选框）

用于多选状态，监听状态变化信号。

from PyQt5.QtWidgets import QApplication, QMainWindow, QCheckBox
from PyQt5.QtCore import Qt
import sys

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QCheckBox 示例")
        self.checkbox = QCheckBox("同意条款", self)
        self.checkbox.stateChanged.connect(self.checkbox_changed)
        self.setCentralWidget(self.checkbox)

    def checkbox_changed(self, state):
        if state == Qt.Checked:
            print("复选框被勾选")
        else:
            print("复选框未被勾选")

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec_())

3.5 QComboBox（下拉列表）

提供选项选择，适合固定集合的输入。

from PyQt5.QtWidgets import QApplication, QMainWindow, QComboBox
import sys

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QComboBox 示例")
        self.combobox = QComboBox(self)
        self.combobox.addItems(["选项 1", "选项 2", "选项 3"])
        self.combobox.currentIndexChanged.connect(self.combobox_changed)
        self.setCentralWidget(self.combobox)

    def combobox_changed(self, index):
        text = self.combobox.currentText()
        print(f"当前选中：{text}")

app = QApplication(sys.argv)
window = MainWindow()
window.show()
sys.exit(app.exec_())

总结

本文介绍了 PyQt5 的基础知识，包括环境配置、窗口架构、布局管理器的使用以及 Label、Button、LineEdit 等常用控件的实战代码。掌握了这些内容，你就具备了构建基础桌面应用的能力。后续可以进一步学习信号与槽的高级用法、自定义样式表以及多线程处理等内容。