PyQt5自定义信号：跨窗口通信与多线程进度传递（完整代码）

寒烟似雪
寒烟似雪
5天前发布 /正在检测是否收录...
0 7 0

第12篇：PyQt5自定义信号：满足复杂交互与跨组件通信需求（完整代码）

哈喽～ 欢迎来到PyQt5系列的第12篇！上一章我们吃透了内置信号与槽的基础用法和进阶技巧，但在实际开发中，内置信号往往无法满足复杂场景（比如两个窗口之间传递数据、自定义控件的状态变化、多线程间的进度通知）。今天我们就来学习自定义信号——PyQt5中实现跨组件、跨线程通信的核心武器，全程搭配完整可运行代码，帮你彻底掌握自定义信号的定义、发射与绑定逻辑！
mk7oiwng.png

一、先明确：自定义信号的核心使用场景

当以下场景出现时，内置信号就不够用了，必须用自定义信号：

  1. 跨窗口通信：主窗口和子窗口之间传递数据（如子窗口输入的内容同步到主窗口）；
  2. 自定义控件：开发自己的控件（如自定义进度条），需要向外发送状态变化信号；
  3. 多线程通信：子线程不能直接操作主界面，需通过自定义信号将数据传递给主线程；
  4. 复杂业务逻辑：业务状态变化（如支付成功、数据加载完成）需要触发多个槽函数响应。

自定义信号的核心规则（必记！）

  1. 自定义信号必须定义在继承自QObject的类中（PyQt5所有控件都继承了QObject，所以自定义窗口类也可以）；
  2. 自定义信号是类属性，需用pyqtSignal()方法创建，不能在__init__中定义；
  3. 信号通过emit()方法发射，发射时的参数必须与信号定义的参数类型一致；
  4. 自定义信号同样支持connect()绑定槽函数、disconnect()断开绑定。

二、自定义信号的基础用法：定义、发射与绑定

1. 无参数自定义信号（基础入门）

先从最简单的无参数自定义信号入手，掌握“定义→发射→绑定”的核心流程。

完整代码：无参数自定义信号

import sys
from PyQt5.QtWidgets import QApplication, QWidget, QVBoxLayout, QPushButton, QLabel
from PyQt5.QtCore import QObject, pyqtSignal

# 自定义信号的载体类（必须继承QObject）
# 注意：如果是自定义窗口类，本身继承QWidget（已继承QObject），可直接在窗口类中定义信号
class MySignal(QObject):
    # 定义无参数的自定义信号，类属性
    custom_signal = pyqtSignal()

class SignalDemo(QWidget):
    def __init__(self):
        super().__init__()
        self.init_ui()
        self.init_signal()

    def init_ui(self):
        self.setWindowTitle("无参数自定义信号演示")
        self.resize(350, 200)

        layout = QVBoxLayout()
        self.label = QLabel("信号未触发", alignment=1)
        self.trigger_btn = QPushButton("点击发射自定义信号")

        layout.addWidget(self.label)
        layout.addWidget(self.trigger_btn)
        self.setLayout(layout)

    def init_signal(self):
        # 1. 创建自定义信号的实例
        self.my_signal = MySignal()

        # 2. 绑定自定义信号到槽函数
        self.my_signal.custom_signal.connect(self.on_custom_signal_trigger)

        # 3. 绑定按钮点击信号，触发自定义信号的发射
        self.trigger_btn.clicked.connect(self.emit_custom_signal)

    def emit_custom_signal(self):
        """发射自定义信号"""
        print("按钮点击，准备发射自定义信号...")
        # 核心方法：emit() 发射信号
        self.my_signal.custom_signal.emit()

    def on_custom_signal_trigger(self):
        """自定义信号的槽函数"""
        self.label.setText("自定义信号触发成功！")
        print("自定义信号槽函数执行完成")

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

核心步骤解析

  1. 定义信号：在继承QObject的类中，用pyqtSignal()创建类属性custom_signal，这就是自定义信号；
  2. 创建信号实例：在窗口类中实例化MySignal，得到信号载体；
  3. 绑定槽函数：用custom_signal.connect(槽函数)将信号与响应逻辑绑定；
  4. 发射信号：通过custom_signal.emit()发射信号，触发槽函数执行。

2. 带参数的自定义信号（高频实战）

大多数场景下，信号需要传递数据（如文本、数值、对象），这就需要定义带参数的自定义信号。pyqtSignal()支持指定参数类型（如int、str、tuple等），发射时必须传递对应类型的参数。

完整代码：带参数的自定义信号

import sys
from PyQt5.QtWidgets import QApplication, QWidget, QVBoxLayout, QPushButton, QLabel, QLineEdit
from PyQt5.QtCore import pyqtSignal  # 窗口类已继承QObject，可直接定义信号

class ParamSignalDemo(QWidget):
    # 定义带参数的自定义信号：支持多种参数类型
    # 格式：pyqtSignal(参数类型1, 参数类型2, ...)
    text_signal = pyqtSignal(str)  # 传递字符串
    num_signal = pyqtSignal(int, str)  # 传递整数+字符串
    dict_signal = pyqtSignal(dict)  # 传递字典

    def __init__(self):
        super().__init__()
        self.init_ui()
        self.bind_signals()

    def init_ui(self):
        self.setWindowTitle("带参数自定义信号演示")
        self.resize(400, 300)

        layout = QVBoxLayout()
        self.edit = QLineEdit()
        self.edit.setPlaceholderText("输入文本，点击按钮发射信号")
        self.label1 = QLabel("字符串信号：未触发", alignment=1)
        self.label2 = QLabel("整数+字符串信号：未触发", alignment=1)
        self.label3 = QLabel("字典信号：未触发", alignment=1)
        self.btn = QPushButton("发射所有带参数信号")

        layout.addWidget(self.edit)
        layout.addWidget(self.label1)
        layout.addWidget(self.label2)
        layout.addWidget(self.label3)
        layout.addWidget(self.btn)
        self.setLayout(layout)

    def bind_signals(self):
        """绑定自定义信号到槽函数"""
        self.text_signal.connect(self.on_text_signal)
        self.num_signal.connect(self.on_num_signal)
        self.dict_signal.connect(self.on_dict_signal)
        self.btn.clicked.connect(self.emit_param_signals)

    def emit_param_signals(self):
        """发射带参数的自定义信号"""
        input_text = self.edit.text().strip() or "默认文本"
        # 发射信号：参数类型必须与定义一致
        self.text_signal.emit(input_text)  # 传递字符串
        self.num_signal.emit(2026, input_text)  # 传递整数+字符串
        self.dict_signal.emit({"name": input_text, "year": 2026})  # 传递字典

    # 对应不同参数的槽函数
    def on_text_signal(self, text):
        self.label1.setText(f"字符串信号：{text}")

    def on_num_signal(self, num, text):
        self.label2.setText(f"整数+字符串信号：{num} | {text}")

    def on_dict_signal(self, data):
        self.label3.setText(f"字典信号：{data}")

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

关键要点

  1. 信号参数定义：pyqtSignal(str)表示信号传递字符串，pyqtSignal(int, str)表示传递两个参数（整数+字符串），支持Python基本数据类型和自定义对象；
  2. 发射参数匹配：emit()的参数数量和类型必须与信号定义完全一致，否则会触发TypeError；
  3. 槽函数接收参数：槽函数的参数数量要与信号传递的参数数量一致，顺序对应。

三、实战案例1：主窗口与子窗口的跨窗口通信

跨窗口通信是自定义信号最常用的场景之一。比如点击主窗口按钮弹出子窗口，子窗口输入内容后，通过自定义信号将数据传递回主窗口并显示。

步骤1：定义子窗口类（含自定义信号）

子窗口负责接收用户输入，输入完成后发射自定义信号传递数据。

# 子窗口类
from PyQt5.QtWidgets import QDialog, QVBoxLayout, QLineEdit, QPushButton, QLabel
from PyQt5.QtCore import pyqtSignal

class ChildWindow(QDialog):
    # 定义自定义信号：传递用户输入的文本
    child_signal = pyqtSignal(str)

    def __init__(self, parent=None):
        super().__init__(parent)
        self.init_ui()

    def init_ui(self):
        self.setWindowTitle("子窗口（输入数据）")
        self.setFixedSize(300, 200)

        layout = QVBoxLayout()
        self.edit = QLineEdit()
        self.edit.setPlaceholderText("请输入要传递的内容")
        self.confirm_btn = QPushButton("确认并传递给主窗口")

        layout.addWidget(self.edit)
        layout.addWidget(self.confirm_btn)
        self.setLayout(layout)

        # 绑定按钮点击信号，发射自定义信号
        self.confirm_btn.clicked.connect(self.on_confirm)

    def on_confirm(self):
        input_text = self.edit.text().strip()
        if input_text:
            # 发射信号，传递输入内容
            self.child_signal.emit(input_text)
            self.close()  # 关闭子窗口
        else:
            QLabel("请输入内容！").show()

步骤2：定义主窗口类（接收子窗口信号）

主窗口点击按钮弹出子窗口，绑定子窗口的自定义信号，接收数据并显示。

import sys
from PyQt5.QtWidgets import QApplication, QWidget, QVBoxLayout, QPushButton, QLabel
from PyQt5.QtCore import Qt

class MainWindow(QWidget):
    def __init__(self):
        super().__init__()
        self.init_ui()

    def init_ui(self):
        self.setWindowTitle("主窗口（接收子窗口数据）")
        self.resize(400, 250)

        layout = QVBoxLayout()
        self.result_label = QLabel("子窗口传递的数据：无", alignment=Qt.AlignCenter)
        self.result_label.setStyleSheet("font-size: 16px; color: #2ecc71;")
        self.open_child_btn = QPushButton("打开子窗口")

        layout.addWidget(self.result_label)
        layout.addWidget(self.open_child_btn)
        self.setLayout(layout)

        # 绑定按钮点击信号，打开子窗口
        self.open_child_btn.clicked.connect(self.open_child_window)

    def open_child_window(self):
        # 创建子窗口实例
        self.child_win = ChildWindow(self)
        # 绑定子窗口的自定义信号到槽函数
        self.child_win.child_signal.connect(self.on_child_data_received)
        # 显示子窗口（模态）
        self.child_win.exec_()

    def on_child_data_received(self, data):
        """接收子窗口传递的数据"""
        self.result_label.setText(f"子窗口传递的数据：{data}")

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

案例核心亮点

  1. 子窗口信号定义：子窗口类中定义child_signal = pyqtSignal(str)，用于传递输入文本；
  2. 跨窗口信号绑定：主窗口创建子窗口后，通过child_win.child_signal.connect()绑定槽函数，实现数据监听；
  3. 模态窗口通信：子窗口用exec_()显示为模态窗口，用户操作完子窗口后，数据同步回主窗口。

四、实战案例2：多线程中用自定义信号传递进度（避免界面卡顿）

PyQt5中子线程不能直接操作主界面控件，否则会导致界面卡顿甚至崩溃。正确的做法是：子线程执行耗时任务，通过自定义信号将进度传递给主线程，主线程更新界面。

完整代码：多线程进度传递

import sys
import time
from PyQt5.QtWidgets import QApplication, QWidget, QVBoxLayout, QPushButton, QProgressBar, QLabel
from PyQt5.QtCore import pyqtSignal, QThread, Qt

# 自定义子线程类：执行耗时任务，发射进度信号
class WorkThread(QThread):
    # 定义自定义信号：传递进度值（整数）
    progress_signal = pyqtSignal(int)
    # 定义任务完成信号
    finish_signal = pyqtSignal(str)

    def __init__(self, total_steps=100):
        super().__init__()
        self.total_steps = total_steps
        self.is_running = True

    def run(self):
        """线程执行的核心方法：耗时任务"""
        for step in range(1, self.total_steps + 1):
            if not self.is_running:
                break
            # 模拟耗时操作（如文件下载、数据处理）
            time.sleep(0.05)
            # 发射进度信号
            self.progress_signal.emit(step)
        # 任务完成，发射完成信号
        self.finish_signal.emit("任务执行完成！" if self.is_running else "任务被取消！")

    def stop(self):
        """停止线程"""
        self.is_running = False

# 主窗口类：显示进度条，控制线程
class ThreadSignalDemo(QWidget):
    def __init__(self):
        super().__init__()
        self.init_ui()
        self.thread = None  # 线程实例

    def init_ui(self):
        self.setWindowTitle("多线程自定义信号传递进度")
        self.resize(400, 250)

        layout = QVBoxLayout()
        self.progress_bar = QProgressBar()
        self.progress_bar.setRange(0, 100)
        self.status_label = QLabel("状态：未开始", alignment=Qt.AlignCenter)
        self.start_btn = QPushButton("开始任务")
        self.stop_btn = QPushButton("停止任务")
        self.stop_btn.setEnabled(False)

        layout.addWidget(self.progress_bar)
        layout.addWidget(self.status_label)
        layout.addWidget(self.start_btn)
        layout.addWidget(self.stop_btn)
        self.setLayout(layout)

        # 绑定按钮信号
        self.start_btn.clicked.connect(self.start_task)
        self.stop_btn.clicked.connect(self.stop_task)

    def start_task(self):
        """启动子线程"""
        self.start_btn.setEnabled(False)
        self.stop_btn.setEnabled(True)
        self.status_label.setText("状态：任务执行中...")
        # 创建线程实例
        self.thread = WorkThread(total_steps=100)
        # 绑定线程的自定义信号到槽函数
        self.thread.progress_signal.connect(self.update_progress)
        self.thread.finish_signal.connect(self.on_task_finish)
        # 启动线程
        self.thread.start()

    def stop_task(self):
        """停止子线程"""
        if self.thread and self.thread.isRunning():
            self.thread.stop()
            self.status_label.setText("状态：任务停止中...")

    def update_progress(self, step):
        """更新进度条（主线程执行）"""
        self.progress_bar.setValue(step)

    def on_task_finish(self, msg):
        """任务完成回调"""
        self.status_label.setText(f"状态：{msg}")
        self.progress_bar.setValue(0)
        self.start_btn.setEnabled(True)
        self.stop_btn.setEnabled(False)
        # 释放线程资源
        self.thread = None

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

案例核心知识点

  1. 线程信号定义：子线程类WorkThread中定义progress_signal = pyqtSignal(int)，用于传递进度值；
  2. 线程安全通信：子线程在run()方法中执行耗时任务，通过emit()发射进度，主线程的槽函数update_progress()更新进度条，避免了子线程直接操作界面；
  3. 线程控制：通过is_running标志控制线程是否继续执行，stop()方法安全停止线程，避免强制终止导致的资源泄漏。

五、自定义信号的高级用法：重载信号与信号断开

1. 重载信号（支持多种参数类型）

重载信号指同一个信号名支持多种参数类型，比如data_signal既可以传递int，也可以传递str。定义时用元组包裹不同的参数类型组合。

完整代码：重载信号

import sys
from PyQt5.QtWidgets import QApplication, QWidget, QVBoxLayout, QPushButton, QLabel
from PyQt5.QtCore import pyqtSignal

class OverloadSignalDemo(QWidget):
    # 定义重载信号：支持两种参数类型（int）或（str）
    data_signal = pyqtSignal([int], [str])

    def __init__(self):
        super().__init__()
        self.init_ui()
        self.bind_signals()

    def init_ui(self):
        self.setWindowTitle("重载自定义信号演示")
        self.resize(350, 200)

        layout = QVBoxLayout()
        self.label = QLabel("信号未触发", alignment=1)
        self.btn1 = QPushButton("发射整数信号")
        self.btn2 = QPushButton("发射字符串信号")

        layout.addWidget(self.label)
        layout.addWidget(self.btn1)
        layout.addWidget(self.btn2)
        self.setLayout(layout)

    def bind_signals(self):
        # 绑定重载信号：指定参数类型，对应不同槽函数
        self.data_signal[int].connect(self.on_int_signal)
        self.data_signal[str].connect(self.on_str_signal)

        self.btn1.clicked.connect(lambda: self.data_signal[int].emit(2026))
        self.btn2.clicked.connect(lambda: self.data_signal[str].emit("重载信号演示"))

    def on_int_signal(self, num):
        self.label.setText(f"整数信号：{num}")

    def on_str_signal(self, text):
        self.label.setText(f"字符串信号：{text}")

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

2. 自定义信号的断开（disconnect）

和内置信号一样，自定义信号也可以用disconnect()方法断开绑定，适用于动态控制信号是否生效的场景。

关键代码片段

# 断开指定槽函数的绑定
self.data_signal.disconnect(self.on_int_signal)

# 断开该信号的所有绑定槽函数
self.data_signal.disconnect()

六、自定义信号常见问题排查

1. 信号定义后无法发射（最常见！）

  • 问题原因：自定义信号定义在__init__方法中，而非类属性；
  • 解决方案：信号必须是类属性，直接在类中定义（如class MyClass(QObject): signal = pyqtSignal()），不能在__init__里用self.signal = pyqtSignal()。

2. 发射信号时报错TypeError: emit() takes 1 positional argument but 2 were given

  • 问题原因：发射信号的参数数量与信号定义的不一致；
  • 解决方案：检查pyqtSignal()的参数类型和emit()的参数数量，确保完全匹配。

3. 子线程发射信号，主线程槽函数不执行

  • 问题原因1：线程实例被垃圾回收（比如线程是局部变量）；

    • 解决方案：将线程实例设为窗口类的属性（如self.thread = WorkThread()）；

  • 问题原因2：信号未绑定成功（线程启动后才绑定信号）；

    • 解决方案：先绑定信号，再启动线程（connect()要在start()之前）。

4. 跨窗口信号绑定后无响应

  • 问题原因：子窗口实例被销毁（比如子窗口是局部变量，函数执行完后被回收）；
  • 解决方案：将子窗口实例设为主窗口的属性（如self.child_win = ChildWindow()）。

总结

  1. 自定义信号核心流程：定义类属性信号（pyqtSignal()）→ 绑定槽函数（connect()）→ 发射信号（emit()）；
  2. 核心使用场景：跨窗口通信、多线程进度传递、自定义控件状态通知；
  3. 关键注意事项：信号必须是类属性、参数类型要匹配、子线程不能直接操作界面；
  4. 下一章预告：我们将学习PyQt5事件处理——重写事件函数（如鼠标事件、键盘事件），实现更灵活的界面交互逻辑。

如果在自定义信号的使用中遇到跨窗口通信、多线程同步的问题，或者想了解更复杂的信号应用场景，欢迎在评论区留言讨论～

© 版权声明
文章版权归作者所有，未经允许请勿转载。
THE END
pyqt5入门到精通技术干货# pyqt5# pyqt5从入门到精通
喜欢就支持一下吧
点赞 0 分享 收藏
本站资源多为网络收集，如涉及版权问题请及时与站长联系，我们会在第一时间内删除资源。
本站用户发帖仅代表本站用户个人观点，并不代表本站赞同其观点和对其真实性负责。
本站一律禁止以任何方式发布或转载任何违法的相关信息，访客发现请向站长举报。
本站资源大多存储在云盘，如发现链接失效，请及时与站长联系，我们会第一时间更新。
转载本网站任何内容，请按照转载方式正确书写本站原文地址。
版权属于：寒烟似雪
本文链接：https://www.ziyeyao.com/archives/pyqt5-12.html
作品采用《署名-非商业性使用-相同方式共享 4.0 国际 (CC BY-NC-SA 4.0)》许可协议授权
相关推荐
PyQt5阶段三实战项目：多线程文件下载工具（仿迅雷核心功能）
PyQt5阶段三实战项目：多线程文件下载工具（仿迅雷核心功能）
PyQt5阶段三实战项目：多线程文件下载工具（仿迅雷核心功能）
昨天 6
PyQt5多线程编程：解决界面卡顿的核心方案（附下载工具实战）
PyQt5多线程编程：解决界面卡顿的核心方案（附下载工具实战）
PyQt5多线程编程：解决界面卡顿的核心方案（附下载工具实战）
2天前 7
PyQt5事件处理：重写鼠标/键盘/窗口事件函数（附绘图实战）
PyQt5事件处理：重写鼠标/键盘/窗口事件函数（附绘图实战）
PyQt5事件处理：重写鼠标/键盘/窗口事件函数（附绘图实战）
4天前 7
PyQt5信号与槽原理：从基础到进阶（附参数传递代码）
PyQt5信号与槽原理：从基础到进阶（附参数传递代码）
PyQt5信号与槽原理：从基础到进阶（附参数传递代码）
1月6日 6
PyQt5实战项目：简易Excel表格数据管理器（完整可运行代码）
PyQt5实战项目：简易Excel表格数据管理器（完整可运行代码）
PyQt5实战项目：简易Excel表格数据管理器（完整可运行代码）
1月5日 7
PyQt5容器控件：QTabWidget与QGroupBox（附多功能窗口实战）
PyQt5容器控件：QTabWidget与QGroupBox（附多功能窗口实战）
PyQt5容器控件：QTabWidget与QGroupBox（附多功能窗口实战）
1月5日 6
评论 抢沙发
OωO
取消
SSL