astron-rpa 浏览器插件实战指南:深度搜索、shadowRoot 递归定位与跨域 iframe 元素统一处理

原创2026-10-12 14:09:522,294 阅读
文章标签:工作流自动化低代码桌面应用AI Agent后端

astron-rpa 浏览器插件实战指南:深度搜索、shadowRoot 递归定位与跨域 iframe 元素统一处理

导读

本文聚焦 astron-rpa 仓库中 browser-plugin 浏览器插件包 的核心自动化能力:鼠标悬浮触发元素深度搜索、跨 shadow DOM 的递归元素获取,以及跨域/同源 iframe 嵌套场景下的元素坐标统一换算。读完本文,你将掌握该插件的打包定制方式(Chrome/Edge/Firefox 及任意 Chromium 内核变体浏览器)、三类元素定位能力的实现原理,以及 crx/xpi 离线包的构建与白名单安装流程,并能在 robot-service 等上层自动化组件中正确理解 iframeXpath、$shadow$ 等定位字段的含义。

该插件包位于 frontend/packages/browser-plugin,是 astron-rpa 体系中负责"网页相关自动化"的浏览器端组件,与仓库内 openapi-service 的 websocket 服务 等模块协同,向 RPA 执行器提供统一的元素拾取与定位能力。

一、环境要求与打包命令

1.1 Node 版本要求

打包环境要求 Node.js v20+。项目使用 Vite 5 作为构建工具,相关的 devDependencies(vite、vitest、cross-env、archiver 等)可见于 package.json。

1.2 基础打包:Chrome/Edge 通用插件

在插件包根目录执行:

npm run build

该命令等价于依次执行两条构建(见 package.json 的 scripts):

"build": "cross-env BUILD_ENTRY=background vite build && cross-env BUILD_ENTRY=content vite build"

即分别打包后台脚本(src/background.ts)与内容脚本(src/content.ts),产物位于 dist/ 目录。构建完成后,vite.config.ts 中的 extension-plugin 插件还会自动将 dist/ 目录压缩为 rpa-extension-v3-<版本号>-<mode>.zip 归档,方便直接上传分发。

1.3 定制浏览器打包:build:browser

npm run build:browser 用于打包为指定浏览器的插件,这里的 browser 指目标浏览器可执行文件的文件名。官方脚本预置了两个变体:

npm run build:firefox    # Firefox 专用包(manifest_version 2)
npm run build:chromium   # Chromium 专用包
npm run build:all        # 一次性执行 Chrome/Edge、Firefox、Chromium 三套构建

针对任意 Chromium/Firefox 内核的变体浏览器(如 360 安全浏览器、360ChromeX、Chromium 等),需要两步定制:

  1. 修改 src/3rd/rpa_websocket.js 中的 custom_agent 函数。该函数通过读取构建期注入的 __BUILD_MODE__ 宏返回浏览器标识,内置映射关系为:
function custom_agent() {
  const modeAgent = {
    '360se': "$360se$",
    '360ChromeX': "$360ChromeX$",
    'chromium': "$chromium$"
  }
  return modeAgent[__BUILD_MODE__] || '';
}
  1. 在 package.json 中新增对应命令,例如参照 build:firefox 增加 "build:360se": "cross-env BUILD_ENTRY=background vite build --mode=360se && cross-env BUILD_ENTRY=content vite build --mode=360se"。vite.config.ts 会通过 loadEnv(env.mode, ...) 读取对应 mode,并在 manifest.ts 中生成带该 mode 后缀的 manifest.json。

二、插件深度搜索功能(Deep Search)

2.1 触发条件与设计意图

深度搜索需要鼠标悬浮目标元素 5 秒以上才会触发。该常量的定义见 content/constant.ts:

export const DEEP_SEARCH_TRIGGER = 5 * 1000   // 5000ms,深度搜索触发延迟
export const ELEMENT_SEARCH_TRIGGER = 200     // 200ms,浅层搜索触发延迟

深度搜索的设计目的是解决一部分元素被遮挡的问题。例如目标按钮被悬浮提示、遮罩层或弹层覆盖时,普通的 elementFromPoint 只能命中最上层的遮挡元素;深度搜索会在 5 秒后自动切换为按"距鼠标坐标最近"的规则重新取元素。

但同时必须注意:并非所有元素都需要深度搜索。文档明确提示,有些未被遮挡的元素在深度搜索后反而会命中用户并不想要的元素(例如紧邻的大面积容器元素),因此插件采用"先浅层、再深度"的两段式触发策略。

2.2 实现方式:elementsFromPoint + 最近距离

在 content/element.ts 中,核心逻辑分为两步:

第一步:取鼠标点下的全部元素。 使用 document.elementsFromPoint(x, y) 获取鼠标 x、y 坐标下所有层叠的元素(而非只取最顶层):

export function getElementsByPosition(x: number, y: number) {
  const elements = document.elementsFromPoint(x, y)
  const positions = elements.map((element) => {
    const rect = element.getBoundingClientRect()
    return { element, ...rect.toJSON() }
  })
  return positions
}

第二步:计算距离,取最近元素。 对每个元素的 left、top、right、bottom 四个边界到目标坐标 (x, y) 的欧氏距离求和,取距离最小的元素;若存在多个并列结果,取第一项。对应实现为 getClosestElementByPoint:

export function getClosestElementByPoint(target: Point) {
  const ele = elementFromPoint(target.x, target.y, document)
  const eles = document.elementsFromPoint ? getElementsByPosition(target.x, target.y) : getAllElementsPositionInBody()
  if (!eles.length) return ele
  const pointEles = eles.filter((item) => {
    return item.left <= target.x && item.top <= target.y && item.right >= target.x && item.bottom >= target.y
  })
  if (!pointEles.length) return ele
  const closestElement = pointEles.reduce((prev, curr) => {
    const prevDistance = Math.hypot(prev.left - target.x, prev.top - target.y, prev.right - target.x, prev.bottom - target.y)
    const currDistance = Math.hypot(curr.left - target.x, curr.top - target.y, curr.right - target.x, curr.bottom - target.y)
    return prevDistance <= currDistance ? prev : curr
  })
  return closestElement.element
}

可见其筛选条件是"元素矩形必须包含该点",再在其中比较"四角到点的距离"之和;Math.hypot 用于计算直角三角形斜边长度。此外,element.ts 还提供了 getAllElementsPositionInBody 作为不支持 elementsFromPoint 环境下的回退方案,它递归遍历 document.body 下的所有可见元素(过滤掉 head、title、meta、script、style、link 等非可视化标签,以及 display:none、visibility:hidden、宽高为 0 的元素),并顺带递归收集 shadowRoot 内元素的位置。

两段式触发的编排逻辑位于 content/contentInject.ts 的 moveListener:鼠标移动先清空旧定时器,200ms 后执行浅层搜索,随后再设 5 秒定时器切换 deepSearchEnabled 执行一次深度搜索,执行完立即复位标志位。而 content.ts 在注册 mousemove 监听时还会过滤 event.isTrusted === false 的合成事件(防止客户页面代码转发事件造成误触发)以及非当前窗口事件。

三、shadowRoot 递归获取元素功能

3.1 递归过程与路径拼接

现代 Web 组件大量使用 Shadow DOM(如自定义元素 custom-element 内部的 button),普通 querySelectorAll 无法穿透 shadow 边界。插件的 shadowRootElement 函数(定义于 content/element.ts)递归处理该问题:

export function shadowRootElement(point: Point, shadowRoot: ShadowRoot, shadowPath: string = '', shadowDirs: ElementDirectory[] = []) {
  const { x, y } = point
  const ele = shadowRoot.elementFromPoint(x, y) as HTMLElement
  if (ele && ele.shadowRoot) {
    const shadowNth = `:nth-child(${getNodeNthIndex(ele)})`
    shadowPath = shadowPath ? `${shadowPath}>$shadow$>${getNthCssSelector(ele)}${shadowNth}` : `${getNthCssSelector(ele)}${shadowNth}`
    shadowDirs = shadowDirs.concat(getElementDirectory(ele))
    return shadowRootElement(point, ele.shadowRoot, shadowPath, shadowDirs)
  }
  else {
    return { element: ele, path: shadowPath, dirs: shadowDirs }
  }
}

其行为如下:

  • 在当前 ShadowRoot 内用 elementFromPoint 命中元素;
  • 若该元素自身又带有 shadowRoot(多层嵌套 shadow DOM),则用 $shadow$ 作为分隔符拼接 CSS 选择器路径,并递归进入下一层 shadowRoot,同时累积 ElementDirectory 目录信息;
  • 直到命中普通元素为止。

最终得到类似 custom-element:nth-child(1)>$shadow$>button:nth-child(2) 的路径,$shadow$ 标记了 shadow 边界,方便用户识别元素路径结构。

3.2 通过路径反查元素:getElementBySelector

通过 path 获取元素时,插件同样识别 $shadow$ 分隔符。content/element.ts 的 getElementBySelector 首先判断选择器是否包含 $shadow$:

export function getElementBySelector(selector: string, onlyPosition: boolean = false): HTMLElement[] | null {
  if (!selector) return null
  if (onlyPosition) {
    selector = onlyPositionSelector(selector)
  }
  if (selector.includes('$shadow$')) {
    const sahdowElements = getShadowElementsBySelector(selector)
    return sahdowElements.length > 0 ? sahdowElements : null
  }
  else {
    const elements = Array.from(document.querySelectorAll(selector)) as HTMLElement[]
    return elements.length > 0 ? elements : null
  }
}

包含 $shadow$ 时进入 getShadowElementsBySelector:先用 selector.split('>$shadow$>') 按 shadow 边界把路径切成"层级选择器数组",再交给 queryDeepShadow 递归查询——每一层在当前 host(Document 或 ShadowRoot)内执行 querySelectorAll,若命中元素带 shadowRoot 则以其作为下一层的 host 继续递归,从而从主文档逐层穿透到最深处的目标元素(见 element.ts 的 queryDeepShadow)。

3.3 限制说明

shadowRoot 元素目前只支持 CSS 选择器获取,不支持 XPath 选择器获取。 这是文档明确标注的边界,设计上沿用 $shadow$ 分隔符的 CSS 路径体系;若 RPA 流程中需要定位 shadow DOM 内元素,应使用 cssSelector 字段而非 xpath 字段。

四、frame 定位功能:跨域/同源 iframe 元素位置统一处理

4.1 问题背景:为什么不能用 src 查找 iframe

在跨域 iframe 场景中,由于浏览器同源策略限制,主文档脚本无法直接读取 iframe 内部 DOM。同时存在两个使问题复杂化的因素:

  • iframe 的 src 固定,但其实际加载的 url 是会变动的(如带 token 参数);
  • 同一个 tab 下可能存在 src 完全相同的多个 iframe。

因此通过 src 查找目标 iframe 是不准确的。插件改用"主进程维护 frame 嵌套关系 + 坐标逐层换算"的方案。

4.2 跨域 iframe:基于 parentFrameId 的嵌套关系定位

解决方案的核心思路(实现位于 background/iframe.ts):

  1. 插件主进程(background)通过 chrome.webNavigation / tabs.getAllFrames 获取 tab 内所有 frame 的嵌套关系,即每个 frame 的 parentFrameId,得到一条从顶层 frame(frameId === 0)到目标 frame 的嵌套顺序链;
  2. 传入目标元素的 x、y 坐标后,沿着嵌套关系顺序逐层查找;
  3. 坐标逐层减掉 iframe 的位置及其盒模型(borderLeft、paddingLeft 等),从而得到目标元素在 iframe content 中的准确坐标。

对应的两段实现分别位于 background 与 content 两侧,函数名均为 getIframeElement:

background 侧(编排层)——getIframeElement(p, activeElement) 从 activeElement.frameId 出发,循环 frames.find(frame => frame.frameId === targetFrame.parentFrameId) 构造完整 frame 路径,再通过 processFrames 在每个 frame 上执行 getIframeElement 消息,并持续用返回的 nextPos 更新坐标;最终把各层 iframe 的 iframeContentRect 累加到元素矩形上,并拼装出 iframeXpath(见 background/iframe.ts):

iXpath = `${iXpath}/$iframe$${frameInfo.xpath}`   // 每层用 /$iframe$/ 分隔

content 侧(坐标换算层)——contentInject.ts 中的 getIframeElement 做了精确的 DPR 与盒模型换算:

getIframeElement(data: Point) {
  const { x, y } = data
  const dpr = window.devicePixelRatio
  const realX = x / dpr
  const realY = y / dpr
  const iframeEle = document.elementFromPoint(realX, realY) as HTMLElement
  if (iframeEle) {
    const { left, top } = iframeEle.getBoundingClientRect()
    const borderLeft = Number.parseInt(window.getComputedStyle(iframeEle).borderLeftWidth)
    const borderTop = Number.parseInt(window.getComputedStyle(iframeEle).borderTopWidth)
    const paddingLeft = Number.parseInt(window.getComputedStyle(iframeEle).paddingLeft)
    const paddingTop = Number.parseInt(window.getComputedStyle(iframeEle).paddingTop)
    const nextPos = {
      x: (realX - left - borderLeft - paddingLeft) * dpr,
      y: (realY - top - borderTop - paddingTop) * dpr,
    }
    ...
  }
}

即:物理像素坐标先除以 devicePixelRatio 还原为 CSS 逻辑像素,命中 iframe 元素后再依次减去其 left/top、borderLeft/borderTop、paddingLeft/paddingTop,得到 iframe content 内部坐标,最后再乘回 DPR。getFrameContentRect(element.ts)则基于 getPadding、getBorder 计算 iframe 的 content 区域矩形,用于 background 侧累加绝对位置。

4.3 同源 iframe:复用同一套方法

文档明确指出:同源 iframe 虽然限制更小,但按同一套方法处理,可以避免冗余、减少变量、减少出错。因此同源与跨域共用 getIframeElement 的整套坐标换算链路,不单独开发分支。

4.4 iframe 元素定位处理:postMessage 绑定 iframeXpath

跨域场景下主文档无法直接操作 iframe 内部 DOM,插件采用 postMessage 消息绑定方案,实现位于 content/iframe.ts:

  1. 标记 frame 元素:content 脚本会标记当前窗口下的所有 frame 元素(tagFrames → getIFramesElements);
  2. 下发 xpath:父窗口通过 frameDom.contentWindow.postMessage({ key: 'setCurrentWindowIframeInfo', data: { iframeXpath: directoryXpath(frameDom), ... } }, '*') 把该 iframe 的 xpath 路径传给对应的 iframe(postToIframe);
  3. iframe 侧接收:iframe 内通过 window.addEventListener('message', listenMessage) 接收 xpath 路径,写入 currentFrameInfo.iframeXpath(listenMessage 同时处理 getCurrentWindowIframeInfo 与 bindCurrentWindowIframeInfo 消息);
  4. 上报主进程:iframe 再通过 window.parent.postMessage 将绑定信息回传父窗口,tagFrameId 会把 frameId 写入对应 iframe 元素的 dataset.astronFrameId 属性;
  5. 得到全路径:由此将"iframe 的 xpath 路径"与"iframe 的 id"绑定起来,按 id 的嵌套关系即可拼出完整的 iframe path 全路径,通过 iframeXpath 字段即可定位到对应 iframe 及其内部目标元素。

background 侧在回查时,findFrameByXpath(background/iframe.ts)会把 iframeXpath 按 /$iframe$/ 分隔成段,从根 frame(frameId === 0)出发,逐段查找"父 frameId 匹配且 iframeXpath 匹配"的下级 frame;findFrameByUrl 则作为无 iframeXpath 时的兜底匹配。此外,background/iframe.ts 还提供了 buildFrameTree(构建 frame 树)、calculateAbsolutePosition(逐层累加 frame 偏移得到绝对坐标)、adjustPosition(把相对坐标转换为绝对坐标)等辅助能力,供上层元素拾取链路使用。

4.5 注意事项:iframeXpath 的动态性

文档明确提示:iframeXpath 与其他元素定位逻辑相同、统一查找逻辑,因此也存在动态性问题。即:当页面结构变化(iframe 增删、嵌套层级变化、同级 iframe 顺序变化)后,记录在元素信息中的 iframeXpath 可能失效,RPA 流程设计时需考虑重拾元素或结合路径目录(iframePathDirs)进行可视化重定位。ElementInfo 类型中 iframeXpath 字段的定义可参见 types/index.d.ts。

五、构建 crx/xpi 包说明

5.1 Chrome:商店发布与白名单安装

Chrome 可以选择构建 crx 插件包,官方推荐使用 Chrome Developer Dashboard 发布到 Chrome 插件商店——但 Chrome 开发者账户需要收费。若不发布到插件商店,Chrome 会限制启用非商店来源插件,需要在安装插件时写入 chrome://policy 政策 ExtensionInstallAllowlist:

  • Windows:以注册表方式写入 Software\Policies\Google\Chrome\ExtensionInstallAllowlist;
  • Linux:写入 /etc/opt/chrome/policies/managed/policy.json。

写入内容为允许安装的扩展 ID 列表(详见 Chrome 企业版政策文档的 ExtensionInstallAllowlist 页面,可在 chrome://policy 中验证生效情况)。

不发布的本地打包方式:

  1. 打开 Chrome,进入 chrome://extensions/ 页面;
  2. 启用开发者模式;
  3. 选择"打包扩展程序";
  4. 浏览到扩展程序根目录(即 dist/ 构建产物);
  5. 第一次打包时私钥文件可留空;
  6. 点击打包后,在扩展程序根目录会生成对应的 .crx 文件与 .pem 密钥文件。

.pem 文件务必妥善保存:后续更新插件包时必须使用同一个密钥文件——同一把密钥会生成相同的插件 id,用于无缝更新插件。

5.2 Firefox:免费开发者账户与 xpi 上传

  1. Firefox 可以免费自行申请一个开发者账户;
  2. 上传打包好的插件 xpi 文件;
  3. 可以不发布,直接下载自己的 xpi 文件安装使用。

文档同时说明:Firefox 插件需自行打包,使用自己的开发者账户上传,构建自己的 xpi 文件。仓库内预置了 npm run build:firefox 命令:构建时 manifest.ts 会把清单切换为 manifest_version 2(MV2,background 使用 scripts 数组而非 service_worker),并注入 browser_specific_settings.gecko.id(取自 VITE_FIREFOXID 环境变量)与 strict_min_version: '58.0',同时移除 MV2 不支持的 debugger 权限并补充 webRequest、webRequestBlocking 权限。

5.3 清单关键配置

无论 Chrome 还是 Firefox 变体,清单的生成逻辑都在 manifest.ts:版本号自动读取 package.json 的 version,content script 声明 all_frames: true(保证注入所有 iframe,这是上文 frame 定位能力的前提)、matches 覆盖 http/https/file/ftp 协议、run_at: 'document_start'、world: 'ISOLATED',后台则声明为 service worker(MV3)。需要的权限包括 tabs、activeTab、webNavigation、cookies、storage、scripting、nativeMessaging、debugger、management 等,完整清单以构建产出的 manifest.json 为准。

六、源码验证与测试支撑

上述能力并非仅停留在文档描述,仓库内提供了对应实现与测试:

  • 深度搜索与 shadowRoot 定位的核心算法:getClosestElementByPoint、shadowRootElement、getElementBySelector、queryDeepShadow 均位于 content/element.ts;
  • iframe 坐标换算与嵌套关系处理:background 侧 background/iframe.ts,content 侧 content/iframe.ts 与 contentInject.ts 的 frame 处理器;
  • 鼠标事件编排与深度搜索开关:moveListener / findElement 见 contentInject.ts,事件注册与合成事件过滤见 content.ts;
  • 后台进程入口与 WebSocket 桥接:见 background.ts;
  • 单元测试:getIframeTransform、getFrameContentRect 等函数有对应测试用例(如 content.element.test.js),background 与 content 的其余工具函数分别有 background.*.test.js、content.*.test.js 测试文件覆盖,运行 npm run test 或 npm run test:browser 可执行(配置见 vite.config.ts)。

结语

astron-rpa 的浏览器插件通过"5 秒悬浮触发深度搜索 + elementsFromPoint 最近距离算法 + $shadow$ 路径穿透 shadow DOM + parentFrameId 嵌套关系与 postMessage 绑定实现 iframe 坐标统一换算"这套组合,解决了网页自动化中元素被遮挡、Web Components 内部元素不可见、跨域 iframe 无法直接操作这三类最棘手的定位问题。配合 Node v20+ 环境下的 npm run build / build:browser 多目标打包能力,以及 crx/xpi 的离线构建与白名单安装流程,开发者可以快速将其集成到自己的 RPA 流水线中。需要特别留意的两个边界是:shadow DOM 元素仅支持 CSS 选择器;iframeXpath 与普通元素定位一样存在页面动态变化导致失效的可能。

登录后查看全文
astron-rpa