什么是视口？

Scrapeless Agent Browser 提供受管理的浏览器环境，其视口和显示配置会影响页面布局和捕获的输出。

视口是浏览器呈现文档的区域。在 Web 开发中，该术语可以用来描述用于布局页面的空间，或当前可见的那部分布局。这两个区域在桌面浏览器上通常看起来很相似，但在移动端缩放和其他显示变化时可能会有所不同。

视口不同于物理屏幕、完整浏览器窗口、文档的全部尺寸以及所有可能截图的尺寸。区分这些测量有助于解释为何响应式页面会改变其导航方式、为何缩放会隐藏布局的一部分，以及为何整页截图的高度可能远远超过浏览器中可见区域。

布局视口定义页面的工作空间

布局视口为页面内容的排版提供了一个参考空间。响应式规则和文档几何形状依赖于该环境，因此更改视口尺寸可能会改变界面本身。

The CSSOM 视图几何模型 定义了 web 应用程序使用的浏览器和文档测量概念。仅仅因为其中有几个测量包含单词 width 或 height，它们就可以互换使用是错误的。

考虑这样一个站点：当有足够的水平空间时，会显示一排导航链接。在较窄的布局中，它可能会用一个菜单按钮来替换这些链接。即使应用程序工作正常，为宽屏布局编写的自动化定位器在窄屏布局中也可能会失败。

内容可以超出视口范围。一篇长文章所占用的文档垂直空间会超过浏览器当前显示的区域。滚动只会改变可见的部分；它不会将整个文档高度变成视口高度。水平溢出也需要类似的关注，因为被隐藏的内容可能意味着需要有意滚动，也可能表明存在布局问题。

可视视口描述可见区域

可视视口描述的是当前对用户可见的那部分布局。当移动端的双指缩放改变页面在屏幕上可容纳的内容范围时，这一区别尤为重要。

该 布局和视觉视口概念 解释为什么对页面进行缩放并不意味着整个页面是按更窄的设备重新布局的。用户只是查看了现有布局中的较小一部分。

屏幕键盘和浏览器界面更改也会影响可见区域，其行为取决于环境和配置。固定控件可以存在于文档中，但在当前交互状态下仍可能被遮挡。针对关键状态进行测试，尤其是在用户必须在小屏幕上完成表单时。

出于诊断目的，记录你所使用的测量类型。一份只说“高度发生了变化”的报告，会让人无法判断变化的是布局、可见区域、屏幕几何结构，还是文档内容。给测量命名可以让视觉问题具备可重现性。

CSS 像素不一定是设备像素

CSS 像素是用于网页布局的单位，而设备像素描述的是栅格显示器或输出表面。它们之间的关系取决于环境的缩放设置和捕获行为。

该 CSS 长度和视口单位 定义样式表中可用的单位。CSS 尺寸不应在任何环境下都被解释为物理显示像素的有保证数量。

这种差异对截图来说很重要。图像的栅格尺寸除了反映请求的视口尺寸外，还可能体现设备缩放比例。如果在比较两个截图时不考虑缩放，即使布局相同，也可能看起来尺寸发生了变化。

在视觉测试中，将屏幕尺寸、视口大小和缩放视为独立的输入。将桌面浏览器调整为窄内容区域可以测试响应式布局，但仅靠这一点并不能再现物理移动设备的所有特性。触控行为、浏览器控件以及特定设备的交互需要单独进行评估。

视口高度单位描述不同的显示条件

视口相关的 CSS 单位使样式能够依赖浏览器视口的尺寸，而现代视口单位还能区分不同的显示条件。应根据预期的布局行为来选择这些单位，而不是将它们当作可以互换的缩写来使用。

一个全高面板说明了这个问题。随着用户在移动页面中滚动，浏览器控件可能会展开或折叠。一个应保持稳定的面板和一个应跟随当前可用空间变化的面板有不同的需求。选择合适的单位是设计决策的一部分。

测试交互，而不仅仅是初始截图。打开导航、聚焦到某个输入字段、滚动浏览内容，并检查重要控件在交互过程中是否依然可用。页面在加载时看起来可能是正确的，但在键盘出现后却会导致提交按钮被裁剪而不可见。

对于自动化检查，记录所代表的浏览器和显示状态。受控视口测试确立了该环境下的行为。它不应被描述为所有移动浏览器的界面或键盘行为完全相同的证明。

截图范围回答了不同的问题

截图范围决定页面的哪一部分会变成图像。视口捕获、整页捕获和元素捕获都可能是正确的，同时会生成截然不同的证据。

视口捕获显示在当前滚动位置下当前可见的区域。它有助于诊断遮罩层以及用户在滚动之前能看到的内容。整页捕获覆盖由工具支持的更大文档范围。元素捕获聚焦于某个组件，可能省略解释遮挡原因的周围上下文。

在选择图像之前先明确定义问题。要比较产品卡片的排版，组件捕获可能就足够了。要诊断一个同意横幅遮盖购买控件的情况，应保留周围页面。要归档一份长文档，整页图像可能有帮助，但它不能证明每个屏外元素都被访问过或每个懒加载条目都被填充。

在相关内容准备就绪后再进行捕获。字体、图像、异步数据和动画都会改变几何布局。两个名义尺寸相同的截图可能代表不同的应用状态，从而使它们的视觉差异具有误导性。

响应式测试应遵循内容断点

响应式测试应覆盖界面发生变化、内容变得难以使用的那些点。一小串流行设备名称无法替代这些特定于应用的边界。

在一个重要断点的上下位置检查布局。检查较长的导航标签、异常长的表格值、翻译后的文本和空状态。这些变体可以暴露出典型记录从未暴露的溢出问题。

一个有用的结果应包括：文本是否仍然可读、控件是否仍然可达，以及有意的滚动是否保持在其预期容器内。页面级的水平滚动条可能表明有元素逃离了其布局边界。检查导致问题的元素，而不是用无关的浏览器设置来掩盖症状。

框架有其自身的布局边界

嵌入式框架有一个文档，其视口与框架自身可用区域相关联。一个宽的父页面可以包含一个窄的嵌入式应用程序，因此只测试顶层视口会遗漏部分布局问题。

该 HTML iframe 模型 定义的是嵌入文档，而非普通的父文档内容。子文档可以拥有自己的响应式布局和滚动行为。

对于一个嵌入式小部件，同时记录顶层布局和框架尺寸。子应用可能因为其框架较窄而显示紧凑的导航，即使浏览器窗口很宽。根据嵌入布局的不同，更改父视口可能会或可能不会改变框架。

Scrapeless Agent Browser 中的视口规划

Scrapeless Agent Browser 通过其有文档说明的配置暴露浏览器环境控制。规划与屏幕相关的设置时，应参考 Agent Browser display and fingerprint configuration ；screen 属性和页面视口仍然必须被视为不同的概念。

使用 Agent Browser platform 完成一个定义好的渲染任务，并通过受支持的客户端表面设置实际视口。根据产生预期证据所需的工作量，查看 Scrapeless pricing 。

关于 iframe extraction with Playwright and Scrapeless 的讨论为嵌入文档提供了背景。本文未报告设备仿真测试或已执行的截图比较；其示例是用来解释如何正确指定此类测试。

结论

视口是浏览器的呈现边界，其含义取决于讨论的是布局还是当前可见性。应同时记录视口尺寸、缩放比例、滚动位置、捕获范围以及页面就绪状态。这些输入使视觉结果能描述实际的界面状态，而不是一个含糊的图像尺寸。