什么是 iframe？

Scrapeless Agent Browser 为在嵌入式网页文档中进行导航和交互的工作流提供托管浏览器会话。

iframe 是一种 HTML 元素，用于在一个网页中嵌入一个独立的文档。父页面包含 iframe 元素，而被嵌入的文档则拥有自己独立的 DOM、URL、脚本环境和加载活动。因此，iframe 创建的是文档边界，而不是简单地将普通子元素添加到父页面的 DOM 树中。

这种边界解释了许多开发和自动化中的意外情况。父文档可以显示一个组件，而该组件的内部控件在父文档的查询中却是不可见的。一个框架可能在其应用拥有可用数据之前就完成加载。安全规则可以允许嵌入的同时，又限制父文档可读取的内容。将框架视为一个独立的文档，会让这些行为更容易诊断。

iframe 嵌入的内容

一个 iframe 会在周围页面内，将文档嵌入到一个子可导航上下文中。 HTML iframe 定义 指定该元素与其嵌入内容的关系以及影响它的属性。

常见用例包括视频、地图、仪表板、支付界面以及其他独立交付的应用程序。父级控制元素的位置和可用空间。嵌入的文档控制其自身内容，并可在其环境约束内进行导航。

子文档不一定是静态的。它可以执行脚本、发起请求、更新其 DOM、打开允许的交互，并更改其 URL。一次性选择正确框架的任务仍然需要考虑之后的导航或 iframe 元素被替换的情况。

框架也会消耗资源。每个嵌入的文档都会带来脚本、布局工作和网络活动。只嵌入页面所需的内容，并评估完整的页面体验，而不是假设第三方内容对加载或响应性没有影响。

父元素与子文档是不同的

iframe 元素属于父文档，而它显示的内容属于另一个文档。这个区别决定了选择器和测量适用于哪里。

父级查询可以通过稳定的标识符、title、name 或其他相关属性找到 iframe 元素。它不会自动搜索嵌入文档的内部控件。要通过浏览器自动化与这些控件交互，先使用受支持的客户端 API 选择目标框架，然后在其中定位内容。

嵌套的框架会增加另一层级。一个组件可以嵌入其自身的子文档，因此所需的控件可能位于多个文档边界之下。检查框架之间的关系，并选择包含目标的文档，而不是反复扩大父级选择器。

不要依赖帧的顺序，除非这是你所控制的应用程序的显式属性。广告、分析或条件小组件都可能添加帧。仅仅因为在列表中排在第一位就被选中的帧，在页面更新后可能会悄然变成错误的那个。

同源策略控制脚本访问

同源策略会限制一个文档如何访问来自不同源的另一个文档。 同源安全边界 是基于文档的来源，而不仅仅是基于该框架是否出现在看起来可信的页面中。

嵌入和读取是不同的权限。父页面可以被允许显示远程文档，而不被允许通过普通页面 JavaScript 检查其内部 DOM。成功的可视化嵌入并不会建立不受限制的编程访问权限。

一个来源包括协议、主机和端口。相关的子域名仍然可能是不同的来源。不要因为共享公司名称或相似的 URL 拼写就推断具备访问权限。请检查实际的来源以及文档中记录的交互机制。

浏览器自动化工具可以暴露与普通父页面 JavaScript 不同的框架控制能力。仅使用受支持的工具接口和授权范围。工具对嵌入式应用程序进行操作的能力并不等同于获得收集受限信息或更改账户的权限。

沙盒和权限需要刻意配置

iframe sandbox 可以限制嵌入文档的功能。其他策略可以控制哪些浏览器特性可用。这些机制应根据子应用程序的实际需求进行配置。

从预期小组件所需的最低能力开始，然后测试其支持的交互。报表显示可能需要与视频会议界面不同的权限。为了修复某个缺失的行为而添加所有可用的许可，会模糊安全边界，并可能造成不必要的暴露。

沙盒选项的组合很重要。一些权限会影响脚本执行、表单、弹出窗口、导航或子级来源的处理。请查看每个选项的文档化效果，而不是假设属性名称就能完全表达其全部影响。

还要区分由父级设置的策略与由嵌入站点设置的限制。远程应用程序可以控制其他页面是否可以嵌入它。嵌入错误不一定是网络故障，更改父级选择器无法解决有意阻止显示的策略。

跨文档通信使用消息协定

当直接访问受到限制或不受欢迎时，跨文档通信应使用显式的消息契约。 window.postMessage 机制 在定义的源检查下支持窗口之间的通信。

安全的消息约定要标识预期的发送方和接收方、允许的消息类型以及可接受数据的结构。父页面在对接收到的消息采取行动前，应验证发送方的来源和消息内容。发送方应将消息发送到预期的来源，而不是向未指明的接收方广播敏感数据。

例如，嵌入的报表可能会通知其父页面某个选定筛选器已更改。有效的约定是一条包含经批准筛选器值的小事件，而不是对每个内部对象的不受限制访问。将消息限制在集成所需的信息范围内。

不要仅因为消息来自某个 frame 就把接收到的消息当作来自可信操作员的指令。应用程序必须决定哪些消息是有效的，以及它们可以触发哪些操作。这个边界对普通 Web 代码和解释页面内容的代理工作流同样重要。

加载 iframe 不等于加载其中的数据

iframe 的导航与其应用程序的就绪是两个独立事件。子文档可以成功加载，而其记录、控件或媒体仍不可用。

在目标子文档内部选择一个就绪条件。对于仪表板，检查完成的图表或结果区域。对于表单，检查必需的控件和状态。对于公开文章，检查承载内容的部分，而不是仅仅检查 iframe 元素本身是否存在。

区分空结果与未完成的应用程序。显示登录提示的子文档不同于显示“无匹配记录”的已授权仪表板。空白 frame 也不同于已完成的空状态。在任务状态中保留这些区别。

如果 frame 发生导航，或父页面替换了其 iframe 元素，则在继续之前重新评估当前文档。旧的元素或 frame 引用可能不再代表屏幕上的内容。基于稳定且与任务相关的证据重新获取目标上下文。

布局和可访问性属于集成的一部分

iframe 集成在父文档和子文档中都包含布局和可访问性责任。父页面必须分配足够空间并提供有意义的 frame 标题，而子页面必须在该空间内保持可用。

宽的浏览器窗口并不保证嵌入的应用同样宽。iframe 自身的尺寸决定了其可用布局区域。狭窄的面板会导致子页面即使在周围页面空间充足时，也采用紧凑界面。

测试滚动和焦点切换。用户可能需要进入 frame、与其控件交互，然后返回父页面。嵌套的滚动区域和被裁剪的按钮会让看似成功的嵌入变得难以使用。检查真实任务，而不仅仅是远程内容是否出现。

标题应标识嵌入内容的用途，例如运费估算器或培训视频。诸如“frame”这样的通用标题帮助不大。如果 iframe 被复用于不同内容，请保持标签准确。

嵌入内容诊断清单

有用的 iframe 诊断应先沿着文档边界排查，再改变抽取逻辑。每个问题都缩小一种不同的失败类别。

仅在有助于解释结果时才保留截图，并避免收集不相关的嵌入内容。支付或账户小组件即使在周围页面为公开内容时也可能暴露敏感信息。抽取范围应遵循已授权的任务。

Scrapeless Agent Browser 中的 iframe 工作流

Scrapeless Agent Browser 提供受管的浏览器环境，而自动化客户端负责选择并与各个 frame 交互。 Agent Browser Puppeteer connection 描述的是受支持的客户端接口；它不会消除文档边界或同源规则。

“ Agent Browser platform ”可以支持动态浏览器工作流，而相关的 iframe extraction with Playwright and Scrapeless 讨论则展开了 frame 选择问题。实现该连接时请使用最新文档，并根据涉及的浏览器工作负载评估 Scrapeless pricing 。

本术语表并不声称执行过实时 iframe 抽取。其设计示例说明实现应验证的内容：正确的子文档、有意义的就绪条件，以及在许可范围内的完整输出。

结论

iframe 嵌入的是具有自己身份、状态与加载行为的独立文档。通过找到正确的 frame、检查其策略、等待其有用的应用状态并验证结果来诊断嵌入内容。这些步骤解释了成功嵌入与成功抽取为何是不同的结果。