Astron RPA 浏览器插件开发指南:Deep Search 元素定位、shadow DOM 穿透与跨域 iframe 处理

原创2026-10-09 12:06:062,317 阅读
文章标签:工作流自动化桌面应用AI 应用企业应用后端前端

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):

  1. 鼠标移动 200ms 后先执行一次浅搜索(deepSearchEnabled = false);
  2. 浅搜索完成后,若鼠标未离开,再等 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 协作完成:

  1. background 侧 getIframeElement(p, activeElement)(iframe.ts):

    • 通过 Tabs.getAllFrames 取回全部 FrameDetails,从目标 frame 沿 parentFrameId 逐级上溯,unshift 出 framePath: number[];
    • 由 processFrames(L145)在每一级 frame 上通过 executeFuncOnFrame 执行 content 侧的 getIframeElement handler,并用返回的 nextPos 更新坐标;
    • 将各级 iframe 的 xpath 以 /$iframe$/ 拼接为 iframeXpath,同时累加 iframeContentRect 偏移修正最终 rect。
  2. 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 侧据此逐层累加还原绝对位置。
  3. background 侧的 findFrameByXpath(L252-L275)按 /$iframe$/ 分段、自 frameId=0 的根 frame 逐级匹配子帧;frameFind 与 locatorFrameId 则通过 content 侧 findIframeId handler 反查 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)

  1. 正式发布(推荐):使用 Chrome 开发者信息中心发布到 Chrome Web Store,需要付费开发者账号;未发布到商店的插件会被 Chrome 限制启用,必须通过 chrome://policy 策略将插件加入白名单:
    • Windows:注册表路径 Software\Policies\Google\Chrome\ExtensionInstallAllowlist;
    • Linux:写入 /etc/opt/chrome/policies/managed/policy.json。 (详见 ExtensionInstallAllowlist 企业策略说明。)
  2. 未发布打包:打开 chrome://extensions/ → 开启"开发者模式" → 选择"打包扩展程序" → 浏览到插件根目录。首次打包私钥文件可留空,打包后根目录会生成 .crx 文件与 .pem 密钥文件。.pem 必须妥善保存:后续更新使用同一密钥重新打包可得到相同的插件 ID,保证升级时插件身份一致。

Firefox(xpi)

  1. 可在 Firefox 申请免费开发者账号,上传打包好的 xpi 文件后无需发布即可直接安装;
  2. 需自行打包 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 变体浏览器。

登录后查看全文
astron-rpa