无需使用cv.waitKey(delay)，如何获取OpenCV窗口键盘事件？

问题背景 #

OpenCV 提供了cv.setMouseCallback(window, callback_function)方法，可用于注册处理鼠标事件的函数，无需通过循环获取事件。那是否存在一种OpenCV方法或其他实现方式，能够注册处理键盘事件的函数，从而无需编写while True: key = cv.waitKey() ...这类循环？

注：已知有针对C++的相关问题但无已采纳答案，此处提问并非重复，且已检索网络未找到有效解决方案。

可行实现方案 #

1. 借助第三方库pynput实现独立键盘监听 #

可以用pynput库脱离OpenCV的waitKey循环，单独监听键盘事件，和OpenCV窗口显示并行运行，完全模拟回调模式。示例代码：

import cv2 as cv
from pynput.keyboard import Listener, Key

# 定义键盘事件回调函数
def on_press(key):
    try:
        print(f"按下字母键: {key.char}")
        # 自定义按键逻辑，比如按q退出
        if key.char == 'q':
            listener.stop()
            cv.destroyAllWindows()
    except AttributeError:
        print(f"按下特殊键: {key}")
        if key == Key.esc:
            listener.stop()
            cv.destroyAllWindows()

# 启动键盘监听线程
listener = Listener(on_press=on_press)
listener.start()

# 显示OpenCV窗口，无需在循环里处理按键
img = cv.imread("test.jpg")
while listener.is_alive():
    cv.imshow("Demo Window", img)
    # 仅做短时间等待降低CPU占用，不处理按键逻辑
    cv.waitKey(1)

listener.join()
cv.destroyAllWindows()

2. 封装循环逻辑模拟回调模式 #

如果不想依赖第三方库，可以自己封装一个装饰器，把waitKey循环的逻辑隐藏，让代码写法接近回调模式：

import cv2 as cv

def keyboard_callback(callback):
    def wrapper(window_name, frame):
        while True:
            cv.imshow(window_name, frame)
            key = cv.waitKey(1) & 0xFF
            if key != 255:
                callback(key)
                if key == ord('q'):
                    break
        cv.destroyAllWindows()
    return wrapper

# 定义自定义键盘处理函数
@keyboard_callback
def handle_key(key):
    print(f"按键码: {key}")
    if key == ord('a'):
        print("执行A键对应的操作")

# 使用示例
test_img = cv.imread("test.jpg")
handle_key("Demo Window", test_img)

关键说明 #

OpenCV本身没有官方提供类似setMouseCallback的键盘事件注册API，因为其键盘事件依赖于窗口消息循环，waitKey是触发该循环的核心机制。第三方库方案更接近“注册回调”的设计思路，而封装方案只是对原有循环做了简化包装，本质仍基于waitKey。

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