Keyboard

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

如需更精细的控制，可以使用 Keyboard.DownAsync()、Keyboard.UpAsync() 和 Keyboard.InsertTextAsync() 手动触发事件，就好像它们是从真实键盘生成的一样。

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

await page.Keyboard.TypeAsync("Hello World!");
await page.Keyboard.PressAsync("ArrowLeft");

await page.Keyboard.DownAsync("Shift");
for (int i = 0; i < " World".Length; i++)
    await page.Keyboard.PressAsync("ArrowLeft");

await page.Keyboard.UpAsync("Shift");

await page.Keyboard.PressAsync("Backspace");
// 最终文本将变为 "Hello!"

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

await page.Keyboard.PressAsync("Shift+KeyA");
// 或者
await page.Keyboard.PressAsync("Shift+A");

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

await page.Keyboard.PressAsync("ControlOrMeta+A");

---

方法

DownAsync

在 v1.9 之前添加 keyboard.DownAsync

派发 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。在 Windows 和 Linux 上，ControlOrMeta 解析为 Control；在 macOS 上，解析为 Meta。

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

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

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

按下某个键一次后，后续对 Keyboard.DownAsync() 的调用将把 repeat 设置为 true。要释放该键，请使用 Keyboard.UpAsync()。

备注

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

用法

await Keyboard.DownAsync(key);

参数

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

返回值

• void#

---

InsertTextAsync

在 v1.9 之前添加 keyboard.InsertTextAsync

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

用法

await page.Keyboard.PressAsync("嗨");

备注

修饰键对 keyboard.insertText 无效。按住 Shift 不会输入大写文本。

参数

• text string# 将输入设置为指定的文本值。

返回值

• void#

---

PressAsync

在 v1.9 之前添加 keyboard.PressAsync

提示

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

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" 之类的快捷键也受支持。当指定了修饰键时，按下后续键时，修饰键将被按下并保持按下状态。

使用方法

await page.GotoAsync("https://keycode.info");
await page.Keyboard.PressAsync("A");
await page.ScreenshotAsync(new() { Path = "A.png" });
await page.Keyboard.PressAsync("ArrowLeft");
await page.ScreenshotAsync(new() { Path = "ArrowLeft.png" });
await page.Keyboard.PressAsync("Shift+O");
await page.ScreenshotAsync(new() { Path = "O.png" });
await browser.CloseAsync();

这是 Keyboard.DownAsync() 和 Keyboard.UpAsync() 的快捷方式。

参数

• key string#

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

• options KeyboardPressOptions?（可选）

  • Delay [float]?（可选）#

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

返回值

• void#

---

TypeAsync

在 v1.9 之前添加 keyboard.TypeAsync

警告

在大多数情况下，你应该使用 Locator.FillAsync() 代替。只有在页面上有特殊的键盘处理时，你才需要逐个按键 - 在这种情况下，使用 Locator.PressSequentiallyAsync()。

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

要按下特殊键，如 Control 或 ArrowDown，请使用 Keyboard.PressAsync()。

用法

await page.Keyboard.TypeAsync("Hello"); // 立即输入
await page.Keyboard.TypeAsync("World", new() { Delay = 100 }); // 输入速度较慢，类似用户输入

备注

修饰键对 keyboard.type 无效。按住 Shift 键不会输入大写文本。

备注

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

参数

• text string#

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

• options KeyboardTypeOptions?（可选）

  • Delay [float]?（可选）#

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

返回值

• void#

---

UpAsync

在 v1.9 之前添加 keyboard.UpAsync

派发一个 keyup 事件。

用法

await Keyboard.UpAsync(key);

参数

• key string#

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

返回值

• void#