键盘与鼠标
🌐 Keyboard & Mouse
Keyboard
browser_press_key
按下键盘上的一个键。这个键是在页面上按下的，而不是在某个特定的元素上——如果元素很重要，先让它获得焦点（例如用 browser_click）。
🌐 Press a key on the keyboard. The key is pressed on the page, not on a specific element — focus the
element first (for example with browser_click) if it matters.
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
key | 字符串 | 是 | 要按的键的名称或要生成的字符，例如 ArrowLeft 或 a |
常用按键： Enter、Tab、Escape、Backspace、Delete、ArrowUp、ArrowDown、ArrowLeft、ArrowRight、Home、End、PageUp、PageDown
组合键： Control+a, Control+c, Control+v, Shift+Tab, Alt+F4
→ browser_press_key { key: "Enter" } // submit form
→ browser_press_key { key: "Tab" } // move to next field
→ browser_press_key { key: "Escape" } // close modal
→ browser_press_key { key: "Control+a" } // select all text
→ browser_press_key { key: "ArrowDown" } // navigate dropdown
browser_type
在元素中输入文本。详情请参见 Forms。
🌐 Type text into an element. See Forms for details.
如果想一个键一个键地输入，而不是一次性填充整个值，可以使用 browser_type 和 slowly: true。
🌐 To type key by key rather than filling the whole value at once, use browser_type with
slowly: true.
鼠标（视觉模式）
🌐 Mouse (Vision mode)
当启用 视觉 功能（--caps=vision）时，这些工具可用。它们使用截图中的像素坐标，而不是快照中的元素引用。
🌐 These tools are available when the vision capability is enabled (--caps=vision). They use pixel coordinates from screenshots rather than element refs from snapshots.
browser_mouse_move_xy
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
x | 数字 | 是 | X 坐标 |
y | 数字 | 是 | Y 坐标 |
浏览器_鼠标按下 / 浏览器_鼠标抬起
🌐 browser_mouse_down / browser_mouse_up
在当前的位置按下或释放鼠标按钮。
🌐 Press or release a mouse button at the current position.
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
button | 字符串 | 否 | left（默认）、right 或 middle |
browser_mouse_wheel
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
deltaX | 数字 | 否 | 水平滚动，默认值为0 |
deltaY | 数字 | 否 | 垂直滚动，默认值为0（正数 = 向下） |
browser_mouse_click_xy
在特定坐标点击，无需先移动。
🌐 Click at specific coordinates without needing to move first.
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
x | 数字 | 是 | X 坐标 |
y | 数字 | 是 | Y 坐标 |
button | 字符串 | 否 | left（默认）、right 或 middle |
clickCount | 数字 | 否 | 点击次数，默认为 1 |
delay | 数字 | 否 | 鼠标按下和松开之间的时间（毫秒），默认 0 |
→ browser_mouse_click_xy { x: 150, y: 300 }
→ browser_mouse_click_xy { x: 150, y: 300, clickCount: 2 } // double-click
browser_mouse_drag_xy
用鼠标左键从一个位置拖到另一个位置。
🌐 Drag the left mouse button from one position to another.
| 参数 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
startX | 数字 | 是 | 起始 X 坐标 |
startY | 数字 | 是 | 起始 Y 坐标 |
endX | 数字 | 是 | 结束 X 坐标 |
endY | 数字 | 是 | 结束 Y 坐标 |
→ browser_mouse_drag_xy { startX: 100, startY: 200, endX: 400, endY: 200 }
将 boxes: true 传给 browser_snapshot（或者用 --snapshot-boxes 启动服务器）来获取快照中每个元素的 [box=x,y,width,height]。这样可以得到坐标而无需截图回传。
何时使用鼠标工具
🌐 When to use mouse tools
| 场景 | 使用 |
|---|---|
| 点击按钮、链接或表单元素 | 带 ref 的 browser_click（默认） |
| 基于画布的应用（绘图、地图） | 带视觉的鼠标工具 |
| 没有辅助功能的自定义 UI 控件 | 带视觉的鼠标工具 |
| 精确像素目标的拖拽操作 | 带视觉的鼠标工具 |
对于大多数 web 应用，来自可访问性快照的引用比坐标更可靠。仅在可访问性树未显示所需元素时使用鼠标工具。
🌐 For most web applications, refs from accessibility snapshots are more reliable than coordinates. Use mouse tools only when the accessibility tree doesn't expose the elements you need.