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

1.4 代码详解

• import sys：提供与 Python 解释器交互的功能，sys.exit() 确保程序正常退出。
• QApplication：每个 PyQt5 程序必须有一个实例，管理控制流和设置。
• QMainWindow：主窗口类，可包含菜单栏、工具栏等。
• QLabel：显示文本的简单控件。
• setCentralWidget：将控件设置为窗口的中央区域。
• app.exec_()：启动事件循环，保持程序运行直到关闭。

1.5 常见问题排查

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

2. 创建应用程序与布局管理

2.1 基本窗口结构

窗口是应用程序的核心。除了简单的 QMainWindow，我们还需要学习如何组织多个控件，使界面更具交互性。

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

说明：我们将水平布局嵌入到垂直布局中，实现更复杂的结构。

2.5 QGridLayout 网格布局

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

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

总结

本教程介绍了 PyQt5 的基础知识和常用控件。从安装配置开始，讲解了窗口结构与布局管理器的使用，涵盖了 QVBoxLayout、QHBoxLayout 和 QGridLayout。最后深入探讨了 QLabel、QPushButton、QLineEdit、QCheckBox 和 QComboBox 等核心控件的事件处理与交互逻辑。这些内容是构建桌面 GUI 应用的基础。