获取控件树

获取控件树 用于获取当前手机界面的控件树（页面源 / pageSource），即当前屏幕上所有可见控件的层级结构与属性。它常用于调试阶段分析页面结构、确认控件属性、辅助编写稳定的元素选择器，结果通过输出变量保存后供后续节点引用。

指令标识：MobileGetPageSource
指令类型：手机指令
指令描述：获取当前界面控件树

先选使用方式

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

方式	怎么用	适合人群
可视化编排（推荐先学）	拖入「获取控件树」节点，选择「处理方式」并填写「将结果保存至」	大多数用户，零代码，适合快速搭建和调试
代码编排（Python）	在脚本中调用 `bots.mobileGetPageSource(outKey="pageSource")`	熟悉代码、需要复用脚本或批量生成流程的用户

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

什么时候用？

调试阶段需要查看当前界面有哪些控件、各自的属性（text、resource-id 等）。
自动化定位失败时，需要确认元素是否存在、层级是否符合预期。
需要将页面结构作为快照保存，用于后续比对或问题排查。

使用前确认

当前流程已经连接并占用了一台可用的手机设备。
目标界面已经加载完成且处于稳定状态。
已规划好用于保存控件树的输出变量名，便于后续节点引用。

可视化编排：从 0 到跑通

下面用一个常见场景演示：在点击失败时先抓取控件树辅助排查。按 3 步即可跑起来：

在工作流画布中添加 获取控件树 指令，放在需要分析页面结构的位置。
在右侧配置面板选择 处理方式（XML 或 JSON），并在 将结果保存至 中填写一个变量名，例如 pageSource。
点击运行，在运行日志或变量值中查看控件树内容，据此确认元素属性并编写选择器。

【图片占位 | command-mobilegetpagesource-config】
截图内容建议： 截一张可视化编排页面，画布选中「获取控件树」节点，右侧属性面板展示「处理方式」与「将结果保存至」输入框。
标注建议： 用 ① 标出画布中的节点，用 ② 标出「处理方式」，用 ③ 标出「将结果保存至」输入框，用 ④ 标出运行后查看变量内容的入口。
用户看完应能明白： 选择控件树输出格式（XML/JSON），并把结果保存到一个输出变量，方便后续分析。

参数说明

输入参数

界面名称	代码属性名	类型	必填	默认值	说明
处理方式	`type`	Enum	是	-	控件树的输出格式：`XML`（输出为XML）、`JSON`（输出为JSON）

输出参数

界面名称	代码属性名	类型	必填	说明
将结果保存至	`outKey`	String	否	保存当前界面的控件树内容（页面源）。后续节点通过该变量名引用结果。

控件树通常较大，一般用于人工分析或调试，不建议在生产流程中频繁抓取以免影响性能。

成功标准

获取控件树 节点运行结束后状态为成功。
运行日志中没有参数缺失、超时或执行失败等错误。
如果配置了输出变量，后续节点能够读取到符合预期的结果。
后续节点能够继续执行，流程没有因为该节点异常中断。

失败排查

现象 / 报错原文	可能原因	处理建议
日志报 `Mobile device not configured`	流程未连接设备	先执行连接/占用设备节点，或在全局变量中配置设备上下文
日志报 `Mobile API ... business error`	移动端服务异常或设备失联	检查设备在线状态与移动端服务连通性，重连设备后重试
控件树为空或不完整	页面尚未加载完成	在获取前增加等待元素存在等待页面稳定
输出变量为空	未配置「将结果保存至」	检查是否填写了 `outKey`，并确认后续引用的变量名一致

Python 代码编排

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

# 获取当前界面控件树（XML 格式）并保存到变量 pageSource
bots.mobileGetPageSource(type="XML", outKey="pageSource")

可视化表单里的「处理方式」「将结果保存至」分别对应代码里的 type、outKey。

如果你想在工作流中通过节点动态编排指令，可使用执行指令（XML）节点。

常见问题

Q1：控件树包含哪些信息？

A：包含当前界面可见控件的层级结构及属性（如 text、resource-id、class、bounds 等），具体字段随平台与控件类型不同而不同。

Q2：抓取控件树会影响页面状态吗？

A：不会修改页面，只读取当前结构。但内容可能较大，建议仅在调试或必要排查时使用。

Q3：如何用控件树编写选择器？

A：在控件树中找到目标控件后，使用其稳定属性（如 resource-id、text）拼出 XPath，再配合点击、获取元素属性等指令使用。