Skip to main content

Keyboard

Keyboard 提供用于管理虚拟键盘的 API。最常用的高级 API 是 keyboard.type(text, **kwargs)，它会根据原始字符自动生成页面上的 keydown、keypress/input 与 keyup 事件。

如需更精细的控制，可以使用 keyboard.down(key)、keyboard.up(key) 以及 keyboard.insert_text(text) 手动触发事件，就像真实键盘发出的输入一样。

下面的示例展示了按住 Shift 选择并删除部分文本：

page.keyboard.type("Hello World!")
page.keyboard.press("ArrowLeft")
page.keyboard.down("Shift")
for i in range(6):
    page.keyboard.press("ArrowLeft")
page.keyboard.up("Shift")
page.keyboard.press("Backspace")
# 最终的文本将显示为 "Hello!"

以下示例演示如何输入大写的 A：

page.keyboard.press("Shift+KeyA")
# 或者
page.keyboard.press("Shift+A")

下面的示例会通过键盘触发全选：

# Windows 和 Linux
page.keyboard.press("Control+A")
# macOS
page.keyboard.press("Meta+A")

keyboard.down(key)​

Added in: v1.8
  • key <str> 要按下的键名或要生成的字符，例如 ArrowLeft 或 a。#
  • returns: <NoneType>#

触发一次 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。

按住 Shift 会输入该键对应的大写字符。

如果 key 是单个字符，则区分大小写，也就是说 a 和 A 会产生不同的内容。

如果 key 是 Shift、Meta、Control、Alt 等修饰键，则之后的按键事件都会带着该修饰键处于按下状态。要释放修饰键，请调用 keyboard.up(key)。

第一次按键后，再次调用 keyboard.down(key) 会把 repeat 标记设为 true。若要释放该键，请调用 keyboard.up(key)。

note

修饰键会影响 keyboard.down，例如按住 Shift 将会以大写形式输入文本。

keyboard.insert_text(text)​

Added in: v1.8

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

page.keyboard.insert_text("嗨")
note

修饰键不会影响 keyboard.insertText，按住 Shift 也不会以大写形式输出文本。

keyboard.press(key, **kwargs)​

Added in: v1.8
  • key <str> 要按下的键名或要生成的字符，例如 ArrowLeft 或 a。#
  • delay <float> keydown 与 keyup 之间的等待时间，单位为毫秒，默认 0。#
  • returns: <NoneType>#

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。

按住 Shift 会输入该键对应的大写字符。

如果 key 是单个字符，则区分大小写，也就是说 a 和 A 会产生不同的内容。

也支持 key: "Control+o"、key: "Control+Shift+T" 等快捷键写法。指定修饰键后，系统会在按下后续按键时保持修饰键处于按下状态。

page = browser.new_page()
page.goto("https://keycode.info")
page.keyboard.press("a")
page.screenshot(path="a.png")
page.keyboard.press("ArrowLeft")
page.screenshot(path="arrow_left.png")
page.keyboard.press("Shift+O")
page.screenshot(path="o.png")
browser.close()

这是 keyboard.down(key) 与 keyboard.up(key) 的组合式快捷调用。

keyboard.type(text, **kwargs)​

Added in: v1.8
  • text <str> 要输入到当前聚焦元素中的文本。#
  • delay <float> 每次按键之间的间隔，单位为毫秒，默认 0。#
  • returns: <NoneType>#

对文本中的每个字符依次发送 keydown、keypress/input、keyup 事件。

如需按下 Control、ArrowDown 等特殊按键，请改用 keyboard.press(key, **kwargs)。

page.keyboard.type("Hello") # 立即输入
page.keyboard.type("World", delay=100) # 加入延迟，更接近真实用户
note

修饰键不会影响 keyboard.type，按住 Shift 也不会以大写形式输出文本。

note

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

keyboard.up(key)​

Added in: v1.8
  • key <str> 要释放的键名或要生成的字符，例如 ArrowLeft 或 a。#
  • returns: <NoneType>#

触发一次 keyup 事件。