Keyboard

Keyboard 提供了用于管理虚拟键盘的 api。高级 API 是 keyboard.type()，它采用原始字符并在页面上生成适当的 keydown、keypress/input 和 keyup 事件。

¥Keyboard provides an api for managing a virtual keyboard. The high level api is keyboard.type(), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page.

为了更好地控制，你可以使用 keyboard.down()、keyboard.up() 和 keyboard.insertText() 手动触发事件，就像它们是从真正的键盘生成的一样。

¥For finer control, you can use keyboard.down(), keyboard.up(), and keyboard.insertText() to manually fire events as if they were generated from a real keyboard.

按住 Shift 以选择和删除某些文本的示例：

¥An example of holding down Shift in order to select and delete some text:

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');
// Result text will end up saying 'Hello!'

按大写 A 的示例

¥An example of pressing uppercase A

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

使用键盘触发全选的示例

¥An example to trigger select-all with the keyboard

// on Windows and Linux
await page.keyboard.press('Control+A');
// on macOS
await page.keyboard.press('Meta+A');

---

方法

¥Methods

down

Added before v1.9 keyboard.down

调度 keydown 事件。

¥Dispatches a keydown event.

key 可以指定预期的 keyboardEvent.key 值或单个字符来生成文本。可以找到 key 值的超集 此处。键的示例有：

¥key can specify the intended keyboardEvent.key value or a single character to generate the text for. A superset of the key values can be found here. Examples of the keys are:

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

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

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

¥Following modification shortcuts are also supported: Shift, Control, Alt, Meta, ShiftLeft, ControlOrMeta. ControlOrMeta resolves to Control on Windows and Linux and to Meta on macOS.

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

¥Holding down Shift will type the text that corresponds to the key in the upper case.

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

¥If key is a single character, it is case-sensitive, so the values a and A will generate different respective texts.

如果 key 是修饰键、Shift、Meta、Control 或 Alt，则后续按键将在该修饰键处于活动状态时发送。要释放修饰键，请使用 keyboard.up()。

¥If key is a modifier key, Shift, Meta, Control, or Alt, subsequent key presses will be sent with that modifier active. To release the modifier key, use keyboard.up().

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

¥After the key is pressed once, subsequent calls to keyboard.down() will have repeat set to true. To release the key, use keyboard.up().

注意

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

¥Modifier keys DO influence keyboard.down. Holding down Shift will type the text in upper case.

用法

¥Usage

await keyboard.down(key);

参数

¥Arguments

• key string#

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

¥Name of the key to press or a character to generate, such as ArrowLeft or a.

返回

¥Returns

• Promise<void>#

---

insertText

Added before v1.9 keyboard.insertText

仅调度 input 事件，不触发 keydown、keyup 或 keypress 事件。

¥Dispatches only input event, does not emit the keydown, keyup or keypress events.

用法

¥Usage

page.keyboard.insertText('嗨');

注意

修改键不会影响 keyboard.insertText。按住 Shift 将不会键入大写文本。

¥Modifier keys DO NOT effect keyboard.insertText. Holding down Shift will not type the text in upper case.

参数

¥Arguments

• text string#

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

¥Sets input to the specified text value.

返回

¥Returns

• Promise<void>#

---

press

Added before v1.9 keyboard.press

提示

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

¥In most cases, you should use locator.press() instead.

key 可以指定预期的 keyboardEvent.key 值或单个字符来生成文本。可以找到 key 值的超集 此处。键的示例有：

¥key can specify the intended keyboardEvent.key value or a single character to generate the text for. A superset of the key values can be found here. Examples of the keys are:

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

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

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

¥Following modification shortcuts are also supported: Shift, Control, Alt, Meta, ShiftLeft, ControlOrMeta. ControlOrMeta resolves to Control on Windows and Linux and to Meta on macOS.

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

¥Holding down Shift will type the text that corresponds to the key in the upper case.

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

¥If key is a single character, it is case-sensitive, so the values a and A will generate different respective texts.

还支持 key: "Control+o"、key: "Control++ 或 key: "Control+Shift+T" 等快捷方式。当使用修饰符指定时，修饰符将被按下并在按下后续键的同时保持不变。

¥Shortcuts such as key: "Control+o", key: "Control++ or key: "Control+Shift+T" are supported as well. When specified with the modifier, modifier is pressed and being held while the subsequent key is being pressed.

用法

¥Usage

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() 的快捷方式。

¥Shortcut for keyboard.down() and keyboard.up().

参数

¥Arguments

• key string#

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

¥Name of the key to press or a character to generate, such as ArrowLeft or a.

• options Object (optional)

  • delay number (optional)#

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

¥Time to wait between keydown and keyup in milliseconds. Defaults to 0.

返回

¥Returns

• Promise<void>#

---

type

Added before v1.9 keyboard.type

提醒

在大多数情况下，你应该使用 locator.fill()。如果页面上有特殊的键盘处理，则只需一一按键即可 - 在本例中使用 locator.pressSequentially()。

¥In most cases, you should use locator.fill() instead. You only need to press keys one by one if there is special keyboard handling on the page - in this case use locator.pressSequentially().

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

¥Sends a keydown, keypress/input, and keyup event for each character in the text.

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

¥To press a special key, like Control or ArrowDown, use keyboard.press().

用法

¥Usage

await page.keyboard.type('Hello'); // Types instantly
await page.keyboard.type('World', { delay: 100 }); // Types slower, like a user

注意

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

¥Modifier keys DO NOT effect keyboard.type. Holding down Shift will not type the text in upper case.

注意

对于非美式键盘上的字符，仅发送 input 事件。

¥For characters that are not on a US keyboard, only an input event will be sent.

参数

¥Arguments

• text string#

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

¥A text to type into a focused element.

• options Object (optional)

  • delay number (optional)#

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

¥Time to wait between key presses in milliseconds. Defaults to 0.

返回

¥Returns

• Promise<void>#

---

up

Added before v1.9 keyboard.up

调度 keyup 事件。

¥Dispatches a keyup event.

用法

¥Usage

await keyboard.up(key);

参数

¥Arguments

• key string#

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

¥Name of the key to press or a character to generate, such as ArrowLeft or a.

返回

¥Returns

• Promise<void>#