跳到正文

拟人化输入

启用 humanize 后,SDK 会让鼠标移动、点击、滚动和打字遵循接近真人的轨迹与节奏。showCursor 会绘制指针,方便你观察。

拟人化输入(humanize & showCursor)

传入 humanize 后,所有输入——移动、点击、拖拽、滚动和打字——都遵循同一套拟人化标准,既覆盖页面级操作(page.click / hover / type / fill / mouse.* / keyboard.type),也覆盖 locator 级操作(locator.click / type / fill / pressSequentially / dragTo / …)。移动轨迹是一条从上一次光标位置出发、略带弧度的三次贝塞尔曲线,并按最小加加速度(min-jerk)子运动叠加的方式走完(一次弹道式主运动 + 一次修正运动——也就是真实伸手动作那种多峰的速度曲线,而不是单个对称的钟形曲线),所有操作都以真实、可信的事件派发(isTrusted === true,且 navigator.webdriver 保持为 false)。在 Pro 上,坐标点击(mouse.click(x, y))沿用从真人身上录制的运动轨迹;其他所有操作,以及开源版构建和 GitHub 免费版上的每一次点击,都使用生成的路径。加上 showCursor 会绘制一个跟随运动的圆点,方便你观察。

由于移动使用的是原生输入,用 mouse.down() 按下的鼠标按键会在整个移动过程中保持按住——因此 down → move → up 是一次真正按住按键的拖拽(滑块之类的拖动定位控件收到的是真实按下状态的拖拽),locator.dragTo 同样是拟人化的。打字逐键进行,按键间隔随机化,在词语边界处会停顿,偶尔会打错再改正,还会出现按键重叠(key rollover):在某些快速连按的键对上,下一个键会在上一个键松开之前按下,其发生频率按身份固定(SDK 0.41.1)。fill 会先点击输入框再逐字输入(超过 200 个字符的值会先点击、再一次性插入,免得批量填充慢如蜗牛)。

滚动以完整的鼠标滚轮刻度为单位,分成几次短促的拨动,偶尔会有阅读停顿;如果指针还不在内容上方,会先把指针移过去。浏览器会把每个滚轮事件报告为完整的一格,而真实滚轮的一格在 Windows 上移动 100 px,在 Linux 上移动 120,在 macOS 上移动 40,因此每格的距离跟随页面所报告的平台,请求的距离会四舍五入到最接近的刻度(至少一格):mouse.wheel(0, 800) 在 Windows 身份上滚动 800 px,在 Linux 身份上滚动 840(SDK 0.41.1)。

表单(SDK 0.48.0)

fill 会根据字段类型采取不同做法。文本会被逐字输入,只有字段已有值时才先用按住的按键清空,并检查结果;range 滑块会被拖到精确的值;日期、时间、月份、周或日期时间字段会按浏览器显示的顺序逐段输入。字段容纳不了的值会像以前一样抛出 Playwright 自己的错误。

selectOption 用一次点击打开下拉框,输入选项标签的开头(包括空格),再按 Enter 确认,因此页面看到的是一次可信的变更,而不是每行一次;无法通过输入到达的行用按住的方向键到达。列表框用滚轮滚动,通过点击行来选择,多选时按住 Ctrl 选择额外的行。check / uncheck 只在状态需要改变时才点击。

在密码、电子邮件、数字、电话、URL 或一次性验证码字段中,以及 frame 内的字段中,从不制造打字错误,而且只更正实际输入进去的内容。CLEARCOTE_HUMANIZE_TYPO_RATE 设置每个按键的出错率(默认 0.02;0 关闭打字错误)。所有点击选项都会被遵循(按键、点击次数、按住、修饰键、位置、force、trial),所有 Playwright locator 都可用,而检查点击点是否被遮挡时使用浏览器自身的命中测试,因此指针绝不会先于其路径移动,也不会过早按下。

节奏与准度(SDK 0.49.0)

鼠标路径、拖拽和 ambient_motion / ambientMotion 会保持规划时的时长,即使在繁忙的机器上也是如此。有些路径会越过目标再折回,频率按身份固定;按住按键的拖拽始终在其直线几像素之内,因此滑块手柄不会偏离轨道。SDK 自己执行的每次按下,都会在指针到达后短暂停顿再进行(40 到 250 ms,典型时长按身份固定)。

位于可透过点击的图层(渐变、图标、浮动标签)下方的控件,会像其他控件一样被点击。trial 只运行 Playwright 的检查,完全不执行任何输入。有最大长度或输入掩码的字段(有效期、电话号码)只输入一次,绝不清空后重新输入;日期和时间字段使用与文本相同的按键节奏输入。错误就是 Playwright 自己的错误,措辞也相同。

在 Python、Node 和 .NET(.NET 自 0.58.0 起)中,坐标点击(mouse.click(x, y))可以由浏览器引擎自己移动并按下;在 154 r39 及更早的引擎上,这次按下会在指针到达后约 10 ms 发生,没有停顿。CLEARCOTE_HUMANIZE_ENGINE_CLICKS=off 让所有点击都走 SDK 的路径,=all(需主动开启)则把选择器点击也交给引擎。

from clearcote import launch

browser = launch(fingerprint="seed-123", humanize=True, show_cursor=True)
page = browser.new_page()
page.goto("https://example.com")

page.click("text=Sign in")               # eased curve, then a trusted click
page.fill("#email", "you@example.com")   # focus + key-by-key human typing
page.locator("#password").type("s3cr3t") # locators are humanized too

# held-button drag (e.g. a slider): the press stays held across the move
x0, y0, x1 = 100, 300, 400               # the handle's start, and where to release it
page.mouse.move(x0, y0); page.mouse.down()
page.mouse.move(x1, y0); page.mouse.up()
browser.close()

按住

有些控件只在按键保持按下时才起作用:按住确认的按钮、长按弹出的菜单、要先填满才接受的按住按钮。press_and_hold / pressAndHold / PressAndHoldAsync 会在元素上执行一次长时间的拟人化按压。启用 humanize 后,它在页面上(page.press_and_hold(selector))和每个 locator 上(locator.press_and_hold(),包括 frame locator)都可用;模块函数 press_and_hold(locator) 适用于任何页面。异步 API(clearcote.async_api)使用相同的名称,加 await 调用。

它会等待元素可见并将其带入视图(使用拟人化的滚轮滚动),把指针滑到靠近中心、由身份决定的一个点(或滑到 position,与 Playwright 一样相对于元素左上角),稍作停顿后按下。按键保持按下 duration 毫秒,默认每次在 2.8 到 3.8 秒之间重新取值;或者一直按到 until 返回 true:它每 100 ms 被询问一次,此时 duration 是按住的最长时间(未指定时为 15 秒),按键会在 160 到 350 ms 的人类反应延迟之后松开,而不是在条件变化的同一刻松开。

按键按下期间,静止的手仍会不时让鼠标轻微移动:稀疏的整像素漂移,离按压点从不超过 2 px,每次移动都是可信事件,且报告按键处于按下状态。tremor=False / tremor: false 让指针保持不动。button 选择左键、右键或中键,timeout 是等待元素可见的时长。按住持续了完整时间或 until 变为 true 时返回 true,until 始终没有变为 true 时返回 false。按键总会被松开,包括 until 抛出异常时;在异步 API 中,until 可以是 async 函数,取消调用同样会松开按键。

from clearcote import launch, press_and_hold

browser = launch(fingerprint="seed-123", humanize=True)
page = browser.new_page()
page.goto("https://example.com")

# hold until the button reports it is done (at most 15 s), then let go
done = page.press_and_hold(
    "#hold", until=lambda: page.locator("#hold[data-state=done]").count() > 0
)
print(done)                              # False if the state never changed

# a fixed 4-second hold, pressed 20 px in from the left edge
page.locator("#confirm").press_and_hold(4000, position={"x": 20, "y": 10})

# a control inside an iframe
frame = page.frame_locator("iframe#widget")
frame.locator("#hold").press_and_hold(
    until=lambda: frame.locator("#hold[data-state=done]").count() > 0
)

# the module function works on any Playwright page
press_and_hold(page.locator("#menu-item"), 1200)
browser.close()