Playwright for Python：Keyboard 类中文版文档

Keyboard 类用于模拟浏览器中的键盘输入操作，支持单个按键触发、组合键（如 Ctrl+C）、文本连续输入等场景，还原真实用户的键盘操作行为。Keyboard 实例可通过 page.keyboard 或 frame.keyboard 获取，操作作用于当前活跃的页面/框架。

快速示例

同步示例

from playwright.sync_api import sync_playwright, Playwright

def run(playwright: Playwright):
    browser = playwright.chromium.launch(headless=False)
    context = browser.new_context()
    page = context.new_page()
    page.goto("https://example.com")
    
    # 获取键盘实例
    keyboard = page.keyboard
    
    # 点击输入框激活
    page.click("input[type='text']")
    # 输入文本
    keyboard.type("Hello Playwright!")
    # 组合键：全选（Ctrl+A）
    keyboard.press("Control+A")
    # 组合键：复制（Ctrl+C）
    keyboard.press("Control+C")
    # 组合键：粘贴（Ctrl+V）
    keyboard.press("Control+V")
    # 按下并释放单个按键（Enter）
    keyboard.down("Enter")
    keyboard.up("Enter")

    browser.close()

with sync_playwright() as playwright:
    run(playwright)

异步示例

import asyncio
from playwright.async_api import async_playwright, Playwright

async def run(playwright: Playwright):
    browser = await playwright.firefox.launch()
    context = await browser.new_context()
    page = await context.new_page()
    await page.goto("https://example.com")
    
    # 获取键盘实例
    keyboard = page.keyboard
    
    # 激活输入框并输入密码
    await page.click("input[type='password']")
    await keyboard.type("my_secure_password")
    # 模拟大写锁定+输入
    await keyboard.press("CapsLock")
    await keyboard.type("ADMIN")
    await keyboard.press("CapsLock")
    # 按下ESC键
    await keyboard.press("Escape")

    await browser.close()

async def main():
    async with async_playwright() as playwright:
        await run(playwright)

asyncio.run(main())

核心方法

down

按下指定按键并保持按下状态（不释放），适用于需要长按按键的场景（如组合键前置、长按删除等）。

用法示例

# 同步
keyboard.down("Shift")  # 按住Shift键
keyboard.type("hello")  # 输入结果为"HELLO"
keyboard.up("Shift")    # 释放Shift键

# 异步
await keyboard.down("Shift")
await keyboard.type("hello")
await keyboard.up("Shift")

参数说明

• key：按键标识，支持普通字符（如 a、1）、功能键（如 Shift、Enter、Backspace）、修饰键（如 Control、Alt），完整按键列表参考下方「按键标识说明」。
• delay（可选）：按键按下后延迟时间（毫秒），模拟真实用户操作间隔，默认 0。

insert_text

插入纯文本内容到当前焦点元素，与 type 方法的区别是：不触发键盘事件的模拟，仅直接插入文本内容，适用于无需模拟按键行为、仅需填充文本的场景。

用法示例

# 同步
page.click("input#username")
keyboard.insert_text("user123")  # 直接插入文本，不模拟按键过程

# 异步
await page.click("input#username")
await keyboard.insert_text("user123")

参数说明

• text：需要插入的纯文本字符串。
• delay（可选）：每个字符插入后的延迟时间（毫秒），默认 0。

与 type 方法的核心区别

特性	insert_text	type
键盘事件模拟	不触发（仅修改元素值）	触发完整的 keydown/keypress/keyup 事件
特殊按键支持	不支持（仅纯文本）	支持功能键、修饰键组合
适用场景	快速填充文本、忽略按键行为	还原真实用户键盘操作、需要触发按键事件

press

按下并立即释放指定按键（完整的按键操作），适用于单个按键触发（如 Enter、Escape）或组合键（如 Ctrl+S）。

用法示例

# 同步
# 单个按键
keyboard.press("Enter")  # 回车
keyboard.press("Backspace")  # 回删
keyboard.press("Tab")  # 制表符切换焦点
# 组合键（多个按键用"+"连接）
keyboard.press("Control+S")  # 保存
keyboard.press("Shift+Alt+A")  # 多修饰键组合
keyboard.press("Meta+V")  # Mac系统的粘贴（Meta对应Command键）

# 异步
await keyboard.press("Enter")
await keyboard.press("Control+S")
await keyboard.press("Meta+V")

参数说明

• key：按键标识（支持单个按键或组合键，组合键用 + 分隔）。
• delay（可选）：按键释放后的延迟时间（毫秒），默认 0。

type

模拟真实用户的文本输入过程，逐个字符触发 keydown/keypress/keyup 事件，支持特殊字符和按键延迟，还原真实输入行为。

用法示例

# 同步
# 基础文本输入
keyboard.type("Hello World!")
# 带延迟输入（每个字符间隔100毫秒）
keyboard.type("My Email: test@example.com", delay=100)
# 输入包含特殊字符的内容
keyboard.type("!@#$%^&*()_+")

# 异步
await keyboard.type("Hello World!")
await keyboard.type("My Email: test@example.com", delay=100)

参数说明

• text：需要输入的文本字符串（支持普通字符和部分可打印特殊字符）。
• delay（可选）：每个字符输入的间隔时间（毫秒），默认 0，设置后更贴近真实用户输入速度。

up

释放之前通过 down 方法按下的按键，完成“按下-释放”的完整流程。

用法示例

# 同步：模拟长按删除
keyboard.down("Backspace")
# 长按500毫秒
import time
time.sleep(0.5)
keyboard.up("Backspace")

# 异步：模拟长按方向键
await keyboard.down("ArrowRight")
await asyncio.sleep(0.5)
await keyboard.up("ArrowRight")

参数说明

• key：需要释放的按键标识（与 down 方法的 key 参数一致）。
• delay（可选）：按键释放后的延迟时间（毫秒），默认 0。

按键标识说明

Playwright 支持的按键标识分为以下几类，部分核心按键如下：

1. 修饰键

按键标识	对应键盘按键	备注
Control	Ctrl（Windows/Linux）	组合键常用修饰符
Shift	Shift	大小写切换、特殊字符输入
Alt	Alt（Windows/Linux）	功能快捷键修饰符
Meta	Command（Mac）/ Win（Windows）	Mac系统核心修饰键

2. 功能键

按键标识	对应键盘按键
Enter	回车键
Escape	ESC键
Backspace	回删键（删除左侧字符）
Delete	删除键（删除右侧字符）
Tab	制表符键
CapsLock	大写锁定键
F1-F12	功能键F1至F12
PageUp	上翻页键
PageDown	下翻页键
Home	首页键
End	尾页键

3. 方向键

按键标识	对应键盘按键
ArrowUp	上方向键
ArrowDown	下方向键
ArrowLeft	左方向键
ArrowRight	右方向键

4. 普通字符

• 字母：a-z、A-Z（大小写不敏感，可通过 Shift 键控制）
• 数字：0-9
• 特殊字符：!、@、#、$ 等（可直接输入或通过 Shift+对应按键 模拟）

常用场景实战

场景1：模拟表单填写与提交

# 同步
page.click("#username")
keyboard.type("admin", delay=50)
page.click("#password")
keyboard.type("123456", delay=50)
# 提交表单（Enter键）
keyboard.press("Enter")

# 异步
await page.click("#username")
await keyboard.type("admin", delay=50)
await page.click("#password")
await keyboard.type("123456", delay=50)
await keyboard.press("Enter")

场景2：快捷键操作（复制/粘贴/全选）

# 同步
# 全选文本
keyboard.press("Control+A")
# 复制
keyboard.press("Control+C")
# 切换输入框
page.click("#target-input")
# 粘贴
keyboard.press("Control+V")

# 异步
await keyboard.press("Control+A")
await keyboard.press("Control+C")
await page.click("#target-input")
await keyboard.press("Control+V")

场景3：长按按键模拟（批量删除文本）

# 同步
page.click("#content-input")
# 长按Backspace删除所有内容
keyboard.down("Backspace")
import time
time.sleep(1)  # 长按1秒
keyboard.up("Backspace")

# 异步
await page.click("#content-input")
await keyboard.down("Backspace")
await asyncio.sleep(1)
await keyboard.up("Backspace")

场景4：区分Windows/Mac系统快捷键

# 同步
import sys
if sys.platform == "darwin":
    # Mac系统：Command+V粘贴
    keyboard.press("Meta+V")
else:
    # Windows/Linux系统：Ctrl+V粘贴
    keyboard.press("Control+V")

# 异步
import sys
if sys.platform == "darwin":
    await keyboard.press("Meta+V")
else:
    await keyboard.press("Control+V")

重要说明

1. 焦点前置：使用 Keyboard 操作前，需确保目标元素已获得焦点（可通过 page.click() 激活元素），否则输入会失效。
2. 组合键顺序：使用 down/up 模拟组合键时，需先按下修饰键（如 Control），再按下普通键，最后按相反顺序释放。
3. 特殊字符处理：对于无法直接输入的特殊字符（如换行符），可使用 keyboard.press("Enter") 替代，而非 type("\n")。
4. 延迟配置：设置 delay 参数（如 type(text, delay=50)）可模拟真实用户的输入速度，避免被网站的反爬机制识别。
5. Mac系统兼容：Mac 系统的核心修饰键为 Meta（对应 Command 键），使用时需与 Windows/Linux 系统区分。

---

要不要我帮你整理 Keyboard 类常用快捷键对照表，包含Windows/Mac双系统的常用操作（如复制、粘贴、截图等），方便快速查阅使用？