ha4t.api module

此模块包含UI自动化操作接口 提供操作如：点击、滑动、输入、OCR识别等

click(*args, duration: float = 0.1, **kwargs) → None

点击操作，支持多种定位方式 用法：

Example:

>>> click((100,100))  # 坐标点击
>>> click("TEXT")  # 文字点击, OCR识别
>>> click(image="path/to/image.png")  # 图像匹配点击
>>> click(**kwargs)  # uiautomator2/wda的点击（适合原生app，速度快，非H5应用建议使用）

exists(*args, **kwargs) → bool

判断元素是否存在 :param args: 可变参数，用于不同的定位方式 :param kwargs: 关键字参数，用于uiautomator2/wda的定位 :return: 元素是否存在

Example:

>>> exists((100,100))  # 坐标点击
>>> exists("TEXT")  # 文字点击, OCR识别
>>> exists(image="path/to/image.png")  # 图像匹配点击
>>> exists(**kwargs)  # uiautomator2/wda的点击（适合原生app，速度快，非H5应用建议使用）

wait(*args, timeout: float = 5, reverse: bool = False, raise_error: bool = True, use_in_text: bool = False, **kwargs)

等待元素出现，支持多种定位方式 用法： 1. wait("TEXT") # 文字等待, OCR识别 2. web等待 3. uiautomator2/wda的等待（适合原生app，速度快，非H5应用建议使用） :param use_in_text: 是否在文本中使用 :param raise_error: 是否抛出错误 :param reverse: 反向等待 :param args: 可变参数，用于不同的定位方式 :param timeout: 等待超时时间，默认为CF.FIND_TIMEOUT :param kwargs: 关键字参数，用于uiautomator2/wda的定位 :return: 元素是否出现

Example:

>>> wait("TEXT")  # 文字等待, OCR识别
>>> wait(image="path/to/image.png")  # 图像匹配等待
>>> wait(**kwargs)  # uiautomator2/wda的等待（适合原生app，速度快，非H5应用建议使用）

swipe(p1, p2, duration=None, steps=None)

uiautomator2/wda的滑动操作 :param p1: 起始位置，(x, y)坐标或比例 :param p2: 结束位置，(x, y)坐标或比例 :param duration: 滑动持续时间 :param steps: 滑动步数，1步约5ms，如果设置则忽略duration

Example:

>>> swipe((0.5, 0.8), (0.5, 0.3))  # 从中间向上滑动
>>> swipe((0.2, 0.5), (0.8, 0.5), duration=0.5)  # 从左向右滑动

get_page_text() → str

OCR识别页面文字，返回当前页面所有文字的拼接字符串 可用于断言

返回:

页面上的所有文字拼接成的字符串

swipe_up(duration: float = 0.2, steps: int | None = None) → None

向上滑动

参数:

• duration -- 滑动持续时间

• steps -- 滑动步数

Example:

>>> swipe_up()  # 默认持续时间向上滑动
>>> swipe_up(duration=0.5, steps=10)  # 自定义持续时间和步数向上滑动

swipe_down(duration: float = 0.2, steps: int | None = None) → None

向下滑动

参数:

• duration -- 滑动持续时间

• steps -- 滑动步数

Example:

>>> swipe_down()  # 默认持续时间向下滑动
>>> swipe_down(duration=0.5, steps=10)  # 自定义持续时间和步数向下滑动

swipe_left(duration: float = 0.1, steps: int | None = None) → None

向左滑动

参数:

• duration -- 滑动持续时间

• steps -- 滑动步数

Example:

>>> swipe_left()  # 默认持续时间向左滑动
>>> swipe_left(duration=0.5, steps=10)  # 自定义持续时间和步数向左滑动

swipe_right(duration: float = 0.1, steps: int | None = None) → None

向右滑动

参数:

• duration -- 滑动持续时间

• steps -- 滑动步数

Example:

>>> swipe_right()  # 默认持续时间向右滑动
>>> swipe_right(duration=0.5, steps=10)  # 自定义持续时间和步数向右滑动

screenshot(filename: str | None = None) → <MagicMock name='mock.Image.Image' id='140435942194976'>

截图并可选保存到本地

参数:

filename -- 保存截图的文件名，如果为None则不保存

返回:

截图的PIL.Image对象

Example:

>>> img = screenshot()  # 截图并不保存
>>> screenshot("screenshot.png")  # 截图并保存为文件

popup_apps() → None

上划弹起应用列表 注意：此方法在部分手机上可能无法使用

Example:

>>> popup_apps()  # 弹起应用列表

home() → None

返回桌面

Example:

>>> home()  # 返回主屏幕

pull_file(src_path: List[str] | str, filename: str) → None

从app本地路径下载文件到本地

参数:

• src_path -- 路径列表或字符串，ios为Documents/xxx，android为/data/data/xxx/files/xxx

• filename -- 本地文件名

Example:

>>> pull_file("Documents/file.txt", "local_file.txt")  # 从app下载文件

upload_files(src_path: str) → None

上传文件或文件夹到设备

参数:

src_path -- 源文件或文件夹路径，可以是列表或字符串

抛出:

Exception -- 如果上传过程中出现错误

Example:

>>> upload_files("local_file.txt")  # 上传单个文件
>>> upload_files("my_folder")  # 上传文件夹

delete_file(file_path: List[str] | str) → None

删除设备上的文件或文件夹

参数:

file_path -- 要删除的文件或文件夹路径，可以是列表或字符串

抛出:

Exception -- 如果删除过程中出现错误

Example:

>>> delete_file("Documents/file.txt")  # 删除单个文件
>>> delete_file(["Documents", "my_folder"])  # 删除文件夹

clear_app(app_name: str = None)

清除应用数据 > 仅支持Android平台 :param app_name: 应用名称 :Example:

>>> clear_app("com.example.app")  # 清除应用数据

返回:

start_app(app_name: str | None = '', activity: str | None = '') → None

启动应用程序

参数:

• app_name -- 应用程序名称，如果为None则使用配置中的默认值

• activity -- Android应用的活动名称，如果为None则使用配置中的默认值

抛出:

ValueError -- 如果是Android平台且activity为None

Example:

>>> start_app("com.example.app")  # 启动指定应用

get_current_app() → str

获取当前运行的应用名称

返回:

应用bundleId 或 package name

Example:

>>> get_current_app()  # 获取当前运行的应用名称

restart_app(app_name: str | None = '', activity: str | None = '') → None

重启应用程序并更新CDP连接

Example:

>>> restart_app()  # 重启当前应用

key(key_name: str) → None

模拟系统按键，多端兼容 :param key_name: 按键名称，如 home, back, menu, volume_up 等 :Example:

>>> key("home")  # 主页键
>>> key("back")  # 返回键

double_click(*args, interval: float = 0.05, **kwargs) → None

双击元素，通过两次连续点击实现 :param args: 定位参数（同 click），支持坐标/OCR文字/图像/u2属性 :param interval: 两次点击间隔（秒），默认0.05 :param kwargs: 定位参数（同 click）

Example:

>>> double_click(text="确定")  # 双击"确定"按钮
>>> double_click((500, 300), interval=0.1)  # 双击坐标点

long_press(*args, duration: float = 1.0, **kwargs) → None

长按元素 :param args: 定位参数（同 click） :param duration: 按压持续时间（秒），默认1.0 :param kwargs: 定位参数（同 click）

Example:

>>> long_press(text="图标", duration=2.0)  # 长按图标2秒

drag(*args, dx: int = 0, dy: int = 0, duration: float = 0.5, **kwargs) → None

拖拽元素（从元素位置偏移dx, dy） 仅支持通过 u2/wda 属性定位的元素（kwargs方式）

参数:

• args -- 暂不支持通过args定位的拖拽

• dx -- X轴偏移像素（正数向右）

• dy -- Y轴偏移像素（正数向下）

• duration -- 拖拽持续时间（秒）

• kwargs -- u2/wda属性定位

Example:

>>> drag(text="滑块", dx=200, dy=0)  # 将滑块向右拖动200像素

get_text(*args, **kwargs) → str

获取元素的文本内容（用于断言前的值提取） :param args: 定位参数 :param kwargs: u2/wda属性定位

返回:

元素的文本字符串

Example:

>>> get_text(text="用户名")  # 获取元素的文本

assert_element(*args, operator: str = 'eq', expected=None, extract: str = 'text', raise_error: bool = True, **kwargs) → bool

元素断言 :param args: 定位参数 :param operator: 算子

• eq / ne: 文本等于/不等于期望值

• contains / not_contains: 文本包含/不包含

• empty / not_empty: 文本为空/不为空

• regex: 正则匹配

参数:

• expected -- 期望值（eq/ne/contains/not_contains/regex 时需要）

• extract -- 断言提取方式 - text: 获取文本后进行断言（默认） - exists: 判断元素存在性

• raise_error -- 断言失败时是否抛出 AssertionError，默认 True

• kwargs -- u2/wda属性定位

返回:

断言是否通过

抛出:

AssertionError -- 当断言失败且 raise_error=True 时抛出

Example:

>>> assert_element(text="登录", operator="eq", expected="登录")  # 文本等于
>>> assert_element(text="提示", operator="contains", expected="成功")  # 文本包含
>>> assert_element(text="加载中", operator="exists", extract="exists")  # 判断存在
>>> assert_element(text="加载中", operator="not_empty", extract="text")  # 文本不为空
>>> assert_element(text="加载中", operator="eq", expected="完成", raise_error=False)  # 不抛异常