Keyboard Automation

The Keyboard object is used to simulate keyboard operations, including key presses, key releases, and the input of key combinations. It is suitable for scenarios that require automated keyboard input, such as when direct input through UI controls is not possible, or when complex shortcut key sequences need to be simulated. The Keyboard object makes it easy to accomplish these tasks.

You can import the Keyboard object as follows:

const { Keyboard } = require('leanpro.common');

from leanproAuto import Keyboard

The Keyboard object provides the following methods:

Type Definitions

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 Description

keyTap(key, modified)

Press a key.

Parameters:

• key: string type. The key value to press, refer to the Keys table.
• modified: string | string[] type (optional). The modifier key(s) to press, supporting one or multiple keys (e.g., "control", "shift"). To perform a combination key operation, pass multiple modifier keys as an array.

Return Value:

• A synchronous method that returns nothing.

Usage Example

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)

Press a key specified by Unicode.

Parameters:

• key: number type. The Unicode value of the target key.

Return Value:

• A synchronous method that returns nothing.

Usage Example

Keyboard.unicodeTap(65)  // Press "A" key

Keyboard.unicodeTap(65)  # Press "A" key

In JavaScript, you can use the string method charCodeAt to get the key code. The following code outputs the string, equivalent to calling pressKeys():

'您好，中国(China)'.split('').map(k => Keyboard.unicodeTap(k.charCodeAt(0)))

keyDown(key, modified)

Hold down a key.

Parameters:

• key: string type. The key value to hold, refer to the Keys table.
• modified: string | string[] type (optional). Modifier key(s), can be one or multiple keys (e.g., "control", "shift"). For combination key operations, pass an array of multiple modifiers.

Return Value:

• A synchronous method that returns nothing.

Usage Example

Keyboard.keyDown("control")  // Hold "control"
Keyboard.keyDown("c", "control")  // Hold "control + c"
Keyboard.keyDown("b", ["control", "shift"])  // Hold "control + shift + b"

Keyboard.keyDown("control")  # Hold "control"
Keyboard.keyDown("c", "control")  # Hold "control + c"
Keyboard.keyDown("b", ["control", "shift"])  # Hold "control + shift + b"

keyUp(key, modified)

Release a key.

Parameters:

• key: string type. The key value to release, refer to the Keys table.
• modified: string | string[] type (optional). Modifier key(s), can be one or multiple keys (e.g., "control", "shift"). For combination key operations, pass an array of multiple modifiers.

Return Value:

• A synchronous method that returns nothing.

Usage Example

Keyboard.keyUp("control")  // Release "control"
Keyboard.keyUp("c", "control")  // Release "control + c"
Keyboard.keyUp("b", ["control", "shift"])  // Release "control + shift + b"

Keyboard.keyUp("control")  # Release "control"
Keyboard.keyUp("c", "control")  # Release "control + c"
Keyboard.keyUp("b", ["control", "shift"])  # Release "control + shift + b"

setDelay(delay)

Set the interval between each keyboard operation, default is 10ms.

Parameters:

• delay: number type. Interval time in milliseconds.

Return Value:

• A synchronous method that returns nothing.

Usage Example

Keyboard.setDelay(100)

Keyboard.setDelay(100)

typeString(str, cpm)

Deprecated. Recommended to use pressKeys(str, {textOnly: true}) instead.

Type a string.

Parameters:

• str: string type. The string to type.
• cpm: (optional) number type. Characters per minute. For some applications that cannot handle rapid input properly, reduce cpm (e.g., 60).

Return Value:

• An asynchronous method that returns nothing.

Usage Example

await Keyboard.typeString("Hello, World!", 100)

Keyboard.typeString("Hello, World!", 100)

pressKeys(keys, options)

Simulate keyboard signals to input strings or perform combination key operations. Suitable for simple text input as well as complex operations like login, navigation, cut, and paste.

Note: Some special characters in the string (e.g., ^+~%{}()) are interpreted as control keys (Shift, Ctrl) instead of text input. For pure text input ignoring control characters, use {textOnly: true}: pressKeys(str, {textOnly: true}).

Parameters:

• keys: string type. Keys, combination keys, or string to input, max 1024 characters.

• options: PressKeysOptions | number (optional). Options controlling input mode:

  • textOnly: boolean. If true, treat all characters as plain text, equivalent to Keyboard.typeString().
  • cpm: number. Characters per minute to control input speed. Recommended above 200. Actual speed may vary depending on system/application.

  If a number is passed directly as options, it is treated as cpm.

Return Value:

• An asynchronous method that returns nothing.

Usage Example

await Keyboard.pressKeys("Hello, World!", { textOnly: true })

Keyboard.pressKeys("Hello, World!", { "textOnly": True })

disableIme()

Disable the input method of the currently focused application. This prevents interference when calling other keyboard input methods like typeString or pressKeys.

Return Value:

• An asynchronous method that returns nothing.

Note: Input method is app-specific. When launching a new application under test, you may need to call disableIme() again.

Usage Example

await Keyboard.disableIme()

Keyboard.disableIme()

Keys

Keys is an enumeration object listing all keys usable with keyTap, keyDown, and keyUp. The table describes the key names and their functions.

Note: For letter and number keys, you can use the character directly. For example, use "b" or "5" for letters and digits.

Windows Logo Key: A special control key on Windows, similar to Mac's cmd, can be represented as "command".

Special Keys Keys Usage

The Keys enum is commonly used for handling special keys like Ctrl and Shift. It can be used with keyDown(), keyUp(), and keyTap() methods to simulate key operations. For example, to perform a "Select All" operation by pressing Ctrl + A, the code examples are:

const { Keyboard } = require('leanpro.common');

// Method 1: Press and release control key separately
Keyboard.keyDown('control');
Keyboard.keyTap('a');
Keyboard.keyUp('control');

// Method 2: Tap combination key
Keyboard.keyTap('a', 'control');

from leanproAuto import Keyboard

# Method 1: Press and release control key separately
Keyboard.keyDown('control')
Keyboard.keyTap('a')
Keyboard.keyUp('control')

# Method 2: Tap combination key
Keyboard.keyTap('a', 'control')

Using the Keys Enum

By default, keyTap, keyDown, and keyUp methods can directly accept simple characters (e.g., 'a'). For strings like 'control', they automatically match the Keys enum. To explicitly use the Keys enum, you can write:

const { Keyboard, Keys } = require('leanpro.common');

// Using the Keys enum
Keyboard.keyDown(Keys.control);
Keyboard.keyTap('a');
Keyboard.keyUp(Keys.control);

// Equivalent to
Keyboard.keyTap('a', Keys.control);

Note: To input a literal string like "control" without triggering a special key, use pressKeys(str, { textOnly: true }).

Combination Key Operations

To perform operations while holding a control key (e.g., Ctrl) for actions like drag or click, you can use keyDown() and keyUp(). For example, holding the Shift key while performing other operations:

const { Keyboard } = require('leanpro.common');

// Hold the Shift key
Keyboard.keyDown('shift');
// Perform other operations here
// ...
// Release the Shift key
Keyboard.keyUp('shift');

from leanproAuto import Keyboard

# Hold the Shift key
Keyboard.keyDown('shift')
# Perform other operations here
# ...
# Release the Shift key
Keyboard.keyUp('shift')

Example: Using Combination Keys

Here are some examples of combination key operations, including pressing Ctrl or Shift with letter keys:

const { Keyboard } = require('leanpro.common');

// Press and release combination keys
Keyboard.keyTap('c', 'control');  // Press "control + c"
Keyboard.keyTap('b', ['control', 'shift']);  // Press "control + shift + b"

// Hold combination keys to perform actions
Keyboard.keyDown('shift');  // Hold "shift"
// Perform actions
Keyboard.keyUp('shift');  // Release "shift"

from leanproAuto import Keyboard

# Press and release combination keys
Keyboard.keyTap('c', 'control')  # Press "control + c"
Keyboard.keyTap('b', ['control', 'shift'])  # Press "control + shift + b"

# Hold combination keys to perform actions
Keyboard.keyDown('shift')  # Hold "shift"
# Perform actions
Keyboard.keyUp('shift')  # Release "shift"

Through these methods and examples, you can flexibly handle various keyboard input scenarios, especially complex operations involving combination keys.