二、如何使用Poco API文档¶
1. 前言¶
除了使用AirtestIDE帮助我们录制Poco脚本之外，我们还可以借助Poco API文档，查找和学习更多与Poco框架相关的内容，帮助我们写出内容更加丰富Poco脚本。
我们在poco的API文档中，不仅仅可以搜索框架的API及其用法，还可以查看poco的一些入门教程和poco-SDK的接入教程：
2. Poco入门教程¶
在Poco的入门教程中，汇总了框架的绝大部分内容，包含poco脚本的示例、poco框架的安装、入门教学用例、poco如何定位控件、poco的核心API介绍、poco使用的坐标系等等：
3. Poco框架的API及相关异常¶
1）Poco类的方法¶
我们可以在这里找到Poco类的所有方法和参数：
① 常用API介绍¶
在Poco类里，我们常用的API，比如：
- 点击：
click - 冻结：
freeze - 长按：
long_click - 滑动：
swipe - 自定义渲染分辨率：
use_render_resolution - ......
from poco.drivers.android.uiautomation import AndroidUiautomationPoco
poco = AndroidUiautomationPoco(use_airtest_input=True, screenshot_each_action=False)
# 单击画面中心位置
poco.click([0.5,0.5])
# 长按画面中心位置
poco.long_click([0.5,0.5])
# 向左滑动
poco.swipe([0.9,0.5],[0.3,0.5])
# 冻结当前的UI树，可提高poco查找效率
frozen_poco = poco.freeze()
# 自定义渲染分辨率，为更好支持更多不兼容的全面屏设备
poco.use_render_resolution(True, (0 ,100 ,1080 ,2020))
② Poco使用的坐标系¶
Poco的坐标系与Airtest不一样，Airtest使用的是绝对坐标系，在Airtest的脚本里，我们可以传入类似 touch([500,500]) 这样的绝对坐标；但Poco只能接受绝对坐标（归一化坐标系），如上述示例中的 poco.click([0.5,0.5]) 。
归一化坐标系就是将屏幕宽和高按照单位一来算，这样UI在poco中的宽和高其实就是相对于屏幕的百分比大小了，好处就是不同分辨率设备之间，同一个UI的归一化坐标系下的位置和尺寸是一样的，有助于编写跨设备测试用例。
归一化坐标系的空间是均匀的，屏幕正中央一定是(0.5, 0.5)，其他标量和向量的计算方法同欧式空间。
2）Poco控件类的方法¶
Poco控件类的所有方法和参数我们可以在这里找到：
在Poco框架中，最重要的就是学会如何定位控件以及对控件进行各种操作。
① 控件定位相关的API¶
Poco控件给我们提供了利用树的层级关系来定位的各种方法：
- 子节点：
child - 所有子节点：
children - 子孙节点：
offspring - 父节点：
parent - 兄弟节点：
sibling
from poco.drivers.android.uiautomation import AndroidUiautomationPoco
poco = AndroidUiautomationPoco(use_airtest_input=True, screenshot_each_action=False)
poco("com.mumu.launcher:id/workspace").child("android.view.ViewGroup")
我们需要根据控件树的详细层级关系，来选去合适的定位方法来定位我们的Poco控件。
② 控件操作相关的API¶
控件操作的API就非常多了：
- 获取控件的属性信息：
attr - 点击：
click - 拖动：
drag_to - 存在：
exists - 内外偏移：
focus - 获取控件的text属性值：
get_text - 设置控件的text属性值：
set_text - ......
from poco.drivers.android.uiautomation import AndroidUiautomationPoco
poco = AndroidUiautomationPoco(use_airtest_input=True, screenshot_each_action=False)
# 控件点击操作
poco(text="网易大神").click()
# 获取控件的name属性值
poco(text="网易大神").attr("name")
# 判断控件存在
poco(text="网易大神").exists()
# 设置控件的文本信息
poco("android.widget.EditText").set_text("123")
# ......
③ 控件使用的坐标系¶
局部坐标系是为了表示相对于某UI的坐标。局部坐标系以UI包围盒左上角为原点，向右为x轴，向下为y轴，包围盒宽和高均为单位1。其余的定义和归一化坐标系类似。
局部坐标系可以更灵活地定位UI内或外的位置，例如(0.5, 0.5)就代表UI的正中央，超过1或小于0的坐标值则表示UI的外面。内外部偏移方法focus就是依据这个坐标系原理实现的。
from poco.drivers.unity3d import UnityPoco
poco = UnityPoco()
# 点击星星控件左上角的位置
poco("star_single").focus([0,0]).click()
# 点击星星控件的中心位置，等同于poco("star_single").click()
poco("star_single").focus([0.5,0.5]).click()
# 点击星星控件的外部位置
poco("star_single").focus([-0.5,0.5]).click()
3）Poco的异常模块¶
在这里我们可以看到Poco相关的一些异常模块：
我们在编写脚本的过程中，最常遇到的报错应该是 PocoNoSuchNodeException 和 PocoTargetTimeout了。
PocoNoSuchNodeException 是找不到控件的报错，大概有以下几种情况：
- 控件不存在于当前页面内
- 控件定位脚本编写错误，无法定位到目标控件
而PocoTargetTimeout常见于使用wait等待控件出现，一直没等到而出现的超时报错。
4. 不同平台如何实例化Poco对象¶
我们可以在这里找到绝大部分平台，实例化Poco对象的示例：
# unity项目的poco初始化
# import unity poco driver from this path
from poco.drivers.unity3d import UnityPoco
# then initialize the poco instance in the following way
poco = UnityPoco()
# android项目的poco初始化
from poco.drivers.android.uiautomation import AndroidUiautomationPoco
poco = AndroidUiautomationPoco()
更重要的是，这里还给出了多设备初始化Poco的案例，同学们可以详细查看下：
5. 在不同平台嵌入Poco-SDK¶
在Poco API文档的这部分内容，给我们提供了各种游戏引擎接入Poco-SDK的详细教程，同学们可以在这里找到对应引擎的接入教程，来使用我们的Poco框架：
