Astron RPA 浏览器插件开发指南:Deep Search 元素定位、shadow DOM 穿透与跨域 iframe 处理
Astron RPA 浏览器插件开发指南:Deep Search 元素定位、shadow DOM 穿透与跨域 iframe 处理
本文以 Astron RPA(Agent-ready RPA 套件)中的浏览器插件(Browser Plugin)为核心,系统讲解其针对 Web 自动化场景的三项关键技术:基于鼠标停留触发的 Deep Search 元素拾取、递归穿透 shadow DOM 的定位路径、以及基于 parentFrameId 嵌套关系的跨域/同源 iframe 元素定位;同时给出构建 Chrome/Edge 通用扩展与 Firefox 专属包的完整流程。读完本文,你将掌握如何从源码层面理解插件元素拾取机制的实现原理,并能独立完成自定义浏览器的扩展打包配置。
仓库定位与插件架构
Astron RPA 是一个面向个人与企业的 Agent-ready RPA 套件,浏览器插件是其 Web 自动化能力的执行载体。插件代码位于 frontend/packages/browser-plugin/,由以下几个核心部分组成:
src/background/:扩展后台(background)逻辑,负责标签页/框架管理、iframe 嵌套关系处理、Cookie、网络监控与截图等能力,核心文件包括backgroundInject.ts、iframe.ts、tab.ts;src/content/:注入到网页中的 content script,负责元素拾取、高亮、iframe 消息通信与元素变更监听,核心文件包括contentInject.ts、element.ts、iframe.ts、watcher.ts;src/3rd/:第三方/桥接脚本,如rpa_websocket.js(与 RPA 主程序通信的 WebSocket 桥),多浏览器定制就是在此配置custom_agent;manifest.ts:构建期动态生成 manifest.json(MV3 / MV2)的脚本;tests/:基于 Vitest + jsdom 的单元测试,如content.element.test.js、content.inject.test.js。
插件以 manifest_version: 3 为主(Firefox 构建时降级为 MV2),content script 通过 all_frames: true 注入所有帧,并声明 debugger、tabs、webNavigation、nativeMessaging 等权限,见 manifest.ts。
构建指令与多浏览器打包
package.json(版本 5.2.12)中定义了如下构建脚本(package.json):
npm run build # 构建 Chrome/Edge 通用扩展(background + content 两个入口)
npm run build:firefox # 构建 Firefox 专属扩展(MV2)
npm run build:chromium # 构建指定 Chromium 变体扩展
npm run build:all # 依次执行上述三种构建
build通过cross-env BUILD_ENTRY=background vite build与BUILD_ENTRY=content vite build分别产出background.js与content.js两个入口;build:firefox/build:chromium额外传入--mode=firefox/--mode=chromium,由 manifest.ts 据此动态生成不同规范的 manifest:Firefox 模式使用manifest_version: 2、browser_specific_settings.gecko(含VITE_FIREFOXID与最低版本58.0),并从权限列表中移除debugger;- Node 版本要求为 v20+。
为任意 Chromium/Firefox 变体定制打包
npm run build:browser 用于打包到指定浏览器。核心思路是:只需在 src/3rd/rpa_websocket.js 中设置 custom_agent,并在 package.json 中新增对应命令,其中 browser 指目标浏览器的可执行文件名。同时,构建期通过 VITE_APP_NAME、VITE_APP_HOMEPAGE、VITE_FIREFOXID 等环境变量注入应用名、主页与 Firefox 扩展 ID。
Deep Search:悬停 5 秒触发的深度元素拾取
设计动机
普通点击拾取只能拿到坐标点最顶层的一个元素。当某些元素被遮挡时(如弹层、浮层、透明覆盖物),用户实际想选中的元素会取不到。Deep Search 正是为解决"元素被覆盖"而设计:鼠标悬停超过 5 秒即触发深度搜索。
但要注意,对未被遮挡的元素而言,深度搜索可能选中用户并不想要的下层元素,因此并非所有元素都适合 Deep Search——这正是插件将深浅两次搜索分开触发的原因。
实现原理:elementsFromPoint + 距离计算
核心实现在 element.ts 中:
getElementsByPosition(x, y)(L653):调用document.elementsFromPoint(x, y)取得鼠标坐标 (x, y) 下所有元素及其getBoundingClientRect()矩形;getClosestElementByPoint(target)(L799):先取最顶层元素,再用elementsFromPoint枚举该点下的全部元素,过滤出矩形确实包含该点的候选集,最后计算每个元素 left/top/right/bottom 到目标点的欧氏距离(Math.hypot),取距离最近的元素;多个结果并列时取第一个。
触发时序:两次搜索的节流编排
在 contentInject.ts 的 moveListener 中(L92-L107):
- 鼠标移动 200ms 后先执行一次浅搜索(
deepSearchEnabled = false); - 浅搜索完成后,若鼠标未离开,再等
DEEP_SEARCH_TRIGGER(5 秒)后置deepSearchEnabled = true执行一次深搜索,随后立即复位标志。
两个阈值常量定义在 constant.ts:ELEMENT_SEARCH_TRIGGER = 200(浅搜索节流)、DEEP_SEARCH_TRIGGER = 5 * 1000(深搜索阈值);common 目录下另有副本常量(50ms)。findElement(L49-L77)在深搜开关开启时走 findElementByPoint({ x, y }, deepSearchEnabled, docu) 分支,从而选中被遮挡的下层元素,并最终通过 formatElementInfo 生成包含 xpath/selector 的元素信息下发。
shadow DOM 穿透:递归 shadowRoot 元素检索
现代 Web 应用大量使用 Shadow DOM 封装组件,其内部元素对普通 document.querySelectorAll 不可见。插件的解决方案是递归穿透:
-
shadowRootElement(point, shadowRoot, shadowPath, shadowDirs)(element.ts):- 在
shadowRoot.elementFromPoint(x, y)取得当前影子根内元素; - 若该元素自身又挂有
shadowRoot,则用getNthCssSelector(ele)与:nth-child(n)拼接路径段,以$shadow$作为分隔符累积shadowPath,并继续向下递归,直到找到普通元素; - 返回
{ element, path, dirs },其中path形如component-a>div等层级链,dirs记录每一层元素目录。
- 在
-
在
findElement(contentInject.ts)中,当拾取到的元素带shadowRoot时即调用shadowRootElement深入影子 DOM,并把shadowPath一并传给formatElementInfo。
按路径反查元素:仅支持 CSS 选择器
元素定位阶段,$shadow$ 同样被识别:getElementBySelector(element.ts)负责按路径(含 $shadow$ 分隔的 selector 链)找回目标元素。目前 shadow DOM 内的元素只支持 CSS 选择器定位,不支持 XPath 选择器,这是接入方需要特别留意的约束。此外 watcher.ts 中的元素变更监听也会复用 getElementBySelector 与 getElementsByXpath 来重定位已记录的元素。
iframe 元素定位:基于嵌套关系的统一处理
为什么不能只靠 src 定位 iframe
同源策略下,直接读取跨域 iframe 内部 DOM 是不允许的;同时 iframe 的 src 虽可固定但实际 URL 可能变化,同一标签页内也可能存在 src 完全相同的多个 iframe。因此仅凭 src 找 iframe 是不准确的。
方案总览:parentFrameId 嵌套顺序 + 逐层坐标换算
插件的核心思路:从插件主进程取得 iframe 的嵌套关系(parentFrameId),得到嵌套顺序;随后把 (x, y) 坐标与嵌套顺序一起逐层下传,每进一层都按该层 iframe 的位置与盒模型(borderLeft、paddingLeft 等)逐层缩减坐标,从而得到在 iframe 内容区的精确位置。 跨域与同源 iframe 采用完全相同的处理路径——同源虽然限制更松,但统一处理可以避免逻辑重复、减少变量与误差。
该能力由 backgroundInject.ts 的 getIframeElement 与 content 侧的 getIframeElement handler 协作完成:
-
background 侧
getIframeElement(p, activeElement)(iframe.ts):- 通过
Tabs.getAllFrames取回全部 FrameDetails,从目标 frame 沿parentFrameId逐级上溯,unshift 出framePath: number[]; - 由
processFrames(L145)在每一级 frame 上通过executeFuncOnFrame执行 content 侧的getIframeElementhandler,并用返回的nextPos更新坐标; - 将各级 iframe 的 xpath 以
/$iframe$/拼接为iframeXpath,同时累加iframeContentRect偏移修正最终 rect。
- 通过
-
content 侧
getIframeElement(data: Point)(contentInject.ts):- 先按
window.devicePixelRatio做 CSS 像素与物理像素换算(realX = x / dpr); document.elementFromPoint(realX, realY)命中 iframe 元素后,取getBoundingClientRect()的 left/top,再读取borderLeftWidth、borderTopWidth、paddingLeft、paddingTop,按公式x - left - borderLeft - paddingLeft计算下一层坐标系;- 返回
nextPos(下一帧内的坐标)与iframeContentRect(iframe 内容区在父级中的偏移),background 侧据此逐层累加还原绝对位置。
- 先按
-
background 侧的
findFrameByXpath(L252-L275)按/$iframe$/分段、自 frameId=0 的根 frame 逐级匹配子帧;frameFind与locatorFrameId则通过 content 侧findIframeIdhandler 反查 iframe 元素的dataset.astronFrameId;兜底时elementLocatorFrameId(L118-L129)向所有 frame 广播elementLocatorFrameId消息,找出元素真正所在 frame。
iframe 元素定位(iframeXpath 绑定机制)
在 content 侧 iframe.ts 中:
tagFrames()遍历当前窗口内所有 frame 元素(iframe/frame),通过iframe.contentWindow.postMessage({ key: 'setCurrentWindowIframeInfo', data: { iframeXpath, ... } })把该 iframe 的 XPath 发送给对应 iframe;- iframe 内通过
window.addEventListener('message', e => {...})(listenMessage,L65-L78)接收setCurrentWindowIframeInfo并写入currentFrameInfo.iframeXpath,随后requestFrameId从主进程取 frameId,并回传bindCurrentWindowIframeInfo把 XPath 与 id 绑定; - 父级收到
bindCurrentWindowIframeInfo后,tagFrameId将data-astron-frame-id属性写入对应 iframe DOM,形成"iframe XPath ↔ frameId"映射。于是可按 id 嵌套关系得到完整 iframe 路径,并通过iframeXpath字段在对应 iframe 内定位目标元素。
注意事项:iframeXpath 的定位逻辑与普通元素一致,同样面临页面动态变化导致的失效问题(元素变更监听 watcher.ts 负责处理此类动态场景)。
构建 crx / xpi 安装包
Chrome(crx)
- 正式发布(推荐):使用 Chrome 开发者信息中心发布到 Chrome Web Store,需要付费开发者账号;未发布到商店的插件会被 Chrome 限制启用,必须通过
chrome://policy策略将插件加入白名单:- Windows:注册表路径
Software\Policies\Google\Chrome\ExtensionInstallAllowlist; - Linux:写入
/etc/opt/chrome/policies/managed/policy.json。 (详见ExtensionInstallAllowlist企业策略说明。)
- Windows:注册表路径
- 未发布打包:打开
chrome://extensions/→ 开启"开发者模式" → 选择"打包扩展程序" → 浏览到插件根目录。首次打包私钥文件可留空,打包后根目录会生成.crx文件与.pem密钥文件。.pem必须妥善保存:后续更新使用同一密钥重新打包可得到相同的插件 ID,保证升级时插件身份一致。
Firefox(xpi)
- 可在 Firefox 申请免费开发者账号,上传打包好的 xpi 文件后无需发布即可直接安装;
- 需自行打包 Firefox 扩展、使用自己的开发者账号上传并构建自己的 XPI 文件(对应仓库中的
npm run build:firefox,产出 MV2 规范的 xpi 包)。
测试与验证
仓库提供了与上述机制对应的测试与调试工具:
- 单元测试位于 tests/ 与 src/test/,覆盖元素拾取、注入逻辑、tab/工具函数等,运行方式为
npm test(Vitest),浏览器级测试用npm run test:browser(基于vitest.browser.config.js); tests/iframe-diagnostic-tool.html是 iframe 定位诊断页面,可直接在浏览器中打开用于验证跨域/同源 iframe 拾取链路。
小结
Astron RPA 浏览器插件通过"悬停 5 秒触发深搜(elementsFromPoint + 距离度量)"解决遮挡元素拾取,通过"$shadow$ 分隔符递归穿透 shadow DOM + CSS selector 反查"解决组件内部元素定位,通过"parentFrameId 嵌套顺序 + 逐层盒模型坐标换算 + postMessage 绑定 iframeXpath↔frameId"实现跨域/同源 iframe 内元素的可靠定位,三者共同构成了 RPA 在浏览器端拾取元素的核心能力。在此基础上,npm run build 与 npm run build:firefox 分别产出 Chrome/Edge 通用扩展与 Firefox 专属包,结合 custom_agent 配置即可适配任意 Chromium/Firefox 变体浏览器。