键盘自动化 (Keyboard)
Keyboard 对象用于模拟键盘的按键操作，包括按键的按下、释放以及组合键的输入。它适用于需要自动化键盘输入的场景，例如在无法通过控件直接输入内容时，或者需要模拟复杂的快捷键操作时。Keyboard 对象能够帮助你轻松实现这些功能。
你可以通过以下方式引入 Keyboard 对象：
JavaScript
Python
const { Keyboard } = require('leanpro.common');from leanproAuto import KeyboardKeyboard 对象提供以下方法：
| 方法名 | 描述 |
|---|---|
| keyTap | 按下一个键。 |
| unicodeTap | 按下一个由 Unicode 指定的键。 |
| keyDown | 按住一个键。 |
| keyUp | 释放一个键。 |
| setDelay | 设置每个键盘操作的间隔时间。 |
| typeString | 已弃用，建议使用 pressKeys。 |
| pressKeys | 输入组合按键或字符串。 |
| disableIme | 禁用当前聚焦应用的输入法。 |
类型定义
JavaScript
Python
export class Keyboard {
static keyTap(key: string, modified?: string | string[]): void;
static unicodeTap(keyCode: number): void;
static keyDown(key: string, modified?: string | string[]): void;
static keyUp(key: string, modified?: string | string[]): void;
static setDelay(milliseconds: number): void;
// static typeString(str: string, cpm?: number): void; // deprecated
static pressKeys(keys: string, options?: PressKeysOptions | number): Promise<void>;
static disableIme();
}
interface PressKeysOptions {
textOnly?: boolean,
cpm?: number
}class Keyboard:
def keyTap(key: str, modified: Optional[Union[str, List[str]]]=None) -> None
def unicodeTap(keyCode: int) -> None
def keyDown(key: str, modified: Optional[Union[str, List[str]]]=None) -> None
def keyUp(key: str, modified: Optional[Union[str, List[str]]]=None) -> None
def setDelay(milliseconds: int) -> None
# def typeString(str: str, cpm: Optional[int]=None) -> None # deprecated
def pressKeys(keys: str, cpm: Optional[int]=None) -> None
def disableIme() -> None
class PressKeysOptions():
textOnly: bool
cpm: intAPI 介绍
keyTap(key, modified)
按下一个键。
参数:
- key:
string类型，目标键的键值，可以参考Keys表。 - modified:
string | string[]类型（可选）。修饰键的键值，支持传入一个或多个修饰键（如 "control", "shift"）。若需要组合按键操作，可将多个修饰键以数组形式传入。
返回值:
- 不返回任何值的同步方法。
使用示例
JavaScript
Python
Keyboard.keyTap("a"); // 按下 "a" 键
Keyboard.keyTap("c", "control"); // 按下 "control + c" 组合键
Keyboard.keyTap("b", ["control", "shift"]); // 按下 "control + shift + b" 组合键Keyboard.keyTap("a") # 按下 "a" 键
Keyboard.keyTap("c", "control") # 按下 "control + c" 组合键
Keyboard.keyTap("b", ["control", "shift"]) # 按下 "control + shift + b" 组合键unicodeTap(key)
按下一个由 Unicode 指定的键。
参数:
- key:
number类型，目标键的 Unicode 键值。
返回值:
- 不返回任何值的同步方法。
使用示例
JavaScript
Python
Keyboard.unicodeTap(65); // 按下 "A" 键Keyboard.unicodeTap(65) # 按下 "A" 键在JavaScript中，可调用字符串的charCodeAt获得键值。例如下面的代码可以将字符串输出，等效于调用pressKeys()的效果：
JavaScript
'您好，中国(China)'.split('').map(k => Keyboard.unicodeTap(k.charCodeAt(0)));keyDown(key, modified)
按住一个键。
参数:
- key:
string类型，目标键的键值，可以参考Keys表。 - modified:
string | string[]类型（可选）。修饰键的键值，支持传入一个或多个修饰键（如 "control", "shift"）。若需要组合按键操作，可将多个修饰键以数组形式传入。
返回值:
- 不返回任何值的同步方法。
使用示例
JavaScript
Python
Keyboard.keyDown("control"); // 按住 "control" 键
Keyboard.keyDown("c", "control"); // 按住 "control + c" 组合键
Keyboard.keyDown("b", ["control", "shift"]); // 按住 "control + shift + b" 组合键Keyboard.keyDown("control") # 按住 "control" 键
Keyboard.keyDown("c", "control") # 按住 "control + c" 组合键
Keyboard.keyDown("b", ["control", "shift"]) # 按住 "control + shift + b" 组合键keyUp(key, modified)
释放一个键。
参数:
- key:
string类型，目标键的键值，可以参考Keys表。 - modified:
string | string[]类型（可选）。修饰键的键值，支持传入一个或多个修饰键（如 "control", "shift"）。若需要组合按键操作，可将多个修饰键以数组形式传入。
返回值:
- 不返回任何值的同步方法。
使用示例
JavaScript
Python
Keyboard.keyUp("control"); // 释放 "control" 键
Keyboard.keyUp("c", "control"); // 释放 "control + c" 组合键
Keyboard.keyUp("b", ["control", "shift"]); // 释放 "control + shift + b" 组合键Keyboard.keyUp("control") # 释放 "control" 键
Keyboard.keyUp("c", "control") # 释放 "control + c" 组合键
Keyboard.keyUp("b", ["control", "shift"]) # 释放 "control + shift + b" 组合键setDelay(delay)
控制每个键盘操作的间隔，默认为 10ms。
参数:
- delay:
number类型，间隔时间，单位为毫秒。
返回值:
- 不返回任何值的同步方法。
使用示例
JavaScript
Python
Keyboard.setDelay(100);Keyboard.setDelay(100)typeString(str, cpm)
已弃用，建议使用
pressKeys(str, {textOnly: true})代替。
输入一串字符。
参数:
- str:
string类型，需要输入的字符串。 - cpm: （可选）
number类型，每分钟输入的字符数（Character Per Minute）。如果有些被测应用在快速输入字符时无法及时处理导致显示不正常，可通过设置较低的cpm解决，例如cpm = 60。
返回值:
- 不返回任何值的异步方法。
使用示例
JavaScript
Python
await Keyboard.typeString("Hello, World!", 100);Keyboard.typeString("Hello, World!", 100)pressKeys(keys, options)
通过模拟键盘信号来实现字符串输入或组合键操作，因此不仅可以用于简单的文本输入，还可以进行复杂的键盘操作，如模拟登录、导航、剪切、粘贴等操作。
注意事项
- 在调用
pressKeys()之前，请确保目标控件已获得焦点（例如先使用click()点击文本输入框），否则输入内容可能不会发送到预期的控件。 - 输入字符串时，某些特殊字符（如
^+~%{}()）会被解析为控制键（如 Shift、Ctrl），而非普通字符。如需输入纯文本而忽略这些控制符号，可使用{ textOnly: true }选项调用。更多控制键符号的说明请参考附录: 输入键对应表。
参数:
- key:
string类型，要输入的按键、组合键或字符串，最大支持 1024 个字符。 options:
PressKeysOptions | number（可选） 控制输入模式的参数：textOnly:boolean类型，设为true时，将所有字符作为普通文本输入，等效于Keyboard.typeString()。cpm:number类型，每分钟输入的字符数，用于控制输入速度。建议设置在 200 以上，实际速度可能因系统差异而不同。
如果直接传入数字作为
options，该值将被视为cpm参数。
返回值:
- 不返回任何值的异步方法。
使用示例
JavaScript
Python
await Keyboard.pressKeys("Hello, World!", { textOnly: true });Keyboard.pressKeys("Hello, World!", { "textOnly": True })disableIme()
禁用当前聚焦应用的输入法。这样在调用其他输入键盘操作的方法，如typeString或pressKeys时，不会受输入法的干扰。
返回值:
- 不返回任何值的异步方法。
注意：输入法是跟应用相关的。如果启动了一个新的被测应用，可能需要再次调用disableIme()。
使用示例
JavaScript
Python
await Keyboard.disableIme();Keyboard.disableIme()Keys
Keys 是一个枚举对象，列举了所有可用于 keyTap、keyDown 和 keyUp 方法的按键。以下表格中描述了按键名和其对应的功能。
注意： 对于字母键和数字键，可以直接使用同名字符，因此未在下表列出。例如，按下字母键 b 和数字键 5 时，直接传入参数 "b" 和 "5" 即可。
Windows 徽标键: Windows 键盘特有的一个 控制 键，与 Mac 的
cmd键类似，都可以使用"command"的按键名来表示。
| 按键名 | 描述 | 备注 |
|---|---|---|
| backspace | 退格键 | |
| delete | 删除键 | |
| enter | 回车键 | |
| tab | Tab键 | |
| escape | Esc键 | |
| up | 上方向键 | |
| down | 下方向键 | |
| right | 右方向键 | |
| left | 左方向键 | |
| home | Home键 | |
| end | End键 | |
| pageup | Page Up键 | |
| pagedown | Page Down键 | |
| f1 | F1键 | |
| f2 | F2键 | |
| f3 | F3键 | |
| f4 | F4键 | |
| f5 | F5键 | |
| f6 | F6键 | |
| f7 | F7键 | |
| f8 | F8键 | |
| f9 | F9键 | |
| f10 | F10键 | |
| f11 | F11键 | |
| f12 | F12键 | |
| f13 | F13键 | |
| f14 | F14键 | |
| f15 | F15键 | |
| f16 | F16键 | |
| f17 | F17键 | |
| f18 | F18键 | |
| f19 | F19键 | |
| f20 | F20键 | |
| f21 | F21键 | |
| f22 | F22键 | |
| f23 | F23键 | |
| f24 | F24键 | |
| capslock | Caps Lock键 | |
| command | CMD 键或 Windows 键 | 取决于系统 |
| alt | Alt键 | |
| right_alt | 右Alt键 | |
| control | Ctrl键 | |
| left_control | 左Ctrl键 | |
| right_control | 右Ctrl键 | |
| shift | Shift键 | |
| right_shift | 右Shift键 | |
| space | 空格键 | |
| printscreen | 打印屏幕键 | 不支持Mac |
| insert | 插入键 | 不支持Mac |
| menu | 菜单键 | |
| audio_mute | 静音键 | |
| audio_vol_down | 音量减小键 | |
| audio_vol_up | 音量增大键 | |
| audio_play | 播放键 | |
| audio_stop | 停止键 | |
| audio_pause | 暂停键 | |
| audio_prev | 上一首键 | |
| audio_next | 下一首键 | |
| audio_rewind | 倒带键 | 仅在 Linux 有效 |
| audio_forward | 快进键 | 仅在 Linux 有效 |
| audio_repeat | 重复播放键 | 仅在 Linux 有效 |
| audio_random | 随机播放键 | 仅在 Linux 有效 |
| numpad_lock | Num Lock键 | |
| numpad_0 | 数字键盘0 | |
| numpad_1 | 数字键盘1 | |
| numpad_2 | 数字键盘2 | |
| numpad_3 | 数字键盘3 | |
| numpad_4 | 数字键盘4 | |
| numpad_5 | 数字键盘5 | |
| numpad_6 | 数字键盘6 | |
| numpad_7 | 数字键盘7 | |
| numpad_8 | 数字键盘8 | |
| numpad_9 | 数字键盘9 | |
| numpad_+ | 数字键盘+ | |
| numpad_- | 数字键盘- | |
| numpad_* | 数字键盘* | |
| numpad_/ | 数字键盘/ | |
| numpad_. | 数字键盘. | |
| lights_mon_up | 提高显示器亮度 | Windows 不支持 |
| lights_mon_down | 降低显示器亮度 | Windows 不支持 |
| lights_kbd_toggle | 开/关键盘背灯 | Windows 不支持 |
| lights_kbd_up | 提高键盘背灯亮度 | Windows 不支持 |
| lights_kbd_down | 降低键盘背灯亮度 | Windows 不支持 |
特殊按键 Keys 的用法
Keys 枚举类常用于处理特殊按键，比如 Ctrl、Shift 等。可以通过 keyDown()、keyUp() 和 keyTap() 方法来模拟按键操作。在需要同时按下 Ctrl 键和 A 键以执行全选操作时，代码示例如下：
JavaScript
Python
const { Keyboard } = require('leanpro.common');
// 方法1：分别按下与释放控制键
Keyboard.keyDown('control');
Keyboard.keyTap('a');
Keyboard.keyUp('control');
// 方法2：组合键按下
Keyboard.keyTap('a', 'control');from leanproAuto import Keyboard
# 方法1：分别按下与释放控制键
Keyboard.keyDown('control')
Keyboard.keyTap('a')
Keyboard.keyUp('control')
# 方法2：组合键按下
Keyboard.keyTap('a', 'control')使用 Keys 枚举类
在默认情况下，keyTap、keyDown、keyUp 方法可以直接接受简单的字符（如 'a'）。而对于像 'control' 这样的字符串，会自动匹配 Keys 枚举类。如果需要明确使用 Keys 枚举类，可以如下编写：
JavaScript
const { Keyboard, Keys } = require('leanpro.common');
// 使用 Keys 枚举类
Keyboard.keyDown(Keys.control);
Keyboard.keyTap('a');
Keyboard.keyUp(Keys.control);
// 等同于下面的写法
Keyboard.keyTap('a', Keys.control);注意：如果希望直接输入字符串而不触发特殊键（如输入
"control"），应该使用pressKeys(str, { textOnly: true })方法。
组合键操作
如果需要在操作过程中按住某个控制键（例如 Ctrl 键）并进行其他操作（如拖拽、点击），可以灵活使用 keyDown() 和 keyUp() 方法。例如按住 Shift 键并在按住期间进行其他操作：
JavaScript
Python
const { Keyboard } = require('leanpro.common');
// 按住 Shift 键
Keyboard.keyDown('shift');
// 在这里执行其他操作
// ...
// 释放 Shift 键
Keyboard.keyUp('shift');from leanproAuto import Keyboard
# 按住 Shift 键
Keyboard.keyDown('shift')
# 在这里执行其他操作
# ...
# 释放 Shift 键
Keyboard.keyUp('shift')示例：使用组合键进行操作
下面是几个组合键操作的示例，包括按住 Ctrl 键、Shift 键与字母键的不同组合操作：
JavaScript
Python
const { Keyboard } = require('leanpro.common');
// 按下并释放组合键
Keyboard.keyTap('c', 'control'); // 按下 "control + c"
Keyboard.keyTap('b', ['control', 'shift']); // 按下 "control + shift + b"
// 按住组合键进行操作
Keyboard.keyDown('shift'); // 按住 "shift" 键
// 执行操作
Keyboard.keyUp('shift'); // 释放 "shift" 键from leanproAuto import Keyboard
# 按下并释放组合键
Keyboard.keyTap('c', 'control') # 按下 "control + c"
Keyboard.keyTap('b', ['control', 'shift']) # 按下 "control + shift + b"
# 按住组合键进行操作
Keyboard.keyDown('shift') # 按住 "shift" 键
# 执行操作
Keyboard.keyUp('shift') # 释放 "shift" 键通过这些方法和示例，你可以灵活处理各种键盘输入场景，特别是涉及组合键的复杂操作。