Python keyboard模块：非阻塞式按键检测教程

在开发需要持续运行并同时响应用户按键输入的python程序时，正确处理键盘事件至关重要。keyboard是一个强大的python库，用于模拟和监听键盘事件。然而，在使用过程中，开发者常会遇到一个常见陷阱：keyboard.read_key()函数的阻塞行为。本教程将深入探讨这一问题，并提供一个优雅的非阻塞解决方案。

1. read_key()函数的阻塞特性

许多开发者在尝试检测特定按键（例如“q”键）以停止程序时，可能会编写如下代码：

import keyboard as kbd
from time import sleep

while True:
    kbd.press("space")
    sleep(0.1)
    kbd.release("space")            
    # 尝试在此处检测'q'键
    if kbd.read_key() == "q":
        break

这段代码的预期是程序在循环中不断执行space键的按下和释放操作，直到用户按下“q”键时停止。然而，实际运行会发现，程序在执行到if kbd.read_key() == "q":这一行时会暂停，不再执行space键的操作，而是等待用户输入任何按键。

这是因为keyboard.read_key()函数是一个阻塞式调用。根据其官方文档描述，该函数会“阻塞直到键盘事件发生，然后返回该事件的名称或扫描码”。这意味着程序会在此处暂停执行，直到用户按下任意一个键。这种行为不适用于需要程序持续运行，同时在后台监听特定按键的场景。

2. 使用add_hotkey()实现非阻塞按键监听

为了实现非阻塞的按键检测，keyboard模块提供了add_hotkey()函数。这个函数允许你注册一个回调函数，当指定的快捷键组合被按下时，该回调函数会被异步执行，而不会阻塞主程序的流程。

立即学习“Python免费学习笔记（深入）”；

AGI-Eval评测社区

AI大模型评测社区

63

查看详情

keyboard.add_hotkey(hotkey, callback, args=(), suppress=False, timeout=1, trigger_on_release=False)

• hotkey: 要监听的按键或按键组合（例如："q", "ctrl+c"）。
• callback: 当hotkey被按下时要执行的函数。
• args: 传递给callback函数的参数。
• suppress: 如果为True，则按键事件不会传递给其他应用程序。
• trigger_on_release: 如果为True，则在按键释放时触发回调。

通过add_hotkey()，我们可以设置一个全局标志位，当“q”键被按下时，回调函数会修改这个标志位，主循环通过检查这个标志位来决定是否退出。

3. 示例代码：非阻塞式“q”键停止程序

下面是使用add_hotkey()改进后的代码示例，它实现了在不阻塞主循环的情况下，通过按下“q”键来停止程序：

import keyboard as kbd
from time import sleep

# 定义一个全局标志位，用于指示'q'键是否被按下
was_q_pressed = False
# 用于存储热键的引用，以便后续移除
q_hotkey_reference = None

# 定义'q'键按下时的回调函数
def on_q_press():
  """
  当'q'键被按下时执行的回调函数。
  它会设置全局标志位，并移除当前热键，确保只触发一次。
  """
  global was_q_pressed
  global q_hotkey_reference

  was_q_pressed = True
  # 移除热键，确保回调只被触发一次，避免重复处理
  if q_hotkey_reference:
      kbd.remove_hotkey(q_hotkey_reference)
      q_hotkey_reference = None # 清空引用

# 注册'q'键的热键，并将其引用存储起来
q_hotkey_reference = kbd.add_hotkey("q", on_q_press)

print("程序开始运行，按'q'键停止...")

while True:
    # 模拟持续的程序操作
    kbd.press("space")
    sleep(0.1)
    kbd.release("space")            

    # 检查全局标志位，判断是否需要退出循环
    if was_q_pressed:
        print("检测到'q'键按下，程序即将停止。")
        break

    # 为了避免CPU占用过高，可以在循环中添加短暂的延时
    # sleep(0.01) # 根据实际需求调整

print("程序已停止。")

4. 代码详解与注意事项

• was_q_pressed = False: 这是一个布尔型的全局标志位，用于在主循环和回调函数之间传递状态信息。初始值为False，表示“q”键尚未被按下。
• q_hotkey_reference = None: 用于存储add_hotkey返回的热键引用。这个引用在后续需要移除热键时会用到。
• on_q_press()函数:
  • 这是一个回调函数，当“q”键被按下时，keyboard模块会自动调用它。
  • global was_q_pressed 和 global q_hotkey_reference: 在函数内部修改全局变量时，必须使用global关键字声明。
  • was_q_pressed = True: 将标志位设置为True，通知主循环“q”键已被按下。
  • kbd.remove_hotkey(q_hotkey_reference): 非常重要！ 如果你希望“q”键只触发一次停止动作，那么在回调函数执行后，应该立即移除这个热键。否则，每次按下“q”键都会再次触发回调。移除后，将q_hotkey_reference置为None以避免悬空引用。
• q_hotkey_reference = kbd.add_hotkey("q", on_q_press): 这一行注册了热键。当用户按下“q”键时，on_q_press函数将被调用。
• 主while循环:
  • 它会持续执行space键的按下和释放操作，模拟程序的正常运行。
  • if was_q_pressed:: 主循环不断检查was_q_pressed的状态。一旦on_q_press函数被调用并将其设置为True，主循环就会检测到并执行break语句，从而优雅地退出。

5. 总结

通过使用keyboard.add_hotkey()并结合回调函数与全局标志位，我们可以有效地实现非阻塞的按键事件监听。这种方法使得程序能够在持续执行主任务的同时，异步地响应用户输入，极大地提高了程序的响应性和用户体验。在设计需要后台监听键盘事件的自动化脚本、游戏辅助工具或交互式程序时，add_hotkey()是比read_key()更优的选择。务必记住，对于一次性触发的事件，使用remove_hotkey()来清理注册的热键是一个良好的编程习惯。

以上就是Python keyboard模块：非阻塞式按键检测教程的详细内容，更多请关注php中文网其它相关文章！