【Poco框架】实例API详解

class Poco(agent,**options)

• agent：Poco与目标通信agent对象设备
• options：
  • action_interval：等待在设备上执行的动作(如触摸或滑动)完成以及UI变得静止(稳定)的时间间隔。缺省值是0.8秒
  • poll_interval：每个轮询事件之间所需的最小时间(例如等待UI元素出现在屏幕上)。轮询是定期进行的。
  • pre_action_wait_for_appearance：在执行动作(如单击或滑动)之前等待的时间间隔。如果目标UI元素在此时间间隔后没有出现在屏幕上，则会引发PocoNoSuchNodeException。
  • touch_down_duration：上次单击操作的触屏步长。如果提供了此参数，则该值将设置为self.agent.input模块。注意，并非所有poco实现都支持此参数。如果不支持，您可能会看到警告。
  • reevaluate_volatile_attrbutes：检索易失性属性时，重新选择目标UI代理。使用hrpc连接的Poco驱动应该默认为False，因为hrpc总是远程重新评估属性。这个选项对于StdPoco驱动程序很有用，应该由StdPoco处理。

call(name=None,**kw)

调用Poco实例按查询表达式选择UI元素。查询表达式可以包含特定的名称和/或其他属性。即使设置了" visible=False "参数，不可见的UI元素也会被跳过。
选择过程不会立即执行，查询表达式存储在UI代理中，只有在需要UI元素信息时才执行选择(例如获取要单击的点坐标和/或检索特定属性值)。
实际案例：

// 此示例显示选择名为'close'的Button
poco = Poco(...)
close_btn = poco('close',type='Button')

---

• 参数：name(str)-要选择的UI元素的名称。
• 关键字参数：
  • xx-任意键值对，表示选择与UI.xx值匹配的UI
  • xxMatches(str)-表示选择与正则表达式模式UI.xx匹配的UI的任意键值对

poco = Poco(...)
arb_close_btn = poco(textMatches='^close.*$')

• 返回：表示与给定查询表达式匹配的UI元素的UI代理对象。
• 返回类型：UIObjectProxy

add_post_action_callback(cb)

注册一个回调函数，以便在每次操作（例如触摸或滑动）后调用。要传递的参数与add_pre_action_callback中的回调函数相同。

• 参数：cb-回调函数

add_pre_action_callback(cb)

注册一个回调函数，以便在每个动作(如触摸或滑动)之前调用。

• 参数：
  • action(str):动作的名称或标记
  • proxy(UIobjectProxy or NoneType)：相关的UI代理，它涉及到动作本身
  • args(tuple)：特定动作函数的所有必需参数

agent

用于访问poco代理实例的只读属性。

• 返回：poco代理实例
• 返回类型：poco.agentPocoAgent

apply_motion_tracks(tracks,accuracy=0.004)

类似于单击，但按屏幕给定的时间间隔，然后释放
（tracks:轨道，accuracy:精度）

• 参数：
  • tracks(list)-poco.utils.track.MotionTrack对象列表
  • accuracy(float)-归一化坐标度量中的每个运动步长的运动精度

click(pos)

执行点击（触摸、轻击等）在给定坐标处对目标设备的动作。
坐标（x，y）是2-列表或2-元组。x和y的坐标值必须在 0 ~ 1之间的间隔表示屏幕的百分比。例如，坐标[0.5, 0.5] 坐标[0, 0]表示屏幕的中心，坐标undefined表示左上角。
实际案例
单击分辨率为(100, 100)的屏幕(1920, 1080)的点：

poco.click([100.0/1920,100.0/1080])

• 参数：
  • pos（list(float, float) / tuple(float, float)）-坐标（x，y）在0到1的范围内
  • Raises：InvalidOperationException -在屏幕外点击时

freeze()

快照当前层次结构并将其缓存到新的poco实例中。这个新的poco实例是从 当前poco实例（self）。新的poco实例的层次结构是固定且不可变的。会的 从冻结的poco调用dump函数时超快。请参见下面的示例。
实际案例

poco = Poco(...)
frozen_poco = poco.freeze()
hierarchy_dict = frozen_poco.agent.hierarchy.dump() 
# 将返回已经缓存的层次结构数据

• 返回：从当前poco实例复制新的poco实例（self）
• 返回类型：poco

get_screen_size()

获取目标设备屏幕的真实物理分辨率。
返回：表示屏幕物理分辨率的浮点数，以像素为单位
返回类型：tuple元组

long_click(pos,duration=2.0)

类似于单击但按屏幕给定的时间间隔，然后释放。

• 参数：
  • pos(2-list/2-tuple)-坐标(x,y)，范围从0到1
  • duration-按下屏幕的持续时间

pinch(direction=‘in’, percent=0.6, duration=2.0, dead_zone=0.1)

在整个屏幕上挤压或扩展两个手指。

• 参数：
  • direction(str)-(方向)夹紧方向，仅限“进”或“出”。“进”表示挤压，“出”表示扩张
  • percent(float)-(百分比)整个屏幕的挤压范围或扩展范围
  • duration(float)-(持续时间)执行动作的时间间隔
  • dead_zone(float)-挤压内圈半径。不应大于percent

scroll(direction=‘vertical’,percent=0.6,duration=2.0)

从整个屏幕的下部滚动到上部。

• 参数：
  • direction(str)-滚动方向，“垂直”还是“水平”
  • percent(float)-整个屏幕高度或宽度的滚动距离百分比方向
  • duration(float)-执行动作的时间间隔

sleep_for_polling_interval()

在每个轮询事件后休眠固定的秒数。 无需手动调用此方法。它会在需要时自动调用。

snapshot(width=720)

从目标设备获取屏幕截图。支持的输出格式（png，jpg等）取决于代理人实施。

• 参数：
  • width(int)-屏幕截图的预期宽度。真实的大小取决于代理实现
  • 可能无法获得屏幕截图的预期宽度
• 返回：
  • screen_shot(str/bytes)：base64编码截图数据；
  • format(str)：输出格式’png’、’ jpg’等
• 返回类型：2-tuple二元组

start_gesture(pos)

开始一个手势动作。该方法将返回能够生成分解手势步骤的PendingGestureAction对象。你可以调用 .to和.hold在一个链中的任何时间。
实际案例

poco = Poco(...)
# 从屏幕中心移动到(0.6w, 0.6h)并保持1秒
# 然后回到中心
poco.start_gesture([0.5, 0.5]).to([0.6, 0.6]).hold(1).to([0.5, 0.5]).up()

• 参数：pos-归一化坐标系的起始坐标
• 返回：用于构建序列化的对象手势动作
• 返回类型：PendingGestureAction

swipe(p1,p2=None,direction=None,duration=2.0)

在目标设备上执行由起点和终点或方向矢量给出的点到点的滑动操作。必须提供至少一个终点或方向。
点的坐标(x, y)定义与click事件相同。方向矢量(x, y)的分量也表示为屏幕从0到1的范围。

实际案例
以下示例显示了如何在屏幕上执行从（100，100）到（100，200）的滑动操作 分辨率1920x1080：

poco.swipe([100.0 / 1920, 100.0 / 1080], [100.0 / 1920, 200.0 / 1080])

• 参数：
  • p1(2-list/2-tuple)-起点
  • p2-端点
  • direction -滑动方向
  • duration(float)-执行滑动动作的时间间隔
• Raises：InvalidOperationException -当滑动动作的起始点位于屏幕外时

use_render_resolution(use=True, resolution=None)

是否使用渲染分辨率。

• 参数：
  • use -True或False
  • resolution -纵向模式下的渲染分辨率，offset_x，offset_y，offset_width，offset_height，（0，10，1080，1820）

wait_for_all(objects,timeout=120)

等待，直到所有给定的UI代理在超时之前出现。所有UI代理将定期轮询。

• 参数：
  • objects(IterableUIObjectProxy)-给定UI的可迭代对象代理
  • timeout(float)-超时时间，单位为秒，默认为120s
• Raises：PocoTargetTimeout-超时前未出现所有UI代理

wait_for_any(objects, timeout=120)

等待，直到任何给定的UI代理在超时之前出现，并返回第一个出现的UI代理。所有UI代理将定期轮询。

• 参数：
  • objects(IterableUIObjectProxy)-给定UI的可迭代对象代理
  • timeout(float)-超时时间，单位为秒，默认为120s
• 返回：第一个出现的UI代理
• 返回类型：UIObjectProxy
• Raises：PocoTargetTimeout -在超时之前没有UI代理出现时

wait_stable()

休眠固定的秒数，以便等待UI变得静止(稳定)。不需要手动调用此方法。它在需要时自动调用。