键盘自动化 (Keyboard)

与模拟鼠标相对应的就是模拟键盘操作，所有与键盘相关的操作属于 Keyboard 对象。

Keyboard 对象提供以下方法：

方法名	描述
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: int

API 介绍

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)

通过模拟键盘信号来实现字符串输入或组合键操作，因此不仅可以用于简单的文本输入，还可以进行复杂的键盘操作，如模拟登录、导航、剪切、粘贴等操作。

需要注意，字符串中的某些特殊字符（如 ^+~%{}()）会被解析为控制键（如 Shift、Ctrl），而非作为字符输入。具体的键指令请参考附录: 输入键对应表。如果希望输入纯文本，无视这些控制键符号，请使用 {textOnly: true} 选项，这样调用：pressKeys(str, {textOnly: true})。

参数:

key: string 类型，要输入的按键、组合键或是字符串，最大支持 1024 个字符。
options: PressKeysOptions | number（可选）
控制输入模式的可选参数，包含以下内容：
- textOnly: boolean 类型，设为 true 时，将所有字符作为普通文本输入，忽略控制键指令，等效于 Keyboard.typeString() 方法。
- cpm: number 类型，即每分钟输入的字符数，用于控制输入速度。建议 cpm 值设置在 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键
command	CMD 键或 Windows 键	取决于系统
alt	Alt键
control	Ctrl键
shift	Shift键
right_shift	右Shift键
space	空格键
printscreen	打印屏幕键	不支持Mac
insert	插入键	不支持Mac
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_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" 键

通过这些方法和示例，你可以灵活处理各种键盘输入场景，特别是涉及组合键的复杂操作。

results matching ""

全部 API Walkthrough 其他

键盘自动化 (Keyboard)

类型定义

API 介绍

keyTap(key, modified)

unicodeTap(key)

keyDown(key, modified)

keyUp(key, modified)

setDelay(delay)

typeString(str, cpm)

pressKeys(keys, options)

disableIme()

Keys

特殊按键 Keys 的用法

使用 Keys 枚举类

组合键操作

示例：使用组合键进行操作

results matching ""

No results matching ""

特殊按键 `Keys` 的用法

使用 `Keys` 枚举类