keyboard库-捕获键盘事件、模拟按键事件

一点兴趣爱好在学习过程中形成的笔记。可能会有错误，欢迎指正。邮箱：zhuoyangmu@qq.com

keyboard 是一个在 Python 中使用的第三方库，提供了全局热键监听和模拟键盘输入的功能。可以用来编写程序来监听特定的按键组合，或者控制程序发送键盘输入，对于自动化任务、游戏脚本编写、快速启动程序等场景非常有用。

因为监听全局键盘事件通常需要较高的权限。，所以需要确保在使用 keyboard 库时，程序有适当的权限（在 Windows 上可能需要以管理员身份运行，linux上需要sudo），同时，请注意不要滥用此功能，以免侵犯他人隐私或违反法律法规。

主要特性※

  • 全局事件钩子：可以在所有键盘上捕捉按键事件，无论当前哪个程序处于活动状态。
  • 热键支持：支持复杂的热键组合，例如 ctrl+shift+m 或者 ctrl+space。
  • 国际键盘支持：按键映射考虑到实际布局，支持国际键盘，比如 Ctrl+ç。
  • 多平台兼容性：在 Windows 和 Linux 上运行良好（Linux 需要 sudo 权限），并且有实验性的 macOS 支持。
  • 纯 Python 实现：无需编译额外的 C 模块。
  • 零依赖：仅包含源文件，无需额外安装。
  • 多版本兼容：支持 Python 2 和 Python 3。
  • 非阻塞事件处理：事件在独立线程中捕捉，不会阻塞主程序。

安装与引用※

可以通过 PyPI 安装 keyboard 库：

pip install keyboard

或者从 GitHub 克隆仓库：

git clone https://github.com/boppreh/keyboard

然后通过以下代码引用

import keyboard

API / 函数 / 方法※

模拟按键※

send(‘hotkey’, do_press=True, do_release=True,duration=0.1,pause=0.1)

作用：用于模拟按键操作。可以发送单个键或组合键。可控制是否模拟按键按下和释放。组合键时，确保键名之间有加号 (+) 

参数：

do_press：一个布尔值，表示是否发送按键按下的事件。默认为 True。

do_release：一个布尔值，表示是否发送按键释放的事件。默认为 True。

duration：一个浮点数，表示按键持续的时间（秒）。默认为 0，表示瞬时按键。

pause：一个浮点数，表示在按键之间暂停的时间（秒）。默认为 0。

示例：keyboard.send('ctrl+a')

press(hotkey)

作用：模拟按键按下。
示例：keyboard.press('a')

release(hotkey)

作用：模拟按键释放。
示例：keyboard.release('a')

press_and_release(keys)

作用：模拟按键按下和立即释放，可以是组合键。
示例：keyboard.press_and_release('ctrl+v')

write(string, delay=0, restore_state=True)

作用：用于模拟键盘输入，即向当前活动的窗口或应用程序发送一系列字符。

参数：

string: 要输入的文本字符串。
delay: （可选）两次按键之间的延迟时间（以秒为单位）。默认为0，意味着按键将尽可能快地发送。
restore_state: （可选）布尔值，指示是否在写入后恢复按键状态。默认为True。【当与其他函数混用时，会影响到其他输入】

# 写入一段文本
keyboard.write("Hello, World!")
# 写入文本，每次按键间有0.1秒的延迟
keyboard.write("Slow typing", delay=0.1)

监听-键盘事件※

hook(callback)

作用：监听所有键盘事件，当任何按键被按下或释放时调用回调函数。函数返回一个 ID（listener_id），可以用来移除监听器。callback是一个函数，当任何按键被按下或释放时都会被调用。并将 KeyboardEvent对象属性作为参数传入。
示例：keyboard.hook(print)

unhook(listener_id)

作用：取消监听指定的键盘事件。listener_id为监听事件返回值
示例：keyboard.unhook(listener_id)

unhook_all()

作用：会移除所有通过 keyboard 库注册的监听器和热键，无论它们是由哪个函数添加的。
示例：keyboard.unhook_all()

on_press(callback)

作用：on_press 函数是 keyboard 库中用于注册监听键盘按键被按下的事件处理器。它允许指定一个回调函数，当任何按键被按下时，这个函数就会被调用。并将 KeyboardEvent对象属性作为参数传入。
示例：

import keyboard
def on_key_pressed(event):
  print(f'Key {event.name} was pressed')
# 注册事件处理器
keyboard.on_press(on_key_pressed)
# 程序将一直运行，监听键盘事件
keyboard.wait()

on_press_key(key, callback)

作用：同on_press 类似，用于注册监听特定按键的按下事件的事件处理器。
示例：keyboard.on_press_key('a', on_a_pressed)

is_pressed(’任何标准的键盘键名或组合’)

作用：检查指定的键是否处于按下状态。这在需要即时响应用户输入，或者在循环中检查按键状态时非常有用。
示例：

while True:
    if keyboard.is_pressed('q'):
        print("按'q'进入下一步")
        break

on_release(callback)

作用：用于注册监听按键释放的事件处理器。可以让注册一个回调函数，当任何按键被释放时，这个函数将被调用。并将 KeyboardEvent对象属性作为参数传入。
示例：keyboard.on_release(on_key_released

on_release_key(key, callback)

作用：同on_release类似，用于注册监听特定按键释放事件的事件处理器。
示例：keyboard.on_release_key('space', lambda e: print('Space released'))

read_event()

作用：用于读取并返回下一个键盘事件。这个函数会阻塞，直到有一个键盘事件发生。它主要用于实时应用程序中，需要即时响应键盘输入的情况。

返回值：返回一个KeyboardEvent对象。

示例：

import keyboard

while True:
    event = keyboard.read_event()
    print(f"Key {event.name} was {event.event_type}.")

热键管理※

add_hotkey(hotkey, callback)

作用：用于定义热键组合，当这些热键被按下时，可以触发预定义的回调函数。热键可以是单个键，也可以是多个键的组合，热键顺序无所谓。

特殊参数：suppress 参数是一个布尔值，用于控制热键事件是否应被抑制。默认情况下，suppress 设置为 False，这意味着热键事件会被发送到操作系统和其他应用程序，可能会被其他程序捕获和处理。如果将 suppress 设置为 True，则热键事件将不会传递给其他应用程序，仅由你的回调函数处理。这对于避免与其他应用程序的热键冲突特别有用。
示例：keyboard.add_hotkey('热键组合', 函数,args,kwargs,suppress)

def my_callback(message, user_id):
    print(f'Message from user {user_id}: {message}')

# 注册热键并传递参数
keyboard.add_hotkey('ctrl+shift+m', my_callback, args=('Hello, world!', 12345))

remove_hotkey(hotkey)

作用：用于移除之前通过 add_hotkey 函数注册的指定热键。
示例：

keyboard.remove_hotkey('ctrl+alt+p')
或
hotkey_id = keyboard.add_hotkey('ctrl+shift+t', print（"a"）)
keyboard.remove_hotkey(hotkey_id)

unhook_all_hotkeys()

作用：用于移除所有注册过的热键（hotkeys）。

文本缩写※

add_abbreviation(abbreviation, replacement, trigger_on_release=False)【如何触发】

作用：注册文本缩写。当输入特定文本后跟空格时，自动替换成完整的文本。非常适合快速输入长文本、常用短语或代码模板，极大地提高了打字效率，尤其在编写大量重复文本或代码时非常有用。

参数：

abbreviation: 字符串，你想要定义的缩写词。
replacement: 字符串，缩写词被触发时将替换为的完整文本。
trigger_on_release: 布尔值，可选，默认为False。如果设置为True，则缩写在按键释放时触发；如果为False，则在按键按下时触发。

事件记录和回放※

record(until=None, suppress=False, include_repeats=True)【实际使用時會提示until超長。】

作用：用于记录键盘输入，直到满足特定条件为止。这个函数会持续监听键盘事件，并返回一个事件列表，这些事件是在until条件满足之前发生的。

参数：

until: 这个参数可以是一个字符串，表示应该停止记录的特定键名；也可以是一个函数，该函数接受一个KeyboardEvent对象作为参数，当函数返回True时，记录将停止。

suppress: 布尔值，如果为True，则记录过程中不会将事件发送到操作系统，这意味着记录的键不会影响实际的应用程序。

include_repeats: 布尔值，如果为False，则重复的键按压事件将不会被记录。

示例：

def my_stopping_condition(event):
    # 在这里检查 event 并决定是否停止记录
    if event.name == 'esc':
        return True
    else:
        return False
# 开始记录键盘事件，直到按下 'esc'
events = keyboard.record(until=my_stopping_condition)

# 输出记录的事件
for e in events:
    print(e)

stop_recording()

作用：用于停止正在进行的键盘事件记录。当使用keyboard.record()函数开始记录键盘事件后，如果想要在某个时刻停止记录，就可以调用stop_recording()。如果keyboard.record()函数是在另一个线程或进程中运行的，stop_recording()可能需要一点时间才能生效，这是因为事件记录可能在另一个线程中进行。

返回值：无直接返回值，但停止记录后，你可以通过访问之前记录的事件列表来进行进一步的处理。

get_typed_strings(event)

作用：解析-KeyboardEvent对象属性

返回值【返回值似乎是一个迭代器】：返回一个字符串列表，其中每个字符串代表一个或多个按键事件的文本表示。对于单个字符键，列表中只有一个元素；对于组合键或特殊键，列表可能包含多个元素，表示不同的文本片段。

其他功能※

wait(key=None)

作用：在keyboard库中，keyboard.wait(key=None)函数用于监听和等待特定的键盘事件。具体功能如下：
当没有参数传递给wait()函数时（即keyboard.wait()），它将永久阻塞程序的执行。这通常用于脚本的结尾，以防止脚本立即退出，让用户有机会看到输出结果。如果传递了一个键作为参数（即keyboard.wait('esc')），那么wait()函数将会阻塞，直到指定的键被按下。这可以用来控制脚本的流程，例如暂停脚本直到用户按下特定的热键。

返回值：KeyboardEvent对象，这个对象包含了关于触发事件的键的信息，如键是否被按下或释放，以及事件发生的时间戳。

示例：

import keyboard

print("Waiting for any key...")
event = keyboard.wait()  # 阻塞直到任意键被按下
print(f"Key {event.name} was pressed.")

# 或者等待特定的键
print("Waiting for the 'q' key...")
event = keyboard.wait('q')  # 阻塞直到 'q' 键被按下
print(f"Key {event.name} was pressed.")

未完待续※

  1. read_key(suppress=False)
    • 等待键盘事件发生并返回事件的名称或扫描码。
  2. play(events, speed_factor=1.0)
    • 播放记录的事件序列，保持相对的时间间隔。
  3. parse_hotkey(hotkey)
    • 解析用户提供的热键。
  4. parse_hotkey_combinations(hotkey)
    • 解析用户提供的热键，与 parse_hotkey 不同，它返回所有可能的组合。

KeyboardEvent对象属性※

keyboard库在Python中提供了一系列工具来监听和模拟键盘事件。

当使用keyboard库的事件监听功能时，如keyboard.record()或事件监听装饰器keyboard.on_press()和keyboard.on_release()，捕获的键盘事件会被封装成KeyboardEvent对象。

  • event_type: 键盘事件的类型，通常是'up'（键释放）或'down'（键按下）。

  • scan_code: 键的扫描码，这是一个硬件相关的值，用来唯一标识一个键。

  • name (可选): 键的名称，如'a'、'b'、'left arrow'等。

  • time (可选): 事件发生的时间戳。

  • device (可选): 生成事件的设备信息。

  • modifiers (可选): 按下的修饰键，如Shift、Ctrl、Alt等。

  • is_keypad (可选): 布尔值，指示键是否来自数字小键盘。

import keyboard

# 记录直到 'esc' 被按下
events = keyboard.record(until='esc')

# 遍历所有捕获的事件
for event in events:
    print(f"键盘事件的类型: {event.event_type} - 键的名称: {event.name} - 时间戳: {event.time}")
    print(f"扫描码: {event.scan_code} - 设备信息: {event.device }")
    print(f"修饰键: {event.modifiers } - 是否来自数字小键盘: {event.is_keypad }\n")
目录
Copyright © 2024-2024. All Rights Reserved.