手势与按键

点击、滑动、拖拽、捏合，以及系统按键和键盘。坐标可以写 point，也可以写 0~1 的屏幕比例；方向滑动的起点、距离、角度、时长每次都重新随机，轨迹做成人手的样子。

功能概览

·swipe 系列走 W3C 通道，轨迹拟人；drag 系列走 WDA 原生通道，兼容性更好
·方向滑动默认避开屏幕边缘；要系统的边缘手势（比如右滑返回）就传 'edge'
·所有时间参数的单位都是秒

client.click#

按坐标点一下；给了 duration 就是按住这么多秒再松开（长按）。

typescript

client.click(x: number, y: number, duration?: number): object;

参数

参数名	类型	是否必填	默认值	描述
`x`	`number`	是	—	横坐标：0~1 的屏幕比例，或 point。
`y`	`number`	是	—	纵坐标：0~1 的屏幕比例，或 point。
`duration`	`number`	否	—	按住多少秒。不写就是普通点击。

返回值

类型	描述
`object`	WDA 的原始响应，一般用不到。

异常

异常类型	触发条件
`WDAError`	按比例换算时读不到屏幕尺寸（WDA 会话异常）。

注意事项

x、y 都在 0~1 之间时按屏幕比例换算（0.5, 0.5 是屏幕正中），否则按 point。换算要用到屏幕尺寸，取不到时会抛错。

示例

javascript

client.click(0.5, 0.5);        // 屏幕正中 / screen centre
client.click(200, 640);        // point
client.click(0.5, 0.9, 1.2);   // 长按 1.2 秒 / long press

参见 client.tapHold、element.click

client.swipe#

从 (x1, y1) 滑到 (x2, y2)。起点、终点照给的来；中间的轨迹做成人手的样子：随机弯一点、先慢后快、带细小抖动。

typescript

client.swipe(x1: number, y1: number, x2: number, y2: number, durationSec?: number): object;

参数

参数名	类型	是否必填	默认值	描述
`x1`	`number`	是	—	起点横坐标。
`y1`	`number`	是	—	起点纵坐标。
`x2`	`number`	是	—	终点横坐标。
`y2`	`number`	是	—	终点纵坐标。
`durationSec`	`number`	否	`0`	从开始移动到抬手的秒数。0 表示按距离自动取一个随机时长。

返回值

类型	描述
`object`	WDA 的原始响应，一般用不到。

异常

异常类型	触发条件
`WDAError`	按比例换算时读不到屏幕尺寸（WDA 会话异常）。

注意事项

x、y 都在 0~1 之间时按屏幕比例换算（0.5, 0.5 是屏幕正中），否则按 point。换算要用到屏幕尺寸，取不到时会抛错。

示例

javascript

client.swipe(0.5, 0.8, 0.5, 0.2);        // 往上滑 / swipe up
client.swipe(0.5, 0.8, 0.5, 0.2, 0.6);   // 指定 0.6 秒 / take 0.6 seconds

参见 client.swipeUp、client.drag

client.drag#

WDA 原生拖拽，从 (x1, y1) 拖到 (x2, y2)。轨迹和速度由系统生成；在部分 App（自绘控件、老系统）上比 swipe 更可靠。

typescript

client.drag(x1: number, y1: number, x2: number, y2: number, durationSec?: number): object;

参数

参数名	类型	是否必填	默认值	描述
`x1`	`number`	是	—	起点横坐标。
`y1`	`number`	是	—	起点纵坐标。
`x2`	`number`	是	—	终点横坐标。
`y2`	`number`	是	—	终点纵坐标。
`durationSec`	`number`	否	`0`	在起点按住多少秒再开始拖，不是拖拽本身的耗时。0 表示按下就拖。

返回值

类型	描述
`object`	WDA 的原始响应，一般用不到。

异常

异常类型	触发条件
`WDAError`	按比例换算时读不到屏幕尺寸（WDA 会话异常）。

注意事项

x、y 都在 0~1 之间时按屏幕比例换算（0.5, 0.5 是屏幕正中），否则按 point。换算要用到屏幕尺寸，取不到时会抛错。

示例

javascript

client.drag(0.2, 0.5, 0.8, 0.5, 0.3);

参见 client.swipe、client.dragUp

client.swipeUp#

手指往上滑（内容往上走，看下面的）。起点、距离（屏幕的 35%~55%）、角度（±5°）和时长每次都重新随机，默认离屏幕边缘至少 8%，不会误触系统的边缘手势。走 W3C 手势通道，轨迹做成人手的样子：随机弯一点、先慢后快、带细小抖动。

typescript

client.swipeUp(from?: "edge"): object;

参数

参数名	类型	是否必填	默认值	描述
`from`	`"edge"`	否	—	不写是正常滑动；写 'edge' 从屏幕边缘起手：从屏幕底边起手，相当于系统的回主屏手势，一般用不到。

返回值

类型	描述
`object`	WDA 的原始响应，一般用不到。

异常

异常类型	触发条件
`WDAError`INVALID_ARGUMENT	参数既不是不写，也不是 'edge'（比如照旧写法传了 { fromEdge: true }）。

注意事项

刷信息流那种从屏幕下部小幅快速上滑，用 client.swipeUpFromBottom()；对应的还有 swipeDownFromBottom、dragUpFromBottom、dragDownFromBottom。

示例

javascript

client.swipeUp();

参见 client.swipe

client.swipeDown#

手指往下滑（内容往下走，看上面的）。起点、距离（屏幕的 35%~55%）、角度（±5°）和时长每次都重新随机，默认离屏幕边缘至少 8%，不会误触系统的边缘手势。走 W3C 手势通道，轨迹做成人手的样子：随机弯一点、先慢后快、带细小抖动。

typescript

client.swipeDown(from?: "edge"): object;

参数

参数名	类型	是否必填	默认值	描述
`from`	`"edge"`	否	—	不写是正常滑动；写 'edge' 从屏幕边缘起手：从屏幕顶边起手，会拉出通知中心。

返回值

类型	描述
`object`	WDA 的原始响应，一般用不到。

异常

异常类型	触发条件
`WDAError`INVALID_ARGUMENT	参数既不是不写，也不是 'edge'（比如照旧写法传了 { fromEdge: true }）。

示例

javascript

client.swipeDown();

参见 client.swipe

client.swipeLeft#

手指从右往左滑。起点、距离（屏幕的 35%~55%）、角度（±5°）和时长每次都重新随机，默认离屏幕边缘至少 8%，不会误触系统的边缘手势。走 W3C 手势通道，轨迹做成人手的样子：随机弯一点、先慢后快、带细小抖动。

typescript

client.swipeLeft(from?: "edge"): object;

参数

参数名	类型	是否必填	默认值	描述
`from`	`"edge"`	否	—	不写是正常滑动；写 'edge' 从屏幕边缘起手：从屏幕右边缘起手。

返回值

类型	描述
`object`	WDA 的原始响应，一般用不到。

异常

异常类型	触发条件
`WDAError`INVALID_ARGUMENT	参数既不是不写，也不是 'edge'（比如照旧写法传了 { fromEdge: true }）。

示例

javascript

client.swipeLeft();

参见 client.swipe

client.swipeRight#

手指从左往右滑。起点、距离（屏幕的 35%~55%）、角度（±5°）和时长每次都重新随机，默认离屏幕边缘至少 8%，不会误触系统的边缘手势。走 W3C 手势通道，轨迹做成人手的样子：随机弯一点、先慢后快、带细小抖动。

typescript

client.swipeRight(from?: "edge"): object;

参数

参数名	类型	是否必填	默认值	描述
`from`	`"edge"`	否	—	不写是正常滑动；写 'edge' 从屏幕边缘起手：从屏幕左边缘起手，就是系统的「返回」手势。

返回值

类型	描述
`object`	WDA 的原始响应，一般用不到。

异常

异常类型	触发条件
`WDAError`INVALID_ARGUMENT	参数既不是不写，也不是 'edge'（比如照旧写法传了 { fromEdge: true }）。

示例

javascript

client.swipeRight();          // 普通右滑 / a normal swipe
client.swipeRight('edge');    // 返回上一页 / go back

参见 client.swipe

client.dragUp#

手指往上拖（内容往上走）。起点、距离（屏幕的 35%~55%）、角度（±5°）和时长每次都重新随机，默认离屏幕边缘至少 8%，不会误触系统的边缘手势。走 WDA 原生拖拽通道，拖之前在起点随机按住 0.05~0.2 秒。某个 App 里 swipe 不生效时改用这一组。

typescript

client.dragUp(from?: "edge"): object;

参数

参数名	类型	是否必填	默认值	描述
`from`	`"edge"`	否	—	不写是正常滑动；写 'edge' 从屏幕边缘起手：从屏幕底边起手。

返回值

类型	描述
`object`	WDA 的原始响应，一般用不到。

异常

异常类型	触发条件
`WDAError`INVALID_ARGUMENT	参数既不是不写，也不是 'edge'（比如照旧写法传了 { fromEdge: true }）。

示例

javascript

client.dragUp();

参见 client.drag

client.dragDown#

手指往下拖（内容往下走）。起点、距离（屏幕的 35%~55%）、角度（±5°）和时长每次都重新随机，默认离屏幕边缘至少 8%，不会误触系统的边缘手势。走 WDA 原生拖拽通道，拖之前在起点随机按住 0.05~0.2 秒。某个 App 里 swipe 不生效时改用这一组。

typescript

client.dragDown(from?: "edge"): object;

参数

参数名	类型	是否必填	默认值	描述
`from`	`"edge"`	否	—	不写是正常滑动；写 'edge' 从屏幕边缘起手：从屏幕顶边起手。

返回值

类型	描述
`object`	WDA 的原始响应，一般用不到。

异常

异常类型	触发条件
`WDAError`INVALID_ARGUMENT	参数既不是不写，也不是 'edge'（比如照旧写法传了 { fromEdge: true }）。

示例

javascript

client.dragDown();

参见 client.drag

client.dragLeft#

手指从右往左拖。起点、距离（屏幕的 35%~55%）、角度（±5°）和时长每次都重新随机，默认离屏幕边缘至少 8%，不会误触系统的边缘手势。走 WDA 原生拖拽通道，拖之前在起点随机按住 0.05~0.2 秒。某个 App 里 swipe 不生效时改用这一组。

typescript

client.dragLeft(from?: "edge"): object;

参数

参数名	类型	是否必填	默认值	描述
`from`	`"edge"`	否	—	不写是正常滑动；写 'edge' 从屏幕边缘起手：从屏幕右边缘起手。

返回值

类型	描述
`object`	WDA 的原始响应，一般用不到。

异常

异常类型	触发条件
`WDAError`INVALID_ARGUMENT	参数既不是不写，也不是 'edge'（比如照旧写法传了 { fromEdge: true }）。

示例

javascript

client.dragLeft();

参见 client.drag

client.dragRight#

手指从左往右拖。起点、距离（屏幕的 35%~55%）、角度（±5°）和时长每次都重新随机，默认离屏幕边缘至少 8%，不会误触系统的边缘手势。走 WDA 原生拖拽通道，拖之前在起点随机按住 0.05~0.2 秒。某个 App 里 swipe 不生效时改用这一组。

typescript

client.dragRight(from?: "edge"): object;

参数

参数名	类型	是否必填	默认值	描述
`from`	`"edge"`	否	—	不写是正常滑动；写 'edge' 从屏幕边缘起手：从屏幕左边缘起手。

返回值

类型	描述
`object`	WDA 的原始响应，一般用不到。

异常

异常类型	触发条件
`WDAError`INVALID_ARGUMENT	参数既不是不写，也不是 'edge'（比如照旧写法传了 { fromEdge: true }）。

示例

javascript

client.dragRight();

参见 client.drag

client.scroll#

让 WDA 自己按方向滚动当前界面。滚动量由 XCUITest 计算，对列表这类可滚动容器比滑动更可靠。

typescript

client.scroll(direction: "up" | "down" | "left" | "right", distance?: number): object;

参数

参数名	类型	是否必填	默认值	描述
`direction`	`"up" \| "down" \| "left" \| "right"`	是	—	滚动方向。
`distance`	`number`	否	`1.0`	滚动距离，1.0 约等于一屏。

返回值

类型	描述
`object`	WDA 的原始响应，一般用不到。

示例

javascript

client.scroll('down', 1.0);

参见 client.swipeUp

client.pinch#

双指缩放：scale 大于 1 是两指张开（放大），小于 1 是两指捏合（缩小）。

typescript

client.pinch(scale: number, velocity?: number): object;

参数

参数名	类型	是否必填	默认值	描述
`scale`	`number`	是	—	缩放倍数。
`velocity`	`number`	否	`1`	速度；捏合（scale 小于 1）时要传负数。

返回值

类型	描述
`object`	WDA 的原始响应，一般用不到。

示例

javascript

client.pinch(2, 1);      // 放大 / zoom in
client.pinch(0.5, -1);   // 缩小 / zoom out

client.hideKeyboard#

收起键盘；client.isKeyboardShown() 判断键盘是否弹出。

typescript

client.hideKeyboard(): boolean;
client.isKeyboardShown(): boolean;

返回值

类型	描述
`boolean`	hideKeyboard：键盘收起了返回 true（本来就没弹出也算）；isKeyboardShown：键盘可见返回 true。

示例

javascript

if (client.isKeyboardShown()) {
  client.hideKeyboard();
}

参见 client.sendKeys

client.tapHold#

在某点按住一段时间再松开（长按）。

typescript

client.tapHold(x: number, y: number, duration?: number): object;

参数

参数名	类型	是否必填	默认值	描述
`x`	`number`	是	—	横坐标：0~1 的屏幕比例，或 point。
`y`	`number`	是	—	纵坐标：0~1 的屏幕比例，或 point。
`duration`	`number`	否	`1.0`	按住多少秒。

返回值

类型	描述
`object`	WDA 的原始响应，一般用不到。

异常

异常类型	触发条件
`WDAError`	按比例换算时读不到屏幕尺寸（WDA 会话异常）。

注意事项

x、y 都在 0~1 之间时按屏幕比例换算（0.5, 0.5 是屏幕正中），否则按 point。换算要用到屏幕尺寸，取不到时会抛错。

示例

javascript

client.tapHold(0.5, 0.5, 1.5);

参见 client.click

client.home#

回到主屏幕。

typescript

client.home(): void;

示例

javascript

client.home();

参见 client.press

client.press#

按系统按键：home、volumeUp、volumeDown。

typescript

client.press(name: "home" | "volumeUp" | "volumeDown"): object;

参数

参数名	类型	是否必填	默认值	描述
`name`	`"home" \| "volumeUp" \| "volumeDown"`	是	—	按键名。

返回值

类型	描述
`object`	WDA 的原始响应，一般用不到。

异常

异常类型	触发条件
`Error`	按键名不是这三个之一。

示例

javascript

client.press('volumeUp');

参见 client.home

client.sendKeys#

往当前有焦点的输入框里打字，逐字走键盘。先点一下输入框让它获得焦点。

typescript

client.sendKeys(value: string): object;

参数

参数名	类型	是否必填	默认值	描述
`value`	`string`	是	—	要输入的文字，支持中文。

返回值

类型	描述
`object`	WDA 的原始响应，一般用不到。

示例

javascript

clickElement('accessibilityId', 'search_field', 5);
client.sendKeys('hello');

参见 client.hideKeyboard、client.setClipboard

client.lock#

锁屏；client.unlock() 解锁，client.locked() 查询是否锁着。

typescript

client.lock(): object;
client.unlock(): object;
client.locked(): boolean;

返回值

类型	描述
`object \| boolean`	lock / unlock 返回 WDA 的原始响应；locked 锁着返回 true。

注意事项

只能解开没有设锁屏密码的设备。

示例

javascript

if (client.locked()) {
  client.unlock();
}