命令速查表
所有命令速查表
交互命令（13 个）
| 命令 | 作用 | 示例 |
|---|---|---|
tapOn | 点击元素 | tapOn: "登录" |
longPressOn | 长按元素 | longPressOn: "文件" |
doubleTapOn | 双击元素 | doubleTapOn: "图片" |
swipe | 滑动 | swipe: { direction: UP } |
scroll | 滚动一次 | scroll |
scrollUntilVisible | 滚动直到可见 | 见进阶篇 |
inputText | 输入文字 | inputText: "hello" |
eraseText | 删除文字 | eraseText 或 eraseText: 10 |
pressKey | 按键 | pressKey: Home |
back | 返回 | back |
hideKeyboard | 收起键盘 | hideKeyboard 或 hide keyboard |
copyTextFrom | 复制元素文字 | copyTextFrom: { id: "code" } |
pasteText | 粘贴文字 | pasteText |
验证命令（4 个）
| 命令 | 作用 | 超时 |
|---|---|---|
assertVisible | 验证元素可见 | 17 秒 |
assertNotVisible | 验证元素不可见 | 7 秒 |
assertTrue | 验证脚本条件 | — |
extendedWaitUntil | 自定义等待 | 自定义 |
App 管理（6 个）
| 命令 | 作用 |
|---|---|
launchApp | 启动 App |
stopApp | 停止 App |
killApp | 强杀 App |
clearState | 清除 App 数据 |
openLink | 打开链接 |
setPermissions | 设置权限 |
流程控制（5 个）
| 命令 | 作用 |
|---|---|
repeat | 循环执行 |
break | 退出最近一层循环，只能在 repeat 内使用 |
retry | 失败重试 |
runFlow | 子流程（内联命令或引用文件） |
branch | 条件分支 |
数据与脚本（11 个）
| 命令 | 作用 |
|---|---|
defineVariables | 定义变量 |
evalScript | 执行 JS 表达式 |
runScript | 执行 JS（可注入变量） |
shell | evalScript 的简写 |
httpRequest | 发起 HTTP 请求 |
2fa | 生成 6 位 TOTP 验证码并保存到变量 |
setClipboard | 设置剪贴板 |
inputRandomText | 随机文字 |
inputRandomNumber | 随机数字 |
inputRandomEmail | 随机邮箱 |
inputRandomPersonName | 随机人名 |
设备控制（5 个）
| 命令 | 作用 |
|---|---|
sleep | 延时等待 |
setLocation | 设置 GPS 位置 |
setAirplaneMode | 设置飞行模式 |
takeScreenshot | 截图 |
waitForAnimationToEnd | 等待动画结束 |
所有按键名称
以下按键名称可以在 pressKey 命令中使用：
导航键
| 按键 | 说明 |
|---|---|
Home | 主页键 |
Back | 返回键 |
Menu | 菜单键 |
Search | 搜索键 |
Enter | 回车/确认 |
Tab | Tab 键 |
Escape | ESC 键 |
DpadUp | 方向键 ↑ |
DpadDown | 方向键 ↓ |
DpadLeft | 方向键 ← |
DpadRight | 方向键 → |
DpadCenter | 方向键中心 |
PageUp | 上翻页 |
PageDown | 下翻页 |
编辑键
| 按键 | 说明 |
|---|---|
Delete | 删除键（退格） |
Backspace | 退格键 |
ForwardDelete | 向前删除 |
Space | 空格键 |
音量与电源
| 按键 | 说明 |
|---|---|
VolumeUp | 音量加 |
VolumeDown | 音量减 |
Power | 电源键 |
Lock | 锁屏 |
电话
| 按键 | 说明 |
|---|---|
Call | 接听 |
EndCall | 挂断 |
字母与数字
| 按键 | 说明 |
|---|---|
A ~ Z | 字母键 |
0 ~ 9 | 数字键 |
Numpad0 ~ Numpad9 | 小键盘数字 |
符号
| 按键 | 说明 |
|---|---|
Comma | 逗号 , |
Period | 句号 . |
Grave | 反引号 ` |
Minus | 减号 - |
Equals | 等号 = |
Plus | 加号 + |
LeftBracket | 左方括号 [ |
RightBracket | 右方括号 ] |
Backslash | 反斜杠 \ |
Semicolon | 分号 ; |
Apostrophe | 撇号 ' |
Slash | 斜杠 / |
At | @ 符号 |
Star | 星号 * |
Pound | 井号 # |
其他
| 按键 | 说明 |
|---|---|
Camera | 相机键 |
Clear | 清除键 |
默认超时与限制
| 参数 | 默认值 | 说明 |
|---|---|---|
| 元素查找超时 | 17,000 ms | assertVisible 等命令的默认等待时间 |
| 可选元素查找超时 | 7,000 ms | optional: true 时的等待时间 |
| 界面稳定超时 | 1,500 ms | 点击/滑动后等待界面稳定的时间 |
| 脚本执行超时 | 200 ms | JS 表达式求值超时 |
| 动画等待超时 | 15,000 ms | waitForAnimationToEnd 默认超时 |
| 滑动默认时长 | 400 ms | swipe 默认持续时间 |
| 连续点击间隔 | 100 ms | tapOn 的 delay 默认值 |
| 滚动查找超时 | 20,000 ms | scrollUntilVisible 默认超时 |
| 滚动默认速度 | 40 | scrollUntilVisible 的 speed 参数（0~100） |
| 循环限制 | 无隐藏默认值 | repeat 只应用显式传入的 times、duration、while |
| 重试默认次数 | 1 次 | retry 不设 maxRetries 时的默认值 |
| 重试最大次数 | 3 次 | retry 的 maxRetries 上限 |
| 单命令异常处理重试 | 5 次 | 异常处理器对单条命令的最大重试次数 |
| 最大删除字符数 | 50 个 | eraseText 默认删除上限 |
| 界面稳定等待上限 | 30,000 ms | waitToSettleTimeoutMs 最大值 |
| HTTP 重试间隔 | 3,000 ms | httpRequest retry 默认间隔 |
常见问题
Q: tapOn 找不到元素怎么办？
- 确认文字完全匹配（包括大小写、空格）
- 尝试使用正则：
tapOn: "登录.*" - 尝试使用 ID：
tapOn: { id: "btn_login" } - 加上
optional: true让它不报错
Q: 如何在不同设备上适配？
使用百分比坐标代替绝对坐标：
yaml
# 不推荐（只适用于特定分辨率）
- tapOn: { point: "540,1200" }
# 推荐（任何分辨率都生效）
- tapOn: { point: "50%,60%" }Q: sleep 的随机范围怎么选？
- 快速操作间隔：
sleep: [500, 1500]（0.5~1.5 秒） - 模拟阅读浏览：
sleep: [3000, 8000]（3~8 秒） - 等待加载完成：
sleep: [5000, 10000]（5~10 秒）
Q: chance 和 when 能同时用吗？
同时写时，when 生效，chance 被忽略。它们是二选一的关系——chance: 0.3 其实等价于 when: { true: "${Math.random() < 0.3}" }，只是写起来更方便。
Q: repeat 的 duration 单位是什么？
毫秒（ms）。常用换算：
- 1 秒 = 1,000
- 1 分钟 = 60,000
- 10 分钟 = 600,000
- 30 分钟 = 1,800,000
- 1 小时 = 3,600,000
Q: 变量在子流程中修改后，外面能看到吗？
能看到。evalScript 修改的变量存在全局作用域中，子流程中修改后外面立刻生效。
Q: httpRequest 的 jsonPath 怎么写？
用点号分隔的路径，从 JSON 根节点开始：
json
{ "data": { "user": { "name": "张三" } } }对应 jsonPath：data.user.name，结果为 "张三"。