PyQt5 基础与常用控件入门教程

1.4 代码详细解释

• import sys：提供与 Python 解释器交互的功能，sys.exit() 确保程序关闭时干净退出。
• QApplication：每个 PyQt5 程序必须有一个实例，管理控制流和设置。
• QMainWindow：主窗口类，可包含菜单栏、工具栏等复杂结构。
• QLabel：用于显示文本的基础控件。
• setCentralWidget(label)：将标签填充到窗口中间区域。
• app.exec_()：启动事件循环，保持程序运行直到关闭窗口。

1.5 在 PyCharm 中运行程序

确保代码保存后，点击顶部的绿色 Run 按钮即可看到窗口弹出。

1.6 常见问题排查

• 未安装 PyQt5：检查 pip list 确认环境。
• 解释器配置错误：确保 PyCharm 使用的 Python 版本与安装路径一致。
• 窗口不显示：检查是否调用了 window.show()。

1.7 总结

PyQt5 功能强大，适合创建桌面应用。通过几行代码即可搭建基本窗口框架。

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

2.1 PyQt5 的基本窗口结构

窗口是应用程序的核心。除了显示内容，我们还需要学习如何组织多个控件，使界面更具交互性和美观性。

2.2 基本的 PyQt5 窗口与布局

QWidget 与 QMainWindow 的区别

• QWidget：所有控件的基类，最基础的窗口控件。
• QMainWindow：高级窗口控件，继承自 QWidget，具备菜单栏、状态栏等功能。

2.3 布局管理器

布局管理器让控件自动调整位置和大小，常见的有：

1. QVBoxLayout：垂直排列（从上到下）。
2. QHBoxLayout：水平排列（从左到右）。
3. QGridLayout：网格排列。
4. QFormLayout：表单排列。

2.4 在窗口中使用布局管理器

我们来组合使用 QVBoxLayout 和 QHBoxLayout 组织控件。

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_())

要点解析：

• QMainWindow 需要设置中央控件 (setCentralWidget)。
• 布局可以嵌套，例如将水平布局放入垂直布局中，实现灵活排版。

2.5 更多布局管理器介绍

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()
        
        # 添加控件到特定行列 (row, column)
        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_())

2.6 总结

本部分介绍了 QVBoxLayout、QHBoxLayout 和 QGridLayout 的使用。掌握这些布局管理器，无需手动计算坐标即可让界面自适应。

第 3 部分：常用控件详解

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_())

3.6 总结

介绍了 QLabel、QPushButton、QLineEdit、QCheckBox 和 QComboBox。这些控件构成了 GUI 应用的基础交互元素。

1-3 部分总结

前三部分涵盖了 PyQt5 的基础知识。从安装环境开始，创建了第一个窗口，学习了布局管理器来组织界面，最后深入探讨了常用控件及其信号槽机制。这些内容是构建复杂 Python 桌面应用的基石。