获取文本坐标

获取文本坐标 用于在移动端页面上根据文本内容定位元素，并返回其屏幕坐标。它常用于无法使用 XPath 等定位符时，通过文案定位元素后再做坐标点击或界面校验。

指令标识：MobileLocateByText
指令类型：移动端指令
指令描述：根据指定文本内容获取移动端页面元素的屏幕坐标

先选使用方式

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

方式	怎么用	适合人群
可视化编排（推荐先学）	拖入「获取文本坐标」节点，填写要匹配的文本与输出变量	大多数用户，零代码，适合快速搭建和调试
代码编排（Python）	在脚本中调用 `pos = bots.mobileLocateByText(text="登录", outKey="loginPosition")`	熟悉代码、需要复用脚本或批量生成流程的用户

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

什么时候用？

通过文本内容精确定位控件坐标，再结合坐标点击完成操作。
在无法使用 XPath 等定位符时，用文案定位获取坐标。
列表中存在多个相同文本时，用索引参数定位特定项。
获取弹窗或动态文案的屏幕位置，用于后续交互或布局校验。

使用前确认

目标文本已经显示在当前页面上。
你知道目标文本内容（需与界面显示一致，或使用正则匹配）。
如果页面上有多个相同文本，提前确认要定位第几个。
本指令属于页面定位类，默认失败处理为「报错中止」（STOP_ON_FAILURE）。

可视化编排：从 0 到跑通

先让移动端页面进入目标状态，确认目标文本可见。
在工作流画布中添加 获取文本坐标 节点。
在文本中填写要匹配的内容，例如 登录。
如有多个相同文本，在 匹配索引 中填写要定位第几个（默认 1）。
在 将结果保存至 中填写变量名，例如 loginPosition，运行后查看坐标结果。

【图片占位 | command-mobilelocatebytext-config】 建议放一张配置截图：右侧属性面板展示「文本」「匹配索引」「将结果保存至」。图片用于说明只需填写文本即可获得坐标。

参数说明

输入参数

界面名称	代码属性名	类型	必填	默认值	说明
文本	`text`	String	是	-	需要匹配的文本内容，不能为空，需与界面显示一致；也可使用正则表达式匹配。
匹配索引	`index`	Integer	否	`1`	指定返回第几个匹配项，按页面出现顺序计数，默认第 `1` 个。
超时时间	`timeout`	Double	否	`5000`	高级参数。查找文本的最大等待时间，单位毫秒。

输出参数

界面名称	代码属性名	类型	必填	说明
将结果保存至	`outKey`	JSON	是	保存定位到的元素坐标，结果为包含 `x`、`y` 的 Map 对象，例如变量名 `loginPosition`。

成功标准

输出变量得到包含 x、y 的坐标对象。
坐标位置与目标文本在屏幕上的实际位置一致。
后续坐标点击等节点能正常使用该坐标。

【图片占位 | command-mobilelocatebytext-success】 建议放一张运行成功截图：目标文本被定位，变量面板展示 x、y 坐标值。图片用于说明如何验证坐标获取结果。

失败排查

现象	可能原因	处理建议
未创建输出变量	未找到匹配文本	确认文本与界面显示一致；在后续逻辑中做好判空处理
定位到错误元素	页面存在多个相同文本	使用 `index` 参数指定第几个匹配项
文本暂未出现导致失败	页面尚未加载完成	适当调大 `timeout`，或在定位前增加等待
不同机型坐标偏差	分辨率差异	在不同机型上验证匹配结果，确保兼容性

Python 代码编排

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

# 根据文本“登录”获取元素坐标，返回值即包含 x、y 的坐标对象
position = bots.mobileLocateByText(
    text="登录",
    index=1,
    outKey="loginPosition",
)
print(position)

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

常见问题

Q1：文本内容必须完全匹配吗？

A：不一定。常规匹配要求文本与界面显示完全一致（包括空格、标点）；若无需完全匹配，可使用正则表达式，例如 /^hello/ 可匹配所有以 hello 开头的文本。

Q2：如果页面上有多个相同文本的元素怎么办？

A：可以使用 index 参数指定返回第几个匹配项。index 按文本在页面中出现的顺序计数，从 1 开始；不填时默认返回第一个匹配。

Q3：如果未找到匹配的文本会怎样？

A：不会创建输出变量。建议在后续逻辑中做好判空处理，避免后续步骤因变量不存在而报错。

Q4：返回的坐标有什么特点？

A：坐标为像素单位，基于当前设备分辨率。结果为包含 x、y 的 Map 对象，可通过 ${变量名.x} 和 ${变量名.y} 获取具体坐标值。建议在不同机型上验证兼容性。