PinchTab Hover 指南：按选择器或 ref 移动指针，触发菜单与 Tooltip

【免费下载链接】pinchtabHigh-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.项目地址https://gitcode.com/gh_mirrors/pi/pinchtab点击查看免费下载PinchTab 是一个高性能浏览器自动化桥接与多实例编排工具其核心能力之一是向页面元素派发可信的鼠标事件。本文聚焦其中的hover动作如何通过 HTTP/action接口或pinchtabCLI 将指针移动到指定元素或坐标上从而触发那些只有悬停才会出现的菜单、Tooltip 与浮层。读完本文你将掌握 hover 的全部目标定位方式ref / 统一选择器 / 坐标、CLI 标志位用法、iframe 下的 frame 作用域约束以及 hover 在底层是如何经由 CDP 与 JS 兜底路径被执行的。快速上手一个请求触发悬停hover的语义非常明确将指针移动到某个元素上方。它接受两种目标形式——selectorCSS 选择器或ref来自/snapshot的引用编号。以 ref 为例直接 POST 到动作端点即可curl -X POST http://localhost:9867/action \ -H Content-Type: application/json \ -d {kind:hover,ref:e5}CLI 提供了完全等价且更简洁的写法# CLI Alternative pinchtab hover e5默认情况下 CLI 输出简短的OK需要完整结构化响应时加上--json服务端会返回形如{hovered: true}的 JSON 结果走 humanized 路径时额外携带human: true字段。请求体与命令签名都支持--tab指定目标标签页——CLI 在携带--tab时会把请求路径从/action切换为/tabs/{id}/action见 actions_element.go。典型使用场景当页面的菜单项、Tooltip、下拉浮层只在指针悬停后才渲染或可见时先 hover 再配合click或snapshot完成后续操作。三种目标定位方式ref、统一选择器与坐标hover的目标解析遵循与 click 相同的三选一规则底层由 actionHover 依次判断ref直接给出快照编号例如{kind:hover,ref:e5}服务端将其作为 BackendNodeId 直接派发selector先通过firstNodeBySelector解析出元素再取其 BackendNodeId 派发坐标x/y跳过元素解析直接HoverByCoordinate在视口坐标处移动指针。三者都没有提供时动作会返回NewInvalidActionRequestError(need selector, ref, nodeId, or x/y coordinates)。CLI 端同样强制这一约束如果既没有位置参数、也没有--css或--x/--y会直接输出用法提示并终止见 actions_element.go。统一选择器语法CLI 与 HTTP 请求都接受统一选择器形式由 selector.go 统一解析支持五种前缀语法与裸 CSS 自动识别形式示例解析结果refe5{ref:e5}CSS裸写#menu{selector:#menu}XPathxpath://button{selector:xpath://button}文本text:Menu{selector:text:Menu}语义查询find:account menu{selector:find:account menu}CLI 端会先把输入交给selector.Parseref 类型写入请求体的ref字段裸 CSS 写入selector字段其余带前缀的形式原样透传由服务端二次解析见 setSelectorBody。CLI Flags 全解pinchtab hover支持以下标志位与 HTTP 请求体字段一一对应Flag作用对应请求体字段--css selector用 CSS 选择器代替 ref 定位目标selector--x n,--y n在指定视口坐标处悬停两者必须同时给定才启用坐标模式x,y--humanize走 humanized 贝塞尔曲线 抖动输入路径覆盖实例级配置humanize--json输出完整 JSON 响应而非OK—--tab id指定目标标签页切换为/tabs/{id}/action路径--humanize的优先级与 API 完全一致即单次请求显式覆盖 实例配置 内建默认false这一规则由 effectiveHumanize 实现只有当请求中显式携带humanize字段时才写请求体未提供则保留 nil交由服务端按优先级链解析。CLI 端仅在该标志被显式传入时才写入请求体见 actions_element.go。底层执行路径CDP 可信派发与 DOM 兜底hover在服务端并不只是一个移动坐标的简单调用它包含两条执行路径目标是兼顾可信度与健壮性。标准路径Input.dispatchMouseEvent非 humanized 的 hover 最终落在 cdpops/pointer.go 中HoverByCoordinate(ctx, x, y)等价于MouseMoveByCoordinate通过Input.dispatchMouseEvent的mouseMoved类型派发真实鼠标移动HoverByNodeID(ctx, nodeID)先用PointerPointForNode解析元素盒模型中心点再派发移动到该坐标。这里有一个关键工程细节Headless Chromium 可能将合成的mouseMoved派发挂起约 5 秒等待 renderer/compositor 的 ACK。为避免 hover/移动测试与自动化任务被拖慢代码将真实 CDP 移动的等待上限定为mouseMoveDispatchTimeout 50ms见 pointer.go超时后自动降级为 DOM 合成事件兜底。兜底路径DOM 合成 mouseover / mouseenter / mousemove兜底逻辑由dispatchMouseMove/dispatchMouseMoveToNode负责仅当真实 CDP 移动超时且父上下文未被取消时触发。坐标版dispatchSyntheticMouseMove用document.elementFromPoint找到目标元素然后依次派发mouseover、mouseenter非冒泡、mousemove三个合成事件元素版dispatchSyntheticMouseMoveOnNode则先DOM.resolveNode拿到对象 ID再在节点上下文内以盒模型中心坐标派发同样的事件序列——这样即使 CDP 输入通道不可用依赖 hover 的 CSS 状态切换仍能生效。Humanized 路径贝塞尔轨迹 随机抖动当启用--humanize时actionHumanizedHover会把普通 hover 替换为 input_human.go 中的人性化版本目标点随机化humanPointerPoint先scrollIntoViewIfNeeded把元素滚入可视区域取盒模型中心后叠加±5px的随机偏移避免每次悬停都精确命中同一个像素贝塞尔逼近Hover先通过approachTargetAction以随机起点、贝塞尔插值的轨迹逐步逼近目标每步有超时保护卡住时snap到终点随后调用settleHoverAction即HoverByCoordinate完成最终的 hover 派发响应中会额外携带human: true标记便于调用方区分两条路径。这一设计保证了在需要反自动化检测或行为自然度的场景下hover 的轨迹、落点与时间分布都与真实用户操作更为接近。iframe 场景frame 作用域先行选择器查找默认被限制在**当前 frame 作用域默认main**内。也就是说如果目标菜单位于 iframe 中直接hover #menu可能找不到元素——必须先通过/frame把作用域切到目标 iframepinchtab frame #payment-frame # 切到 iframe pinchtab hover text:Open menu # 在 iframe 内悬停 pinchtab frame main # 用完切回主文档几点边界需要注意详见 frame.mdref 不受 frame 限制/snapshot中来自同源 iframe 后代的 ref 可以直接用于 hover无需切换 frame跨源 iframe 不暴露为 frame 作用域选择器无法穿透跨源 iframe只能依赖同源快照 ref嵌套 iframe 通常需要多次frame跳转同一 frame 作用域同时作用于选择器版/snapshot与/action调用也作用于未显式传frameId的/text。相关能力与延伸阅读hover 是 PinchTab 指针动作家族的一员常与以下能力搭配使用Clickhover 触发浮层后的点击动作同样支持 ref / selector / 坐标与 humanized 路径Frameiframe 内的选择器作用域管理hover 前的前置步骤Snapshot获取 ref 编号的来源也是 iframe 后代元素跨作用域引用的通道。如需深入了解 humanized 输入路径的实现细节可继续阅读 input_human.go 与 cdpops/pointer.go动作注册表与动作名常量位于 action_registry.goActionHover hoverCLI 命令定义见 cmd_cli_browser_actions.go。赞分享【免费下载链接】pinchtabHigh-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.项目地址https://gitcode.com/gh_mirrors/pi/pinchtab点击查看免费下载相关推荐PinchTab Focus 指南用选择器或 Ref 精确移动焦点为键盘流自动化铺路PinchTab Focus 指南用选择器或 Ref 精确移动焦点为键盘流自动化铺路 导读 本文讲解 PinchTab 浏览器自动化桥接器的 focus 动ChartDB选择器单选多选下拉菜单ChartDB选择器单选多选下拉菜单 概述 在数据库图表设计工具ChartDB中选择器组件是用户交互的核心元素。ChartDB提供了三种强大的选择器组件数据库前端数据可视化AI 应用掌握 DatePickerCellTriggerReka UI 日期选择器单元格触发器完全指南掌握 DatePickerCellTriggerReka UI 日期选择器单元格触发器完全指南 DatePickerCellTrigger 是 Reka UI前端UI组件设计系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考