跳到主要内容

Keyboard

Keyboard 类提供了一个用于管理虚拟键盘的 API。高级 API 是 keyboard.type()，它可以接收原始字符并在页面上生成正确的 keydown、keypress/input 和 keyup 事件。

如需更精细的控制，可以使用 keyboard.down()、keyboard.up() 和 keyboard.insertText() 来手动触发事件，模拟真实键盘的操作。

以下是一个按住 Shift 键选择并删除文本的示例：

await page.keyboard.type('Hello World!');
await page.keyboard.press('ArrowLeft');

await page.keyboard.down('Shift');
for (let i = 0; i < ' World'.length; i++)
  await page.keyboard.press('ArrowLeft');
await page.keyboard.up('Shift');

await page.keyboard.press('Backspace');
// 最终文本将显示为 'Hello!'

以下是一个输入大写字母 A 的示例：

await page.keyboard.press('Shift+KeyA');
// 或者
await page.keyboard.press('Shift+A');

以下是一个通过键盘触发全选操作的示例：

await page.keyboard.press('ControlOrMeta+A');

方法​

down​

v1.9 之前添加 keyboard.down

触发一个 keydown 事件。

key 可以指定预期的 keyboardEvent.key 值或单个字符来生成文本。key 值的超集可以在这里找到。按键示例包括：

F1 - F12、Digit0- Digit9、KeyA- KeyZ、Backquote、Minus、Equal、Backslash、Backspace、Tab、Delete、Escape、ArrowDown、End、Enter、Home、Insert、PageDown、PageUp、ArrowRight、ArrowUp 等。

还支持以下修饰快捷键：Shift、Control、Alt、Meta、ShiftLeft、ControlOrMeta。ControlOrMeta 在 Windows 和 Linux 上解析为 Control，在 macOS 上解析为 Meta。

按住 Shift 键将输入与 key 对应的大写文本。

如果 key 是单个字符，则区分大小写，因此值 a 和 A 将生成不同的文本。

如果 key 是修饰键 Shift、Meta、Control 或 Alt，则后续按键将保持该修饰键激活状态。要释放修饰键，请使用 keyboard.up()。

按键按下一次后，后续调用 keyboard.down() 会将 repeat 设置为 true。要释放按键，请使用 keyboard.up()。

备注

修饰键确实会影响 keyboard.down。按住 Shift 键将输入大写文本。

用法

await keyboard.down(key);

参数

  • key string#

    要按下的键名或要生成的字符，例如 ArrowLeft 或 a。

返回值

insertText​

v1.9 版本前添加 keyboard.insertText

仅派发 input 事件，不会触发 keydown、keyup 或 keypress 事件。

用法

page.keyboard.insertText('嗨');

:::注意 修饰键不会影响 keyboard.insertText 的行为。按住 Shift 键不会使输入的文本变为大写。 :::

参数

  • text string#

    将输入内容设置为指定的文本值。

返回值

press​

v1.9 版本前添加 keyboard.press
提示

在大多数情况下，你应该使用 locator.press() 替代。

key 可以指定预期的 keyboardEvent.key 值或单个字符来生成文本。完整的 key 值超集可以在 这里 找到。按键示例包括：

F1 - F12, Digit0- Digit9, KeyA- KeyZ, Backquote, Minus, Equal, Backslash, Backspace, Tab, Delete, Escape, ArrowDown, End, Enter, Home, Insert, PageDown, PageUp, ArrowRight, ArrowUp 等。

还支持以下修饰快捷键：Shift, Control, Alt, Meta, ShiftLeft, ControlOrMeta。ControlOrMeta 在 Windows 和 Linux 上解析为 Control，在 macOS 上解析为 Meta。

按住 Shift 键会输入对应 key 的大写文本。

如果 key 是单个字符，则区分大小写，因此值 a 和 A 会生成不同的文本。

也支持诸如 key: "Control+o", key: "Control++ 或 key: "Control+Shift+T" 这样的快捷键。当指定修饰键时，修饰键会被按下并保持，同时后续的键被按下。

用法

const page = await browser.newPage();
await page.goto('https://keycode.info');
await page.keyboard.press('A');
await page.screenshot({ path: 'A.png' });
await page.keyboard.press('ArrowLeft');
await page.screenshot({ path: 'ArrowLeft.png' });
await page.keyboard.press('Shift+O');
await page.screenshot({ path: 'O.png' });
await browser.close();

这是 keyboard.down() 和 keyboard.up() 的快捷方式。

参数

  • key string#

    要按下的键名或要生成的字符，例如 ArrowLeft 或 a。

  • options Object (可选)

    • delay number (可选)#

      keydown 和 keyup 之间的等待时间（毫秒）。默认为 0。

返回

type​

v1.9 版本前添加 keyboard.type
警告

大多数情况下，你应该使用 locator.fill() 替代。只有当页面有特殊键盘处理时，才需要逐个按键 - 这种情况下请使用 locator.pressSequentially()。

为文本中的每个字符发送 keydown、keypress/input 和 keyup 事件。

要按下特殊键（如 Control 或 ArrowDown），请使用 keyboard.press()。

用法

await page.keyboard.type('Hello'); // 立即输入
await page.keyboard.type('World', { delay: 100 }); // 像用户一样缓慢输入
备注

修饰键不会影响 keyboard.type。按住 Shift 不会输入大写文本。

备注

对于不在美式键盘上的字符，只会发送 input 事件。

参数

  • text string#

    要输入到焦点元素中的文本。

  • options Object (可选)

    • delay number (可选)#

      按键之间的等待时间（毫秒）。默认为 0。

返回值

up​

v1.9 版本前添加 keyboard.up

触发一个 keyup 事件。

用法

await keyboard.up(key);

参数

  • key string#

    要按下的键名或要生成的字符，例如 ArrowLeft 或 a。

返回值