keyboard库安装与使用指南

2026-02-06 04:14:51作者：戚魁泉Nursing

1. 项目目录结构及介绍

keyboard是一个功能强大的Python库，用于捕获和模拟全局键盘事件。项目目录结构清晰：

keyboard/
├── README.md        # 项目说明文档
├── Makefile         # 构建配置文件
├── CHANGES.md       # 变更日志
├── MANIFEST.in      # 包清单文件
├── LICENSE.txt      # 许可证文件
├── setup.py         # 安装配置文件
├── make_release.py  # 发布脚本
├── keyboard/        # 核心库文件目录
│   ├── __init__.py      # 主库文件
│   ├── __main__.py      # 命令行入口
│   ├── _canonical_names.py  # 规范键名映射
│   ├── _darwinkeyboard.py   # macOS键盘实现
│   ├── _darwinmouse.py      # macOS鼠标实现
│   ├── _generic.py          # 通用功能
│   ├── _keyboard_event.py   # 键盘事件类
│   ├── _keyboard_tests.py   # 键盘测试
│   ├── _mouse_event.py      # 鼠标事件类
│   ├── _mouse_tests.py      # 鼠标测试
│   ├── _nixcommon.py        # Linux通用功能
│   ├── _nixkeyboard.py      # Linux键盘实现
│   ├── _nixmouse.py         # Linux鼠标实现
│   ├── _winkeyboard.py      # Windows键盘实现
│   ├── _winmouse.py         # Windows鼠标实现
│   └── mouse.py             # 鼠标模块
└── examples/         # 示例代码目录
    ├── 10_second_macro.py         # 10秒宏示例
    ├── customizable_hotkey.py     # 可自定义热键示例
    ├── pressed_keys.py            # 按键状态检测示例
    ├── push_to_talk_ubuntu.py     # Ubuntu一键通话示例
    ├── segmented_macro.py         # 分段宏示例
    ├── simulate_held_down.py      # 模拟按键保持示例
    ├── stdin_stdout_events.py     # 标准输入输出事件示例
    └── write.py                   # 文本输入示例

2. 项目功能特性

keyboard库提供以下核心功能：

全局事件钩子：捕获所有键盘的按键事件（无论焦点在哪个窗口）
监听和发送键盘事件
跨平台支持：Windows、Linux（需要sudo权限）、实验性macOS支持
纯Python实现：无需编译C模块
零依赖：易于安装和部署
Python 2和3兼容
复杂热键支持：如ctrl+shift+m, ctrl+space，可控制超时时间
国际化支持：正确映射键盘布局中的键位（如Ctrl+ç）
线程安全：事件在独立线程中捕获，不阻塞主程序

3. 安装方法

方法一：通过PyPI安装

pip install keyboard

方法二：克隆仓库（无需安装）

git clone https://gitcode.com/gh_mirrors/ke/keyboard

方法三：下载ZIP文件

下载项目ZIP包并解压到项目文件夹中即可使用。

4. 基本使用方法

4.1 导入库

import keyboard

4.2 基本按键操作

# 按下并释放组合键
keyboard.press_and_release('shift+s, space')

# 输入文本
keyboard.write('The quick brown fox jumps over the lazy dog.')

# 添加热键
keyboard.add_hotkey('ctrl+shift+a', print, args=('triggered', 'hotkey'))

# 按下PAGE UP然后PAGE DOWN来输入"foobar"
keyboard.add_hotkey('page up, page down', lambda: keyboard.write('foobar'))

4.3 事件监听

# 阻塞直到按下ESC键
keyboard.wait('esc')

# 记录事件直到按下ESC
recorded = keyboard.record(until='esc')
# 以三倍速度回放
keyboard.play(recorded, speed_factor=3)

# 输入@@然后按空格替换为缩写
keyboard.add_abbreviation('@@', 'my.long.email@example.com')

# 永久阻塞
keyboard.wait()

5. 示例代码解析

5.1 可自定义热键示例

import keyboard

print('Press and release your desired shortcut: ')
shortcut = keyboard.read_hotkey()
print('Shortcut selected:', shortcut)

def on_triggered():
    print("Triggered!")
keyboard.add_hotkey(shortcut, on_triggered)

print("Press ESC to stop.")
keyboard.wait('esc')

这个示例展示了如何让用户自定义热键。程序会等待用户按下并释放一个组合键，然后将该组合键设置为触发函数的热键。

5.2 命令行使用

keyboard库也可以作为独立模块使用：

# 保存JSON事件到文件直到中断
python -m keyboard > events.txt

# 查看事件
cat events.txt
# {"event_type": "down", "scan_code": 25, "name": "p", "time": 1622447562.2994788, "is_keypad": false}
# {"event_type": "up", "scan_code": 25, "name": "p", "time": 1622447562.431007, "is_keypad": false}

# 回放事件
python -m keyboard < events.txt

6. 常见模式和错误

6.1 防止程序退出

import keyboard
keyboard.add_hotkey('space', lambda: print('space was pressed!'))

# 正确做法：使用wait()
keyboard.wait()

# 或者使用sleep
import time
while True:
    time.sleep(1000000)

6.2 等待单次按键

import keyboard

# 正确做法：使用wait()
keyboard.wait('space')
print('space was pressed, continuing...')

6.3 重复等待按键

import keyboard

# 正确做法
while True:
    keyboard.wait('space')
    print('space was pressed! Waiting on it again...')

# 或者使用热键
keyboard.add_hotkey('space', lambda: print('space was pressed!'))
keyboard.wait()