如何在后台运行Qt按键事件并保留WindowStaysOnTopHint窗口属性？

核心原因 #

PySide6默认的键盘事件（如keyPressEvent）仅在窗口激活时触发，后台状态下无法捕获全局按键；之前使用pynput报错，大概率是因为监听器运行在GUI主线程，阻塞了界面循环，或是未正确处理线程间的GUI更新逻辑。

解决方案 #

通过pynput全局键盘监听+后台线程+PySide6信号槽实现，既保留窗口置顶属性，又能在后台捕获按键并安全更新界面：

1. 定义信号槽实现线程安全的GUI更新 #

在gui.py的窗口类中定义信号，用于接收按键信息并更新标签：

# gui.py
from PySide6.QtWidgets import QMainWindow, QLabel, QVBoxLayout, QWidget
from PySide6.QtCore import Signal, Qt

class KeyDisplayWindow(QMainWindow):
    # 定义传递按键名称的信号
    keyPressed = Signal(str)

    def __init__(self):
        super().__init__()
        self.init_ui()
        # 绑定信号与更新标签的槽函数
        self.keyPressed.connect(self.update_key_label)

    def init_ui(self):
        self.setWindowTitle("按键显示工具")
        # 保留窗口置顶属性
        self.setWindowFlags(self.windowFlags() | Qt.WindowStaysOnTopHint)
        self.resize(300, 100)

        central_widget = QWidget()
        layout = QVBoxLayout(central_widget)
        self.key_label = QLabel("等待按键...", alignment=Qt.AlignCenter)
        layout.addWidget(self.key_label)
        self.setCentralWidget(central_widget)

    def update_key_label(self, key_name):
        self.key_label.setText(f"当前按键: {key_name}")

2. 后台线程启动pynput全局监听器 #

在main.py中创建独立线程运行pynput监听器，捕获按键后通过信号通知GUI主线程更新：

# main.py
from PySide6.QtWidgets import QApplication
from PySide6.QtCore import QThread
from pynput.keyboard import Listener, Key
import sys
from gui import KeyDisplayWindow

class KeyListenerThread(QThread):
    def __init__(self, signal):
        super().__init__()
        self.key_signal = signal
        self.listener = None

    def run(self):
        # 按键捕获回调函数
        def on_press(key):
            try:
                # 处理普通字符按键
                key_name = key.char
            except AttributeError:
                # 处理特殊按键（如Shift、Enter等）
                key_name = str(key).replace("Key.", "")
            # 发射信号传递按键名称
            self.key_signal.emit(key_name)

        # 启动全局监听器
        self.listener = Listener(on_press=on_press)
        self.listener.start()
        self.listener.join()

    def stop(self):
        if self.listener:
            self.listener.stop()

if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = KeyDisplayWindow()
    window.show()

    # 创建并启动监听线程
    listener_thread = KeyListenerThread(window.keyPressed)
    listener_thread.start()

    # 程序退出时终止监听线程
    app.aboutToQuit.connect(listener_thread.stop)

    sys.exit(app.exec())

3. 关键注意事项 #

• 线程安全：禁止在监听线程中直接修改GUI控件，必须通过PySide6信号槽机制，确保更新操作在主线程执行，避免界面崩溃。
• 系统权限：部分系统（如macOS、Windows）需授予程序键盘监听权限，否则后台无法捕获按键。
• 资源清理：程序退出时调用stop()方法终止监听器，避免资源泄漏。

内容的提问来源于stack exchange，提问作者shabnam mansuri