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

1.5 常见问题排查

• 未安装 PyQt5：检查 pip list 输出。
• 解释器不一致：确保 PyCharm 使用的 Python 环境与安装包的版本一致。
• 窗口不显示：确认调用了 window.show()。

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

2.1 基本窗口结构

窗口是 GUI 的核心。除了基础的 QMainWindow，我们还需要了解如何组织多个控件，这就要用到布局管理器。

2.2 QWidget 与 QMainWindow 的区别

• QWidget：所有 UI 控件的基类，最基础的窗口容器。
• QMainWindow：继承自 QWidget，专为复杂应用设计，支持菜单栏、状态栏等。

2.3 布局管理器

手动计算坐标既繁琐又难以适配不同分辨率。PyQt5 提供了自动布局方案：

• QVBoxLayout：垂直排列（从上到下）。
• QHBoxLayout：水平排列（从左到右）。
• QGridLayout：网格排列（行/列）。
• QFormLayout：表单式排列（标签 + 输入框）。

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

下面是一个组合布局的示例，包含标签和两个按钮：

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)

if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = MainWindow()
    window.show()
    sys.exit(app.exec_())

解析：我们将水平布局嵌入垂直布局中，实现了灵活的界面结构。控件会自动根据窗口大小调整位置。

2.6 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)

if __name__ == "__main__":
    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)

if __name__ == "__main__":
    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("按钮被点击！")

if __name__ == "__main__":
    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.line_edit.returnPressed.connect(self.return_pressed)
        self.setCentralWidget(self.line_edit)

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

if __name__ == "__main__":
    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("复选框未被勾选")

if __name__ == "__main__":
    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}")

if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = MainWindow()
    window.show()
    sys.exit(app.exec_())

总结

本章节介绍了 PyQt5 的基础知识，包括安装、窗口结构、布局管理以及 QLabel、QPushButton、QLineEdit 等核心控件的使用。掌握了这些内容，你就具备了构建基础桌面应用的能力。后续可以进一步学习信号槽的高级用法、自定义样式及多线程处理。