截图

截图用于捕获当前网页页面的屏幕快照并上传保存，返回截图文件的访问 URL。它常用于测试结果记录、问题排查取证、界面状态保存和自动化测试报告生成等场景，支持全屏与局部区域截图。

指令标识：TakeScreenshot
指令类型：网页指令
指令描述：对当前页面进行截图并上传保存，支持多种截图配置选项

先选使用方式

工作流支持「可视化编排」和「代码编排」两种创建方式。截图在两种方式里都能用，核心业务参数一致，区别主要是你通过界面配置，还是通过 Python 脚本配置。

方式	怎么用	适合人群
可视化编排（推荐先学）	拖入「截图」节点，按需配置截图选项，并设置输出变量名	大多数用户，零代码，适合快速搭建和调试
代码编排（Python）	在脚本中调用 `bots.takeScreenshot(outKey="screenshotPath")`	熟悉代码、需要复用脚本或批量生成流程的用户

第一次使用建议先用可视化编排跑通，再迁移到 Python 代码编排。下方「参数说明」同时给出界面字段和代码参数名，方便两种方式对应。

什么时候用？

在自动化测试中截取关键步骤，用于生成测试报告。
测试失败或异常时自动截图保存现场，便于排查取证。
保存页面在特定状态下的截图，用于 UI 验证或文档编写。
定期对页面截图归档，用于版本对比或合规审计。

使用前确认

浏览器已打开目标页面（通常先执行打开网页）。
页面已加载完成，必要时先用延迟或等待页面加载。
已规划好输出变量名，用于保存截图访问 URL。
如需局部截图，已确认裁剪区域的坐标和宽高。

可视化编排：从 0 到跑通

下面用一个常见场景演示：打开页面后截取整页快照并保存 URL。按 4 步即可跑起来：

先添加打开网页节点，打开目标页面：

https://example.com

紧接着添加截图节点。
如需局部截图，在 截图选项 中配置裁剪区域；默认即整页截图。设置输出变量名（如 screenshotPath）。
点击运行，确认输出变量中得到截图文件的访问 URL。

参数说明

输入参数

界面名称	代码属性名	类型	必填	默认值	说明
截图选项	`screenshotOption`	JSON	否	-	截图的高级配置选项（`ScreenshotOptions` 类型），支持截图质量、格式、动画禁用、局部区域裁剪与全屏等设置。

screenshotOption 内常用字段说明：

字段	类型	默认值	说明
`fullPage`	Boolean	`true`	是否截取整个可滚动页面的完整截图，默认开启。
`clip.x`	Number	`0`	局部截图区域起点横坐标，用于局部截图。
`clip.y`	Number	`0`	局部截图区域起点纵坐标，用于局部截图。
`clip.width`	Number	-	局部截图区域宽度（像素）。`fullPage` 为 `false` 时必填。
`clip.height`	Number	-	局部截图区域高度（像素）。`fullPage` 为 `false` 时必填。

输出参数

界面名称	代码属性名	类型	必填	说明
将结果保存至	`outKey`	String	否	填写变量名称（如 `screenshotPath`），保存截图文件的访问 URL（字符串类型）。

成功标准

节点运行成功，日志中没有截图或上传相关错误。
输出变量中得到一个可访问的截图文件 URL。
打开该 URL 能看到预期的页面截图内容。

运行后你会看到（以上面场景为例）：

输出变量（如 screenshotPath）中得到截图文件的访问 URL。
打开 URL 可看到完整页面截图。

失败排查

现象 / 报错原文	可能原因	处理建议
截图内容不完整或空白	页面尚未加载完成	截图前增加「延迟」或「等待页面加载」节点
局部截图报错或裁剪异常	`fullPage` 为 `false` 时缺少 `clip.width`/`clip.height`	补全局部截图的宽高参数
输出 URL 为空	未配置 `outKey`	填写有效的输出变量名
截图上传失败	执行环境网络异常	检查执行环境网络后重试

Python 代码编排

代码编排以 Python 为主。运行上下文由代码编排模板创建，示例里只需要关注业务指令本身。

# 打开页面后截取整页快照，URL 保存到 screenshotPath
bots.openUrl(url="https://example.com")
bots.takeScreenshot(outKey="screenshotPath")

需要局部截图时，通过 screenshotOption 配置裁剪区域：

bots.takeScreenshot(
    screenshotOption='{"clip":{"x":0,"y":0,"width":100,"height":100},"fullPage":false}',
    outKey="output",
)

可视化表单里的「截图选项」「将结果保存至」分别对应代码里的 screenshotOption、outKey。如果你想在工作流中通过节点动态编排指令，可使用执行指令（XML）节点。

常见问题

Q1：截图前需要注意什么？

A：建议在截图前等待页面完全加载，确保截图内容准确。可以使用延迟或等待页面加载指令。

Q2：截图文件保存在哪里？

A：截图完成后会自动上传文件并将访问 URL 保存到指定变量中。截图文件默认为 PNG 格式，保证图像质量和透明度支持。

Q3：全屏截图和局部截图的优先级是什么？

A：局部截图（clip 的 x、y、width、height）与全屏截图（fullPage=true）同时设置时，全屏设置优先级更高。使用 fullPage=true 会截取整个可滚动页面，包括需要滚动才能看到的内容。

Q4：截图过程中页面动画会影响截图吗？

A：不会。截图过程中会自动禁用页面动画，确保截图内容稳定，避免动态效果影响截图质量。

截图