跳到主要内容

Keyboard

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

如果需要更精细的控制，可以使用 keyboard.down()、keyboard.up() 和 keyboard.insert_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")

以下是通过键盘触发全选的示例

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 会输入大写字符。

用法

keyboard.down(key)

参数

  • key str#

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

返回值

insert_text​

v1.9 之前添加 keyboard.insert_text

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

用法

page.keyboard.insert_text("嗨")
备注

修饰键不会影响 keyboard.insertText。按住 Shift 不会输入大写字符。

参数

  • text str#

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

返回值

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" 这样的快捷键。当指定修饰键时，修饰键会被按下并保持，直到后续按键被按下。 用法

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

参数

  • key str#

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

  • delay float (可选)#

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

返回值

type​

v1.9 之前添加 keyboard.type
警告

大多数情况下，你应该使用 locator.fill()。只有当页面有特殊的键盘处理时，才需要逐个按键输入——此时请使用 locator.press_sequentially()。

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

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

用法

page.keyboard.type("Hello") # 立即输入
page.keyboard.type("World", delay=100) # 慢速输入，类似用户操作
备注

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

备注

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

参数

  • text str#

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

  • delay float (可选)#

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

返回值

up​

v1.9 之前添加 keyboard.up

派发一个 keyup 事件。

用法

keyboard.up(key)

参数

  • key str#

    要释放的按键名称或用于生成文本的字符，例如 ArrowLeft 或 a。

返回值