Skip to content

1. 基本功能

Jump to bottom
Aues6uen11Z edited this page Oct 25, 2024 · 1 revision

Zafkiel的大部分功能来源于Airtest，建议简单了解一下airtest.core.api，下面将介绍其中与Airtest不一样的部分。

app_is_running

函数签名

def app_is_running() -> bool:

功能：检查应用程序是否正在运行

返回值：返回应用程序是否正在运行的布尔值

支持平台：Windows

screenshot

函数签名

def screenshot():

功能：获取设备屏幕截图

返回值：返回截图图像

支持平台：Android, Windows, iOS

touch

函数签名

def touch(
    v: Union[Template, Tuple[int, int]],
    times: int = 1,
    interval: float = 0.05,
    blind: bool = False,
    ocr_mode: int = 0,
    cls: Type[Ocr] = Ocr,
    local_search: bool = True,
    v_name: str = None,
    **kwargs
) -> Tuple[int, int]:

功能：在设备屏幕上执行触摸/点击动作

参数

  • v: 目标对象，可以是Template实例或绝对坐标(x, y)。
  • times: 要执行的点击次数，默认为1次。
  • interval: 两次点击之间的时间间隔，默认为0.05秒。
  • blind: 是否识别模板，有时候我们只需要点击而不关心图像。
  • ocr_mode: OCR匹配规则，默认为0，可选值有OCR_EQUAL(0), OCR_CONTAINS(1), OCR_SIMILAR(2)。
  • cls: "Ocr"类或其子类，默认为Ocr。
  • local_search: 如果为True，则仅在屏幕相应位置搜索模板图像；否则，在整个屏幕上搜索。
  • v_name: 当v是坐标，但需要一个名字时使用。
  • **kwargs: 平台特定的关键字参数，请参考对应文档。

返回值：返回最终点击的位置坐标，例如 (100, 100)。

支持平台：Android, Windows, iOS

示例

  • 点击绝对坐标：

    touch((100, 100))

  • 连续点击2次：

    touch((100, 100), times=2)

  • 在Android和Windows平台上设置点击持续时间：

    touch((100, 100), duration=2)

  • 在Windows上右键点击：

    touch((100, 100), right_click=True)

find_click

函数签名

def find_click(
    rec_template: Template,
    touch_template: Optional[Template] = None,
    times: int = 1,
    interval: float = 0.05,
    timeout: float = 1,
    blind: bool = False,
    ocr_mode: int = 0,
    cls: Type[Ocr] = Ocr,
    local_search: bool = True
) -> bool:

功能：查找模板图像并点击它或另一个模板图像区域

参数

  • rec_template: 要查找的Template实例。
  • touch_template: 要点击的Template实例，默认为None，意味着点击rec_template。
  • times: 要执行的点击次数，默认为1次。
  • interval: 两次点击之间的时间间隔，默认为0.05秒。
  • timeout: 查找匹配的最大用时，默认为1秒。
  • blind: 是否识别模板，与touch()中的参数相同。
  • ocr_mode: OCR匹配规则，默认为0，可选值有OCR_EQUAL, OCR_CONTAINS, OCR_SIMILAR。
  • cls: "Ocr"类或其子类，默认为Ocr。
  • local_search: 如果为True，则仅在屏幕相应位置搜索模板图像；否则，在整个屏幕上搜索。

返回值：返回目标图像是否出现并被点击

支持平台：Android, Windows, iOS

exists

函数签名

def exists(
    v: Template,
    timeout: float = 0,
    ocr_mode: int = 0,
    cls: Type[Ocr] = Ocr,
    local_search: bool = True
) -> Union[bool, Tuple[int, int]]:

功能：检查给定的目标是否存在于设备屏幕上

参数

  • v: 要检查的目标。
  • timeout: 时间限制，默认为0，意味着loop_find只会搜索一次。
  • ocr_mode: OCR匹配规则，默认为0，可选值有OCR_EQUAL, OCR_CONTAINS, OCR_SIMILAR。
  • cls: "Ocr"类或其子类，默认为Ocr。
  • local_search: 如果为True，则仅在屏幕相应位置搜索模板图像；否则，在整个屏幕上搜索。

返回值：如果未找到目标则返回False，否则返回目标的坐标

支持平台：Android, Windows, iOS

示例

if exists(Template(r"tpl1606822430589.png")):
    touch(Template(r"tpl1606822430589.png"))

# 由于`exists()`会返回坐标，
# 我们可以直接点击这个返回值以减少一次图像搜索：

pos = exists(Template(r"tpl1606822430589.png"))
if pos:
    touch(pos)

wait

函数签名

def wait(
    v: Template,
    timeout: Optional[float] = None,
    interval: float = 0.3,
    interval_func: Optional[Callable] = None,
    ocr_mode: int = 0,
    cls: Type[Ocr] = Ocr,
    local_search: bool = True
) -> Tuple[int, int]:

功能：等待在设备屏幕上匹配模板出现

参数

  • v: 要等待的目标对象，Template实例。
  • timeout: 匹配的时间间隔，默认为None，值为ST.FIND_TIMEOUT。
  • interval: 尝试查找匹配的时间间隔（秒）。
  • interval_func: 每次尝试查找目标失败后调用的回调函数。
  • ocr_mode: OCR匹配规则，默认为0，可选值有OCR_EQUAL, OCR_CONTAINS, OCR_SIMILAR。
  • cls: "Ocr"类或其子类，默认为Ocr。
  • local_search: 如果为True，则仅在屏幕相应位置搜索模板图像；否则，在整个屏幕上搜索。

异常

  • TargetNotFoundError: 如果超时后未找到目标则抛出此异常。

返回值：返回匹配目标的坐标

支持平台：Android, Windows, iOS

示例

wait(Template(r"tpl1606821804906.png"))  # 超时时间为ST.FIND_TIMEOUT
# 每3秒查找一次模板，超时时间为120秒
wait(Template(r"tpl1606821804906.png"), timeout=120, interval=3)

# 可以指定每次查找目标失败时的回调函数：
def notfound():
    print("No target found")
wait(Template(r"tpl1607510661400.png"), interval_func=notfound)

swipe

函数签名

def swipe(
    v1: Union[Template, Tuple[int, int]],
    v2: Optional[Union[Template, Tuple[int, int]]] = None,
    vector: Optional[Tuple[float, float]] = None,
    blind1: bool = False,
    blind2: bool = False,
    **kwargs
) -> Tuple[Tuple[int, int], Tuple[int, int]]:

功能：在设备屏幕上执行滑动操作

参数

  • v1: 滑动的起点，可以是Template实例或绝对坐标(x, y)。
  • v2: 滑动的终点，可以是Template实例或绝对坐标(x, y)，默认为None。
  • vector: 滑动动作的向量坐标，可以是绝对坐标(x, y)或屏幕百分比如(0.5, 0.5)，默认为None。
  • blind1: 是否识别Template1，与touch()中的参数相同，默认为False。
  • blind2: 是否识别Template2，与touch()中的参数相同，默认为False。
  • **kwargs: 平台特定的关键字参数，请参考对应文档。

异常

  • ScriptError：当没有提供足够的参数来执行滑动操作时引发。

返回值：返回起始位置和目标位置

支持平台：Android, Windows, iOS

示例

  • 根据向量滑动：

    swipe(Template(r"tpl1606814865574.png"), vector=(-0.0316, -0.3311))

  • 在两个坐标点间滑动：

    swipe((100, 100), (200, 200))

  • 自定义滑动持续时间和步骤数（Android 和 iOS）：

    # 滑动持续1秒，分为6步
swipe((100, 100), (200, 200), duration=1, steps=6)
Clone this wiki locally