二、如何使用Airtest API 文档

1. 前言

在之前的AirtestIDE使用文档中，我们更多的是介绍如何使用IDE提供的自动录制或者辅助录制功能来编写我们的Airtest脚本，但实际上，为了编写出更多更复杂的Airtest脚本，我们更建议大家学会使用 Airtest API 文档，查阅更多的API来帮助我们实现更多复杂的自动化操作。

打开Airtest API的官方文档，我们可以从左侧的目录中看到，这里包含了1份Airtest的快速上手文档，还有跨平台和平台相关的API等：

image-20211028155747096

下文我们将详细介绍，我们该如何使用这个API文档。

2. Airtest快速上手文档

阅读API文档中这部分的内容，可以快速让我们了解Airtest的支持情况以及简单示例（内容相对简单，更多关于Airtest脚本的详细内容还是建议阅读本文档的Airtest脚本入门章节内容）：

image-20211028160114618

3. 跨平台的Airtest核心API

这个模块包含了Airtest跨平台的各种API，也是Airtest的核心API：

image-20211028160413961

1）查看“支持平台”

在这个模块下面，我们可以查看API的平台支持情况，比如 :

  • touch接口支持Android、iOS和Windows平台
  • start_app接口支持Android和iOS平台
  • clear_app接口仅仅支持Android平台

image-20211028160753761

支持平台的意思就是，该API可以在支持的平台下运行，比如 touch 接口的支持平台是3个，那就意味着这个接口可以在Android设备、iOS设备甚至Windows窗口上面运行。

所以关注API的支持平台是非常重要的，因为Airtest提供了跨平台的API，也提供了平台专用的API，如果同学们强行把接口用在了不支持的平台上，那势必会产生各种报错，比如 clear_app 仅支持Android平台，那如果同学们不小心把它用在了iOS平台上，就会出现错误。

2）查看“参数”

除了需要关注核心API的支持平台情况，我们还需要关注API的参数情况。

举个最简单的例子，我们之前在录制脚本的时候，都知道 touch 接口里面的是一张图片，那是不是这个接口只能传入一张图片呢？这就需要我们到API文档查看一下它的参数情况了：

image-20211028161710393

可以看到这个API的参数情况，我们不仅可以给 touch 传入一个图片实例，还可以传入1个绝对坐标，类似 touch([100,100]) ；甚至我们还可以设置点击次数，比如我们想点击2次，即双击，可以设置 times=2 ，还有一些平台相关的参数。

知道API的参数情况，可以帮助我们实现更多操作效果。

3）查看“返回值”

有时候我们还需要关注API的返回值，比如我们想要拿到某个图片在当前画面的匹配坐标，该如何做呢？查一下各个API的返回值，可以看到有好几个API都可以满足我们的要求：

image-20211028165926665

再比如，我们想要实现1个功能，如果存在某个图片，就进行点击，否则就进行别的操作，我们也可以从API的返回值来找到适合的接口：

  1. if exists(图片)：
  2.     touch(图片)
  3. else:
  4.    pass

image-20211028170150611

可以看到，exists 接口，若找到了目标，返回目标的坐标，if 成立，可以对目标进行点击操作；若没有找到目标，则返回 false ，if 不成立，执行别的操作。

4）查看“示例”

另外，我们在Airtest 的核心API模块里，给各个API提供了示例脚本，方便同学们参考学习：

image-20211028170747955

4. 平台相关的API

这个模块下面包含了一些平台专用的API，包含Android、iOS和Windows平台：

image-20211028173915741

1）平台专属的API

每个平台都有一些专属的API，比如录屏模块，就是Android平台特有的：

image-20211028174159607

有时候，平台通用的API并不能满足我们的脚本编写需求，我们可以到平台专用的API这里查找下，是否有符合我们需求的专用API可以使用。

2）平台专属的API 参数

有一些接口，在通用平台下，只包含几个通用的参数，但在专用平台下，还会额外支持一些参数；比如 touch 接口，在通用平台下，支持传入点击位置pos和点击次数times这2个参数；但是在安卓专用模块下，还支持1个额外的参数，点击时长-duration：

image-20211028173309397

image-20211028173344147

5. 在API文档进行搜索

在编写Airtest脚本时，我们要善于利用API文档的搜索功能，举个例子，同学们经常问到一些问题，我们完全可以借助搜索API文档来实现：

比如，有同学会问，点击图片我会了，但如何实现双击呢？此时我们可以到Airtest的API文档里面搜touch，先从核心模块找起：

image-20211028174639561

发现跨平台的touch接口，支持设置点击次数：

image-20211028174735054

那我们只要给这个touch传入times=2，即可实现双击。

那又会有同学问，我想实现长按呢？比如点击2秒或者更长时间，那我们刚才看过了核心API的touch，没有参数可以实现这个效果，那我们再到平台专用模块里面去查一下，假设此时是Android设备：

image-20211028175048745

image-20211028175126263

可以看到，Android平台专用模块下的touch，是支持传入点击时长-duration的，那此时只需要给touch传入duration=2或者更长时间，即可达到我们想要的效果。