Poco实例(全局操作) API汇总
上期回顾：Poco UI对象 API汇总
2024.2.25更新：poco1.0.92补充了double_click()接口、新增poco.dump()接口；poco1.0.94新增poco.sendMessage()和poco.invoke()接口
以下基于
python3.8；airtestIDE1.2.13；airtest1.2.4；pocoui1.0.85
注意：Poco框架和Airtest框架很多API是同名的，但使用方法完全不一样！！！一定不要搞混了，我初学时也经常搞混，这点一定要注意！
具体Poco框架和Airtest框架是什么关系，可以看之前文章：Airtest Project——UI自动化利器介绍
上期讲了Poco UI对象(UIObjectProxy实例) 都有哪些API可以用；今天讲一下Poco实例都有哪些API。
新人刚开始一定会混淆这两个概念。Poco实例是我们写脚本时一开始定义的Poco对象，如
# Poco的Unity实例
# 源码：your_python_path\site-packages\poco\drivers\unity3d\unity3d_poco.py
poco = UnityPoco()
# Poco的安卓实例
# 源码：your_python_path\site-packages\poco\drivers\android\uiautomation.py
poco = AndroidUiautomationPoco(use_airtest_input=True, screenshot_each_action=False)
此时刚定义好poco，还没有定位具体的元素，不过此时也是可以用poco来操作设备的，Airtest官方将此时可以进行的操作，叫"全局操作"，即此时使用poco操作是针对整个设备屏幕的；而用poco定位之后返回的是具体的UI对象(UIObjectProxy实例)，这时候再操作就是针对这个元素了。
我们以click为例看看两者的实操区别：
# Poco的Unity实例
poco = UnityPoco()
# 因为还没有具体定位到元素，此时用poco只能进行全局操作，所以此时只能通过坐标来点击
# poco框架的坐标全是相对坐标，airtest框架的坐标全是绝对坐标，切记，不要混了！
poco.click([0.5,0.5])
# 定位到文本是"测试工程师小站"的按钮
button = poco(text="测试工程师小站")
# 此时已经定位到具体元素，可以直接点击，不用再给坐标了
button.click()
相对坐标可以通过AirtestIDE获取，之前文章 AirtestIDE基本功能(二) 中的设置部分有介绍
UnityPoco、AndroidUiautomationPoco等各类具体的Poco都是继承自Poco类，实际的API定义也都是在Poco类中，其源码在：
your_python_path\site-packages\poco\pocofw.py
1.wait_for_any(objects, timeout=120)
等待给定元素列表中任一元素出现，并返回该元素
参数：
objects - 元素列表
timeout - 等待时间
返回：
出现的UIObjectProxy实例
异常：
PocoTargetTimeout:等待元素超时
示例：
from airtest.core.api import *
from poco.drivers.android.uiautomation import AndroidUiautomationPoco
from poco.drivers.unity3d import UnityPoco
auto_setup(__file__)
# 或是poco = UnityPoco()
poco = AndroidUiautomationPoco(use_airtest_input=True, screenshot_each_action=False)
ui1 = poco(text="测试工程师小站")
ui2 = poco(name="测试工程师小站")
# 等待ui1,ui2中任一一个元素，先等到哪个元素就返回哪个元素；如果60秒都没等到两者，则报错PocoTargetTimeout
ui = poco.wait_for_any([ui1, ui2], 60)
ui.click()
2.wait_for_all(objects, timeout=120)
等待所有元素出现
参数：
objects - 元素列表
timeout - 等待时间
返回：
None
异常：
PocoTargetTimeout:等待元素超时
示例：
ui1 = poco(text="测试工程师小站")
ui2 = poco(name="测试工程师小站")
# 等待ui1,ui2全部出现，如都出现代码继续往下走；如果120秒有至少1个没出现，则报错PocoTargetTimeout
poco.wait_for_all([ui1, ui2])
3.freeze()
冻结UI，即将当前hierarchy(UI树)复制一份，不保证与手机实时屏幕一致，但操作非常快速。
返回：
新的poco实例(定格的)
示例：
poco = UnityPoco()
# 如当前界面有几十个多选框我们要遍历点击，常规操作会很慢，每个元素都要去UI树中查找
for item in poco('xxx'):
item.click()
# 通过冻结的方式，可以提高约10倍速度
with poco.freeze() as frozen_poco:
for item in frozen_poco('xxx'):
item.click()
4.click(pos)
点击
参数：
pos - 相对坐标，如[0.5,0.5]
异常：
InvalidOperationException: 坐标在屏幕以外时报错
示例：
poco.click([0.5,0.5])
5.swipe(p1, p2=None, direction=None, duration=2.0)
滑动
参数：
p1 - 起点
p2 - 终点
direction - 滑动向量，如[0.1,0.1]，从起始点向右10%向下10%滑动。如屏幕为100*100，起始点为[0.5,0.5]，则是从绝对坐标(50,50)滑到(60,60)
duration - 滑动时长，默认2秒
异常：
InvalidOperationException: 坐标在屏幕以外时报错
示例：
# 从中心向右滑，滑动时长2秒
poco().swipe([0.5,0.5], [0.9,0.5])
# 从中心向左上滑动(左上屏幕宽10%长10%距离的那个点)，滑动过程持续3秒
# p2和direction只需有1个，都存在时取p2
poco().swipe([0.5,0.5], direction=[-0.1,-0.1], duration=3)
6.long_click(pos, duration=2.0)
长按
参数：
pos - 相对坐标，如[0.5,0.5]
duration - 长按时长，默认2秒
异常：
InvalidOperationException: 坐标在屏幕以外时报错
示例：
poco.long_click([0.5,0.5])
7.scroll(direction='vertical', percent=0.6, duration=2.0)
在屏幕上滚动。
参数：
direction - 滚动方向，"vertical" or "horizontal"，默认'vertical'
percent - 滚动距离，该距离是相对于屏幕的高或宽的比例，默认0.6
duration - 滚动时长，默认2秒
示例：
poco().scroll() # 向下垂直滚动0.6的比例，持续2秒
poco().scroll(direction='vertical', percent=-0.6) # 向上垂直滚动0.6的比例，持续2秒
poco().scroll('horizontal', 0.3, 1) # 向右横向滚动0.3的比例，持续1秒
8.pinch(direction='in', percent=0.6, duration=2.0, dead_zone=0.1)
缩放
参数：
direction - "in"缩 or "out"放，默认"in"
percent - 缩放距离，该距离是相对于此元素的比例，默认0.6
duration - 缩放时长，默认2秒
dead_zone - 缩放内圈半径，不能大于percent，默认0.1
示例：
poco().pinch() # 向里缩小
poco().pinch("out") # 向外放大
9.start_gesture(pos )
滑动手势。可用于解锁等复杂手势操作。
参数：
pos - 起点
返回：
PendingGestureAction实例
示例：
# 滑一个对勾形状
poco.start_gesture([0.5, 0.5]).hold(1).to([0.6, 0.6]).hold(1).to([0.7, 0.5]).up()
10.get_screen_size()
获取设备物理分辨率
示例：
poco.get_screen_size()
11.use_render_resolution()
使用渲染分辨率。如有的游戏会有黑边，或者有的手机虚拟按钮会占用屏幕位置，就会导致手机屏幕分辨率和实际渲染分辨率不一样，直接影响就是点击会点偏，这种情况下需要使用渲染分辨率。
示例：
poco.use_render_resolution()12.double_click(focus=None, sleep_interval=None)
双击。Poco1.0.92新增
参数：
focus - 元素相对坐标，如[0.1,0.1]，指元素长、宽各10%的位置，即左上角，取值范围0~1
sleep_interval - 休息间隔
异常：
PocoNoSuchNodeException:元素不存在
13.dump()
Poco1.0.92新增poco.dump() 接口，效果等同于之前的poco.agent.hierarchy.dump()接口，让调用更简单
14.poco.sendMessage()和poco.invoke()
Poco1.0.94新增poco.sendMessage()和poco.invoke()接口，用于向游戏内SDK发送消息，或处理带有自定义参数调用的函数，这样脚本即可和游戏内部直接交互而不通过UI操作。
详情请见代码 https://github.com/AirtestProject/Poco/pull/607 和文档说明：https://poco-chinese.readthedocs.io/en/latest/source/doc/drivers/unity3d.html#integrating-and-using-poco-interface-functions-in-unity 。
---------------------------------------------------------------------------------
关注微信公众号即可在手机上查阅，并可接收更多测试分享~
浙公网安备 33010602011771号