根据屏幕比例滑动

根据屏幕比例滑动 用于在移动设备上按屏幕宽高比例设置起点和终点，并执行滑动操作。它不依赖固定像素坐标，适合不同分辨率设备上的滚动、翻页、刷新和手势导航。

指令标识：MobileSwipeByProportion
指令类型：移动端指令
指令描述：在移动设备上按屏幕比例进行滑动操作

先选使用方式

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

方式	怎么用	适合人群
可视化编排（推荐先学）	拖入「根据屏幕比例滑动」节点，填写起点和终点比例	大多数用户，零代码，适合快速搭建和调试
代码编排（Python）	在脚本中调用 `bots.mobileSwipeByProportion(startX=0.5, startY=0.7, endX=0.5, endY=0.3)`	熟悉代码、需要复用脚本或批量生成流程的用户

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

什么时候用？

需要在移动端页面中向上或向下滚动查找内容。
需要做横向翻页，例如轮播图、卡片列表或引导页。
需要在不同分辨率设备上保持相同滑动位置和方向。
需要触发下拉刷新、上拉加载或手势导航。

使用前确认

已连接并启动目标移动设备或云手机环境。
起点和终点比例都在 0~1 之间。
起点和终点不能完全相同，否则无法形成有效滑动。
页面当前区域允许滑动，且没有弹窗或遮罩阻挡手势。

【图片占位 | command-mobileswipebyproportion-config】
截图内容建议： 截一张可视化编排页面，画布选中「根据屏幕比例滑动」节点，右侧属性面板展示起点/终点比例和滑动速度。
标注建议： 用 ① 标出起点 X/Y，用 ② 标出终点 X/Y，用 ③ 标出滑动速度，用 ④ 标出运行按钮。
用户看完应能明白： 比例坐标以屏幕左上角为原点，0.5 表示屏幕中线位置。

可视化编排：从 0 到跑通

下面用一个常见场景演示：在移动端商品列表页向上滑动加载更多内容。按 4 步即可跑起来：

在工作流画布中添加 根据屏幕比例滑动 指令。
设置起点为屏幕偏下方，例如 起点x轴比例 0.5、起点y轴比例 0.7。
设置终点为屏幕偏上方，例如 终点x轴比例 0.5、终点y轴比例 0.3，滑动速度选择 NORMAL。
运行后确认页面内容向上滚动，必要时在后续增加等待或元素验证节点。

参数说明

输入参数

界面名称	代码属性名	类型	必填	默认值	说明
起点x轴比例	`startX`	Double	是	-	起始坐标 x 轴的比例，区间 `0~1`。
起点y轴比例	`startY`	Double	是	-	起始坐标 y 轴的比例，区间 `0~1`。
终点x轴比例	`endX`	Double	是	-	结束坐标 x 轴的比例，区间 `0~1`。
终点y轴比例	`endY`	Double	是	-	结束坐标 y 轴的比例，区间 `0~1`。
滑动速度	`slideSpeed`	Enum	否	`NORMAL`	高级选项。屏幕滑动速度：`SLOW`(慢)、`NORMAL`(正常)、`FAST`(快)。
是否发送消息	`sendMsgFlag`	Boolean	否	`True`	是否发送节点消息。

输出参数

该指令主要执行滑动动作，原文未提供可配置输出参数；如需确认滑动结果，建议后续接元素验证、获取文本或页面状态类指令。

成功标准

节点正常执行，没有比例越界或手势执行错误。
页面按照起点到终点方向发生滑动。
后续节点能找到滑动后出现的目标元素或内容。

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

页面列表向上滚动，屏幕中出现新的商品卡片或更多表单项。
运行日志中没有 SWIPE_ELEMENT_ERROR 相关错误。

【图片占位 | command-mobileswipebyproportion-success】
建议放一张运行成功截图：移动端页面完成滚动，运行日志中该节点为成功状态。图片用于说明滑动动作跑通后的效果。

失败排查

现象 / 报错原文	可能原因	处理建议
抛出 `SWIPE_ELEMENT_ERROR`	比例值超出 `0~1`，或手势执行失败	检查 `startX`、`startY`、`endX`、`endY` 是否都在 `0~1`
页面没有明显滑动	起点和终点距离太近，或方向设置不符合预期	增大起点与终点差值，例如 `startY=0.7`、`endY=0.3`
iOS 上无法滑动到预期位置	起点位于刘海或系统手势区域	避开屏幕顶部边缘，建议 `yRatio >= 0.05`
滑动后目标内容未出现	页面加载慢或需要多次滑动	增加等待节点，或在循环中多次滑动并验证目标元素

Python 代码编排

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

# 从屏幕中间偏下位置向上滑动
bots.mobileSwipeByProportion(
    startX=0.5,
    startY=0.7,
    endX=0.5,
    endY=0.3,
    slideSpeed="NORMAL",
)

可视化表单里的「起点x轴比例」「起点y轴比例」「终点x轴比例」「终点y轴比例」「滑动速度」分别对应代码里的 startX、startY、endX、endY、slideSpeed。

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

常见问题

Q1：比例值有什么要求？

A：所有坐标比例值（startX、startY、endX、endY）必须在 0~1 之间。0 表示屏幕左侧或顶部，1 表示屏幕右侧或底部，0.5 表示屏幕中心位置。当比例值超出 0~1 范围时会抛出 SWIPE_ELEMENT_ERROR。

Q2：如何实现不同方向的滑动？

A：通过起始和结束坐标的差值确定方向。向上滑动：startY > endY；向下滑动：startY < endY；向左滑动：startX > endX；向右滑动：startX < endX。

Q3：比例坐标如何转换为实际像素？

A：比例坐标会乘以 windowSize 得到实际像素，端到端兼容横竖屏。例如宽度为 750px 的屏幕上，startX=0.5 会转换为 375px。

Q4：iOS 设备有什么特殊限制？

A： iOS 屏幕刘海区域坐标（约 0~44px）可能无法操作，建议 yRatio >= 0.05。使用比例值而非固定坐标，有助于在不同设备上稳定执行。