Aibote(python)使用须知

Aibote是江西爱伯特科技自主研发的一款纯代码RPA办公自动化框架，支持Android、Browser和Windows 三大平台。框架免费、API和接口协议开源，个人、企业商用零费用
以socket tcp接口协议通信方式命令驱动，支持任何一门计算机语言调用。OEM或特殊接口定制等商业合作联系QQ：1600381943

Aibote python是由 AiBot.py模块作者:河畔(810975099)制作而成，提供给python开发者调用
python版本是基于aibote底层api开源协议制作而成，封装格式以node.js为向导，涵盖aibote自动化平台所有功能。

拾取元素工具使用方法

Android 工具位置，Aibote/Aibote.exe->菜单项->脚本工具
Windows 工具位置，Aibote/WindowsTool.exe

Android 元素拾取工具，需要在手机端，勾选连接工具端选项

Windows 元素拾取工具，按下CTRL键，暂停拾取。支持鼠标左键/中键拾取

使用方法：
1、点击"+"按钮 单击手机投屏/windows 窗口，拾取元素和颜色信息。单击目标点会在右和下扩增20个像素点，用作放大目标位置。 再点击预览图片控件可拾取放大后 点的颜色值和坐标

2、点击"+"按钮 在手机投屏/windows 窗口滑动矩形大小，拾取元素和图片信息。截图前输入图片名称。Android端，图片保存在手机/storage/emulated/0/Android/data/com.aibot.client/files/
（根目录：/storage/emulated/0/）。Windows端，图片保存在指定路径目录，如果图片名称不包含路径，则默认保存在Aibote/Picture/windows

3、二值化阈值和最大值在0-255之间，阈值和最大值都为255时灰度化处理

4、BINARY算法，当前点值大于阈值thresh时，取最大值maxva，否则设置为0

5、BINARY_INV算法，当前点值大于阈值thresh时，设置为0，否则设置为最大值maxva

6、TOZERO算法，当前点值大于阈值thresh时，不改变，否则设置为0

7、TOZERO_INV算法，当前点值大于阈值thresh时，设置为0，否则不改变

8、TRUNC算法，当前点值大于阈值thresh时，设置为阈值thresh，否则不改变

9、ADAPTIVE_THRESH_MEAN_C算法，自适应阈值

10、ADAPTIVE_THRESH_GAUSSIAN_C算法，自适应阈值

Aibote.py 使用方法说明

下载安装 Aibote.py

pip install AiBot.py

使用 AndroidBot 编写脚本

# 1. 导入 AndroidBotMain 类
from AiBot import AndroidBotMain


# 2. 自定义一个脚本类，继承 AndroidBotMain
class CustomAndroidScript(AndroidBotMain):
    # 3. 设置等待参数
    # 3.1 设置等待时间
    wait_timeout = 3
    # 3.2 设置重试间隔时长
    interval_timeout = 0.5

    # 4. 设置日志等级
    log_level = "INFO"  # "DEBUG"

    # 5. 设置方法超时是否抛出异常
    raise_err = False  # True

    # 6. 重写方法，编写脚本
    # 注意：此方法是脚本执行入口
    def script_main(self):
        # 6.1 API 演示
        # 注意：Python 版本支持的 Api 与 Nodejs 基本相同
        # 教程中仅演示部分 Api，更多 Api 请自行探索，所有 Api 均包含详细的参数要求和返回值，请自行查看。

        # 截图
        self.save_screenshot("xxx.png")
        # 获取坐标点颜色
        self.get_color((100, 100))
        # 查找图片
        self.find_image("xxx.png")
        # 点击坐标
        self.click((100, 100))
        # 滑动
        self.swipe((100, 100), (200, 200), 3)


# 7. 执行脚本，Pycharm 中，直接右键执行
if __name__ == '__main__':
    # 注意：此处监听的端口号，必须和手机端的脚本端口号一致；
    # 监听 3333 号端口
    CustomAndroidScript.execute(3333)

教程中仅演示部分 Api，更多 Api 请自行探索，所有 Api 均包含详细的参数要求和返回值，请自行查看。

使用 WinBot 编写脚本

# 1. 导入 WinBotMain 类
from AiBot import WinBotMain


# 2. 自定义一个脚本类，继承 WinBotMain
class CustomWinScript(WinBotMain):
    # 3. 设置等待参数
    # 3.1 设置等待时间
    wait_timeout = 3
    # 3.2 设置重试间隔时长
    interval_timeout = 0.5

    # 4. 设置日志等级
    log_level = "INFO"  # "DEBUG"

    # 5. 设置方法超时是否抛出异常
    raise_err = False  # True

    # 6. 重写方法，编写脚本
    # 注意：此方法是脚本执行入口
    def script_main(self):
        # 6.1 API 演示
        # 注意：Python 版本支持的 Api 与 Nodejs 基本相同
        # 教程中仅演示部分 Api，更多 Api 请自行探索，所有 Api 均包含详细的参数要求和返回值，请自行查看。

        # 查询所有窗口句柄
        result = self.find_windows()
        print(result)  # ["1050010", "1050011", "1050012"]

        # 查询指定窗口句柄
        result = self.find_window(window_name="Ai-Bot 2群等9个会话")
        print(result)  # "1050010"


# 7. 执行脚本，Pycharm 中，直接右键执行
if __name__ == '__main__':
    # 启动脚本，监听 6666 号端口

    # local=True 时，是本地运行脚本，会自动启动 WindowsDriver.exe 驱动；
    # 在远端部署脚本时，请设置 local=False，手动启动 WindowsDriver.exe，启动 WindowsDriver.exe 时需指定远端 IP 或端口号；

    CustomWinScript.execute(6666, local=True)

教程中仅演示部分 Api，更多 Api 请自行探索，所有 Api 均包含详细的参数要求和返回值，请自行查看。

使用 WebBot 编写脚本

import time

# 1. 导入 WebBotMain 类
from AiBot import WebBotMain


# 2. 自定义一个脚本类，继承 WebBotMain
class CustomWebScript(WebBotMain):
    # 3. 设置等待参数
    # 3.1 设置等待时间
    wait_timeout = 3
    # 3.2 设置重试间隔时长
    interval_timeout = 0.5

    # 4. 设置日志等级
    log_level = "INFO"  # "DEBUG"

    # 5. 设置方法超时是否抛出异常
    raise_err = False  # True

    # 6. 重写方法，编写脚本
    # 注意：此方法是脚本执行入口
    def script_main(self):
        # 6. API 演示
        # 注意：Python 版本支持的 Api 与 Nodejs 基本相同
        # 教程中仅演示部分 Api，更多 Api 请自行探索，所有 Api 均包含详细的参数要求和返回值，请自行查看。

        self.goto("https://www.baidu.com")
        time.sleep(3)
        self.new_page("https://www.qq.com")
        time.sleep(3)

        result = self.execute_script('(()=>"aibote rpa")()')
        print(result)  # aibote rpa


# 7. 执行脚本，Pycharm 中，直接右键执行
if __name__ == '__main__':
    # 启动脚本，监听 9999 号端口
    # 默认使用 Chrome 浏览器

    # local=True 时，是本地运行脚本，会自动启动 WebDriver.exe 驱动；
    # 在远端部署脚本时，请设置 local=False，手动启动 WebDriver.exe，启动 WebDriver.exe 时需指定远端 IP 或端口号；

    # 如本地部署脚本，需要传递 WebDriver 启动参数时，参考下面方式，如不需传递启动参数，则忽略：
    driver_params = {
        "browserName": "chrome",
        "debugPort": 0,
        "userDataDir": "./UserData",
        "browserPath": None,
        "argument": None,
    }

    CustomWebScript.execute(9999, local=True, driver_params=driver_params)

教程中仅演示部分 Api，更多 Api 请自行探索，所有 Api 均包含详细的参数要求和返回值，请自行查看。

AndroidBot开发手册

图色

def save_screenshot(image_name: str, region: _Region = None, algorithm: _Algorithm = None) -> Optional[str]:
    """
    保存截图，返回图片地址(手机中)或者 None
    :param image_name: 图片名称，保存在手机 /storage/emulated/0/Android/data/com.aibot.client/files/ 路径下；
    :param region: 截图区域，默认全屏，``region = (起点x、起点y、终点x、终点y)``，得到一个矩形
    :param algorithm:
        处理截图所用算法和参数，默认保存原图，

        ``algorithm = (algorithm_type, threshold, max_val)``

        按元素顺序分别代表：

        0. ``algorithm_type`` 算法类型
        1. ``threshold`` 阈值
        2. ``max_val`` 最大值

        ``threshold`` 和 ``max_val`` 同为 255 时灰度处理.

        ``algorithm_type`` 算法类型说明:

        0. ``THRESH_BINARY``      算法，当前点值大于阈值 `threshold` 时，取最大值 ``max_val``，否则设置为 0；
        1. ``THRESH_BINARY_INV``  算法，当前点值大于阈值 `threshold` 时，设置为 0，否则设置为最大值 max_val；
        2. ``THRESH_TOZERO``      算法，当前点值大于阈值 `threshold` 时，不改变，否则设置为 0；
        3. ``THRESH_TOZERO_INV``  算法，当前点值大于阈值 ``threshold`` 时，设置为 0，否则不改变；
        4. ``THRESH_TRUNC``       算法，当前点值大于阈值 ``threshold`` 时，设置为阈值 ``threshold``，否则不改变；
        5. ``ADAPTIVE_THRESH_MEAN_C``      算法，自适应阈值；
        6. ``ADAPTIVE_THRESH_GAUSSIAN_C``  算法，自适应阈值；

    :return: 图片地址(手机中)或者 None
    """

def save_element_screenshot(image_name, xpath) -> Optional[str]:
    """
    保存元素截图
    :param image_name: 图片名称，保存在手机 /storage/emulated/0/Android/data/com.aibot.client/files/ 路径下
    :param xpath: xpath路径
    :return: 图片地址(手机中)或者 None
    """

def take_screenshot(region: _Region = None, algorithm: _Algorithm = None) -> Optional[bytes]:
    """
    保存截图，返回图像字节格式或者"null"的字节格式
    :param region: 截图区域，默认全屏，``region = (起点x、起点y、终点x、终点y)``，得到一个矩形
    :param algorithm:
        处理截图所用算法和参数，默认保存原图，

        ``algorithm = (algorithm_type, threshold, max_val)``

        按元素顺序分别代表：

        0. ``algorithm_type`` 算法类型
        1. ``threshold`` 阈值
        2. ``max_val`` 最大值

        ``threshold`` 和 ``max_val`` 同为 255 时灰度处理.

        ``algorithm_type`` 算法类型说明:

        0. ``THRESH_BINARY``      算法，当前点值大于阈值 `threshold` 时，取最大值 ``max_val``，否则设置为 0；
        1. ``THRESH_BINARY_INV``  算法，当前点值大于阈值 `threshold` 时，设置为 0，否则设置为最大值 max_val；
        2. ``THRESH_TOZERO``      算法，当前点值大于阈值 `threshold` 时，不改变，否则设置为 0；
        3. ``THRESH_TOZERO_INV``  算法，当前点值大于阈值 ``threshold`` 时，设置为 0，否则不改变；
        4. ``THRESH_TRUNC``       算法，当前点值大于阈值 ``threshold`` 时，设置为阈值 ``threshold``，否则不改变；
        5. ``ADAPTIVE_THRESH_MEAN_C``      算法，自适应阈值；
        6. ``ADAPTIVE_THRESH_GAUSSIAN_C``  算法，自适应阈值；

    :return: 图像字节格式或者"null"的字节格式
    """

def get_color(point: _Point_Tuple) -> Optional[str]:
    """
    获取指定坐标点的色值
    :param point: 坐标点
    :return: 色值字符串(例如: #008577)或者 None

    """

找图

def find_color(color: str, sub_colors: _SubColors = None, region: _Region = None, similarity: float = 0.9,
               wait_time: float = None, interval_time: float = None, raise_err: bool = None) -> Optional[_Point]:
    """
    获取指定色值的坐标点，返回坐标或者 None
    :param color: 颜色字符串，必须以 # 开头，例如：#008577；
    :param sub_colors: 辅助定位的其他颜色；
    :param region: 在指定区域内找色，默认全屏；
    :param similarity: 相似度，0-1 的浮点数，默认 0.9；
    :param wait_time: 等待时间，默认取 .wait_timeout；
    :param interval_time: 轮询间隔时间，默认取 .interval_timeout；
    :param raise_err: 超时是否抛出异常；
    :return:

    # 区域相关参数
    region = (0, 0, 0, 0) 按元素顺序分别代表：起点x、起点y、终点x、终点y，最终得到一个矩形。
    # 算法相关参数
    algorithm = (0, 0, 0) # 按元素顺序分别代表：algorithm_type 算法类型、threshold 阈值、max_val 最大值。
    threshold 和 max_val 同为 255 时灰度处理.
    0   THRESH_BINARY      算法，当前点值大于阈值 threshold 时，取最大值 max_val，否则设置为 0；
    1   THRESH_BINARY_INV  算法，当前点值大于阈值 threshold 时，设置为 0，否则设置为最大值 max_val；
    2   THRESH_TOZERO      算法，当前点值大于阈值 threshold 时，不改变，否则设置为 0；
    3   THRESH_TOZERO_INV  算法，当前点值大于阈值 threshold 时，设置为 0，否则不改变；
    4   THRESH_TRUNC       算法，当前点值大于阈值 threshold 时，设置为阈值 threshold，否则不改变；
    5   ADAPTIVE_THRESH_MEAN_C      算法，自适应阈值；
    6   ADAPTIVE_THRESH_GAUSSIAN_C  算法，自适应阈值；
    """

def find_image(image_name, region: _Region = None, algorithm: _Algorithm = None, similarity: float = 0.9,
               wait_time: float = None, interval_time: float = None, raise_err: bool = None) -> Optional[_Point]:
    """
    寻找图片坐标，在当前屏幕中寻找给定图片中心点的坐标，返回坐标或者 None
    :param image_name: 图片名称（手机中）；
    :param region: 从指定区域中找图，默认全屏；
    :param algorithm: 处理屏幕截图所用的算法，默认原图，注意：给定图片处理时所用的算法，应该和此方法的算法一致；
    :param similarity: 相似度，0-1 的浮点数，默认 0.9；
    :param wait_time: 等待时间，默认取 .wait_timeout；
    :param interval_time: 轮询间隔时间，默认取 .interval_timeout；
    :param raise_err: 超时是否抛出异常；
    :return:

    # 区域相关参数
    region = (0, 0, 0, 0) 按元素顺序分别代表：起点x、起点y、终点x、终点y，最终得到一个矩形。
    # 算法相关参数
    algorithm = (0, 0, 0) # 按元素顺序分别代表：algorithm_type 算法类型、threshold 阈值、max_val 最大值。
    threshold 和 max_val 同为 255 时灰度处理.
    0   THRESH_BINARY      算法，当前点值大于阈值 threshold 时，取最大值 max_val，否则设置为 0；
    1   THRESH_BINARY_INV  算法，当前点值大于阈值 threshold 时，设置为 0，否则设置为最大值 max_val；
    2   THRESH_TOZERO      算法，当前点值大于阈值 threshold 时，不改变，否则设置为 0；
    3   THRESH_TOZERO_INV  算法，当前点值大于阈值 threshold 时，设置为 0，否则不改变；
    4   THRESH_TRUNC       算法，当前点值大于阈值 threshold 时，设置为阈值 threshold，否则不改变；
    5   ADAPTIVE_THRESH_MEAN_C      算法，自适应阈值；
    6   ADAPTIVE_THRESH_GAUSSIAN_C  算法，自适应阈值；
    """

def find_images(image_name,region: _Region = None,algorithm: _Algorithm = None,similarity: float = 0.9,multi: int = 1,wait_time: float = None,interval_time: float = None,raise_err: bool = None) -> List[Point]:
    """
    寻找图片坐标，在当前屏幕中寻找给定图片中心点的坐标，返回坐标列表
    :param image_name: 图片名称（手机中）；
    :param region: 截图区域，默认全屏，``region = (起点x、起点y、终点x、终点y)``，得到一个矩形
    :param algorithm:
        处理屏幕截图所用的算法，默认原图，注意：给定图片处理时所用的算法，应该和此方法的算法一致；

        ``algorithm = (algorithm_type, threshold, max_val)``

        按元素顺序分别代表：

        0. ``algorithm_type`` 算法类型
        1. ``threshold`` 阈值
        2. ``max_val`` 最大值

        ``threshold`` 和 ``max_val`` 同为 255 时灰度处理.

        ``algorithm_type`` 算法类型说明:

        0. ``THRESH_BINARY``      算法，当前点值大于阈值 `threshold` 时，取最大值 ``max_val``，否则设置为 0；
        1. ``THRESH_BINARY_INV``  算法，当前点值大于阈值 `threshold` 时，设置为 0，否则设置为最大值 max_val；
        2. ``THRESH_TOZERO``      算法，当前点值大于阈值 `threshold` 时，不改变，否则设置为 0；
        3. ``THRESH_TOZERO_INV``  算法，当前点值大于阈值 ``threshold`` 时，设置为 0，否则不改变；
        4. ``THRESH_TRUNC``       算法，当前点值大于阈值 ``threshold`` 时，设置为阈值 ``threshold``，否则不改变；
        5. ``ADAPTIVE_THRESH_MEAN_C``      算法，自适应阈值；
        6. ``ADAPTIVE_THRESH_GAUSSIAN_C``  算法，自适应阈值；
    :param similarity: 相似度，0-1 的浮点数，默认 0.9；
    :param multi: 目标数量，默认为 1，找到 1 个目标后立即结束；
    :param wait_time: 等待时间，默认取 self.wait_timeout
    :param interval_time: 轮询间隔时间，默认取 self.interval_timeout
    :param raise_err: 超时是否抛出异常；
    :return:
    """

def find_dynamic_image(interval_ti: int, region: _Region = None, wait_time: float = None,
                       interval_time: float = None, raise_err: bool = None) -> List[_Point]:
    """
    找动态图，对比同一张图在不同时刻是否发生变化，返回坐标列表
    :param interval_ti: 前后时刻的间隔时间，单位毫秒；
    :param region: 截图区域，默认全屏，``region = (起点x、起点y、终点x、终点y)``，得到一个矩形
    :param wait_time: 等待时间，默认取 self.wait_timeout
    :param interval_time: 轮询间隔时间，默认取 self.interval_timeout
    :param raise_err: 超时是否抛出异常；
    :return: 坐标列表

坐标操作

def click(point: _Point_Tuple, offset_x: float = 0, offset_y: float = 0) -> bool:
    """
    点击坐标
    :param point: 坐标；
    :param offset_x: 坐标 x 轴偏移量；
    :param offset_y: 坐标 y 轴偏移量；
    :return:
    """


def double_click(point: _Point_Tuple, offset_x: float = 0, offset_y: float = 0) -> bool:
    """
    双击坐标
    :param point: 坐标；
    :param offset_x: 坐标 x 轴偏移量；
    :param offset_y: 坐标 y 轴偏移量；
    :return:
    """


def long_click(point: _Point_Tuple, duration: float, offset_x: float = 0, offset_y: float = 0) -> bool:
    """
    长按坐标
    :param point: 坐标；
    :param duration: 按住时长，单位秒；
    :param offset_x: 坐标 x 轴偏移量；
    :param offset_y: 坐标 y 轴偏移量；
    :return:
    """


def swipe(start_point: _Point_Tuple, end_point: _Point_Tuple, duration: float) -> bool:
    """
    滑动坐标
    :param start_point: 起始坐标；
    :param end_point: 结束坐标；
    :param duration: 滑动时长，单位秒；
    :return:
    """


def gesture(gesture_path: List[_Point_Tuple], duration: float) -> bool:
    """
    执行手势
    :param gesture_path: 手势路径，由一系列坐标点组成
    :param duration: 手势执行时长, 单位秒
    :return:
    """


def press(point: _Point_Tuple, duration: float) -> bool:
    """
    手指按下
    :param point: 坐标
    :param duration: 持续时间，单位秒
    :return:
    """


def move(point: _Point_Tuple, duration: float) -> bool:
    """
    手指移动
    :param point: 坐标
    :param duration: 持续时间
    :return:
    """


def release() -> bool:
    """手指抬起
    """


def press_release(point: _Point_Tuple, duration: float) -> bool:
    """
    按下屏幕坐标点并释放
    :param point: 按压坐标
    :param duration: 按压时长，单位秒
    :return:
    """


def press_release_by_ele(xpath, duration: float, wait_time: float = None,
                             interval_time: float = None, ) -> bool:
    """
    按压元素并释放
    :param xpath: 要按压的元素
    :param duration: 按压时长，单位秒
    :param wait_time: 查找元素的最长等待时间
    :param interval_time: 查找元素的轮询间隔时间
    :return:
    """

OCR

def init_ocr_server(ip: str, port: int = 9752) -> bool:
    """
    初始化 OCR 服务
    :param ip:
    :param port:
    :return:
    """


def get_text(region: _Region = None, scale: float = 1.0) -> List[str]:
    """
    通过 OCR 识别屏幕中的文字，返回文字列表
    :param region: 识别区域，默认全屏；
    :param algorithm: 处理图片/屏幕所用算法和参数，默认保存原图；
    :param scale: 图片缩放率，默认为 1.0，1.0 以下为缩小，1.0 以上为放大；
    :return: 文字列表
    """


def find_text(text: str, region: _Region = None, scale: float = 1.0) -> List[_Point]:
    """
    查找文字所在的坐标，返回坐标列表（坐标是文本区域中心位置）
    :param text: 要查找的文字；
    :param region: 识别区域，默认全屏；
    :param algorithm: 处理图片/屏幕所用算法和参数，默认保存原图；
    :param scale: 图片缩放率，默认为 1.0，1.0 以下为缩小，1.0 以上为放大；
    :return: 坐标列表（坐标是文本区域中心位置）
    """

元素操作

def get_element_rect(xpath: str, wait_time: float = None, interval_time: float = None,
                     raise_err: bool = None) -> Optional[Tuple[_Point, _Point]]:
    """
    获取元素位置，返回元素区域左上角和右下角坐标
    :param xpath: xpath 路径
    :param wait_time: 等待时间，默认取 self.wait_timeout
    :param interval_time: 轮询间隔时间，默认取 self.interval_timeout
    :param raise_err: 超时是否抛出异常；
    :return: 元素区域左上角和右下角坐标
    """


def get_element_desc(xpath: str, wait_time: float = None, interval_time: float = None,
                     raise_err: bool = None) -> Optional[str]:
    """
    获取元素描述
    :param xpath: xpath 路径
    :param wait_time: 等待时间，默认取 self.wait_timeout
    :param interval_time: 轮询间隔时间，默认取 self.interval_timeout
    :param raise_err: 超时是否抛出异常；
    :return: 元素描述字符串
    """


def get_element_text(xpath: str, wait_time: float = None, interval_time: float = None,
                     raise_err: bool = None) -> Optional[str]:
    """
    获取元素文本
    :param xpath: xpath 路径
    :param wait_time: 等待时间，默认取 self.wait_timeout
    :param interval_time: 轮询间隔时间，默认取 self.interval_timeout
    :param raise_err: 超时是否抛出异常；
    :return: 元素文本
    """


def set_element_text(xpath: str, text: str, wait_time: float = None, interval_time: float = None,
                     raise_err: bool = None) -> bool:
    """
    设置元素文本
    :param xpath:
    :param text:
    :param wait_time: 等待时间，默认取 .wait_timeout
    :param interval_time: 轮询间隔时间，默认取 .interval_timeout
    :param raise_err: 超时是否抛出异常；
    :return:
    """


def click_element(xpath: str, wait_time: float = None, interval_time: float = None,
                  raise_err: bool = None) -> bool:
    """
    点击元素
    :param xpath:
    :param wait_time: 等待时间，默认取 .wait_timeout
    :param interval_time: 轮询间隔时间，默认取 .interval_timeout
    :param raise_err: 超时是否抛出异常；
    :return:
    """


def click_any_elements(xpath_list: List[str], wait_time: float = None, interval_time: float = None,
                       raise_err: bool = None) -> bool:
    """
    遍历点击列表中的元素，直到任意一个元素返回 True
    :param xpath_list: xpath 列表
    :param wait_time: 等待时间，默认取 .wait_timeout
    :param interval_time: 轮询间隔时间，默认取 .interval_timeout
    :param raise_err: 超时是否抛出异常；
    :return:
    """


def scroll_element(xpath: str, direction: int = 0) -> bool:
    """
    滚动元素，0 向上滑动，1 向下滑动
    :param xpath: xpath 路径
    :param direction: 滚动方向，0 向上滑动，1 向下滑动
    :return:
    """


def element_not_exists(xpath: str, wait_time: float = None, interval_time: float = None) -> bool:
    """
    元素是否不存在
    :param xpath: xpath 路径
    :param wait_time: 等待时间，默认取 self.wait_timeout
    :param interval_time: 轮询间隔时间，默认取 self.interval_timeout
    :return:
    """


def element_exists(xpath: str, wait_time: float = None, interval_time: float = None) -> bool:
    """
    元素是否存在
    :param xpath: xpath 路径
    :param wait_time: 等待时间，默认取 self.wait_timeout
    :param interval_time: 轮询间隔时间，默认取 self.interval_timeout
    :return:
    """


def any_elements_exists(xpath_list: List[str], wait_time: float = None, interval_time: float = None) -> Optional[str]:
    """
    遍历列表中的元素，只要任意一个元素存在就返回 True
    :param xpath_list: xpath 列表
    :param wait_time: 等待时间，默认取 self.wait_timeout
    :param interval_time: 轮询间隔时间，默认取 self.interval_timeout
    :return: 任意一个元素存在就返回 True
    """


def element_is_selected(xpath: str) -> bool:
    """
    元素是否存在
    :param xpath: xpath 路径
    :return:
    """


def click_element_by_slide(xpath, distance: int = 1000, duration: float = 0.5, direction: int = 1,
                           count: int = 999, end_flag_xpath: str = None, wait_time: float = 600,
                           interval_time: float = 0.5, raise_err: bool = None) -> bool:
    """
    滑动列表，查找并点击指定元素
    :param xpath:
    :param distance: 滑动距离，默认 1000
    :param duration: 滑动时间，默认 0.5 秒
    :param direction: 滑动方向，默认为 1； 1=上滑，2=下滑
    :param count: 滑动次数
    :param end_flag_xpath: 结束标志 xpath
    :param wait_time: 等待时间，默认 10 分钟
    :param interval_time: 轮询间隔时间，默认 0.5 秒
    :param raise_err: 超时是否抛出异常；
    :return:
    """

文件传输

def push_file(origin_path: str, to_path: str) -> bool:
    """
    将电脑文件传输到手机端
    :param origin_path: 源文件路径
    :param to_path: 目标存储路径
    :return:

    ex:
    origin_path: /
    to_path: /storage/emulated/0/Android/data/com.aibot.client/files/code479259.png
    """


def pull_file(remote_path: str, local_path: str) -> bool:
    """
    将手机文件传输到电脑端
    :param remote_path: 手机端文件路径
    :param local_path: 电脑本地文件存储路径
    :return:

    ex:
    remote_path: /storage/emulated/0/Android/data/com.aibot.client/files/code479259.png
    local_path: /
    """

设备操作

def start_app(name: str, wait_time: float = None, interval_time: float = None) -> bool:
    """
    启动 APP
    :param name: APP名字或者包名
    :param wait_time: 等待时间，默认取 .wait_timeout
    :param interval_time: 轮询间隔时间，默认取 .interval_timeout
    :return:
    """


def get_device_ip() -> str:
    """
    获取设备IP地址
    :return:
    """


def get_android_id() -> str:
    """
    获取 Android 设备 ID
    :return:
    """


def get_window_size() -> Dict[str, float]:
    """
    获取屏幕大小
    :return:
    """


def get_image_size(image_path) -> Dict[str, float]:
    """
    获取图片大小
    :param image_path: 图片路径；
    :return:
    """


def show_toast(text: str) -> bool:
    """
    Toast 弹窗
    :param text: 弹窗内容；
    :return:
    """


def sleep(wait_time: float, interval_time: float = 1.5):
    """
    强制等待
    :param wait_time: 等待时长
    :param interval_time: 等待时轮询间隔时间
    :return:
    """


def send_keys(text: str) -> bool:
    """
    发送文本，需要打开 AiBot 输入法
    :param text: 文本内容
    :return:
    """


def send_vk(vk: int) -> bool:
    """
    发送文本，需要打开 AiBot 输入法
    :param vk: 虚拟键值
    :return:

    虚拟键值按键对照表 https://blog.csdn.net/yaoyaozaiye/article/details/122826340
    """


def write_android_file(remote_path: str, text: str, append: bool) -> bool:
    """
    写入安卓文件
    :param remote_path: 安卓文件路径
    :param text: 要写入的文本内容
    :param append: 是否追加模式
    :return:
    """


def read_android_file(remote_path: str) -> Optional[str]:
    """
    读取安卓文件
    :param remote_path: 安卓文件路径
    :return:
    """


def delete_android_file(remote_path: str) -> bool:
    """
    删除安卓文件
    :param remote_path: 安卓文件路径
    :return:
    """


def exists_android_file(remote_path: str) -> bool:
    """
    安卓文件是否存在
    :param remote_path: 安卓文件路径
    :return:
    """


def back() -> bool:
    """
    返回
    :return:
    """


def home() -> bool:
    """
    返回桌面
    :return:
    """


def recent_tasks() -> bool:
    """
    显示最近任务
    :return:
    """


def open_uri(uri: str) -> bool:
    """
    唤起 app
    :param uri: app 唤醒协议
    :return:

    open_uri("alipayqr://platformapi/startapp?saId=10000007")
    """


def start_activity(action: str,uri: str = '',package_name: str = '',class_name: str = '',typ: str = '') -> bool:
    """
    Intent 跳转
    :param action: 动作，例如 "android.intent.action.VIEW"
    :param uri: 跳转链接，例如：打开支付宝扫一扫界面，"alipayqr://platformapi/startapp?saId=10000007"
    :param package_name: 包名，"com.xxx.xxxxx"
    :param class_name: 类名
    :param typ: 类型
    :return: True或者 False
    """


def call_phone(mobile: str) -> bool:
    """
    拨打电话
    :param mobile: 手机号码
    :return:
    """


def send_msg(mobile, text) -> bool:
    """
    发送短信
    :param mobile: 手机号码
    :param text: 短信内容
    :return:
    """


def get_activity() -> str:
    """
    获取活动页
    :return:
    """


def get_package() -> str:
    """
    获取包名
    :return:
    """


def set_clipboard_text(text: str) -> bool:
    """
    设置剪切板文本
    :param text:
    :return:
    """


def get_clipboard_text() -> str:
    """
    获取剪切板内容
    :return:
    """

控件与参数

def create_text_view(_id: int, text: str, x: int, y: int, width: int = 400, height: int = 60):
    """
    创建文本框控件
    :param _id:  控件ID，不可与其他控件重复
    :param text:  控件文本
    :param x:  控件在屏幕上x坐标
    :param y:  控件在屏幕上y坐标
    :param width:  控件宽度，默认 400
    :param height:  控件高度，默认 60
    :return:
    """


def create_edit_view(_id: int, text: str, x: int, y: int, width: int = 400, height: int = 150):
    """
    创建编辑框控件
    :param _id:  控件ID，不可与其他控件重复
    :param text:  控件文本
    :param x:  控件在屏幕上x坐标
    :param y:  控件在屏幕上y坐标
    :param width:  控件宽度，默认 400
    :param height:  控件高度，默认 150
    :return:
    """


def create_check_box(_id: int, text: str, x: int, y: int, width: int = 400, height: int = 60):
    """
    创建复选框控件
    :param _id:  控件ID，不可与其他控件重复
    :param text:  控件文本
    :param x:  控件在屏幕上x坐标
    :param y:  控件在屏幕上y坐标
    :param width:  控件宽度，默认 400
    :param height:  控件高度，默认 60
    :return:
    """


def create_web_view(_id: int, url: str, x: int = -1, y: int = -1, width: int = -1, height: int = -1) -> bool:
    """
    创建WebView控件
    :param _id: 控件ID，不可与其他控件重复
    :param url: 加载的链接
    :param x: 控件在屏幕上 x 坐标，值为 -1 时自动填充宽高
    :param y: 控件在屏幕上 y 坐标，值为 -1 时自动填充宽高
    :param width: 控件宽度，值为 -1 时自动填充宽高
    :param height: 控件高度，值为 -1 时自动填充宽高
    :return:
    """


def clear_script_widget() -> bool:
    """
    清除脚本控件
    :return:
    """


def get_script_params() -> Optional[dict]:
    """
    获取脚本参数
    :return:
    """

验证码

def get_captcha(file_path: str, username: str, password: str, soft_id: str, code_type: str, len_min: str = '0') -> Optional[dict]:
    """
    识别验证码
    :param file_path: 图片文件路径
    :param username: 用户名
    :param password: 密码
    :param soft_id: 软件ID
    :param code_type: 图片类型 参考https://www.chaojiying.com/price.html
    :param len_min: 最小位数 默认0为不启用,图片类型为可变位长时可启用这个参数
    :return: JSON
        err_no,(数值) 返回代码  为0 表示正常，错误代码 参考https://www.chaojiying.com/api-23.html
        err_str,(字符串) 中文描述的返回信息 
        pic_id,(字符串) 图片标识号，或图片id号
        pic_str,(字符串) 识别出的结果
        md5,(字符串) md5校验值,用来校验此条数据返回是否真实有效
    """


def error_captcha(username: str, password: str, soft_id: str,pic_id: str)  -> Optional[dict]:
    """
    识别报错返分
    :param username: 用户名
    :param password: 密码
    :param soft_id: 软件ID
    :param pic_id: 图片ID 对应 getCaptcha返回值的pic_id 字段
    :return: JSON
        err_no,(数值) 返回代码
        err_str,(字符串) 中文描述的返回信息
    """


def score_captcha(username: str, password: str)  -> Optional[dict]:
    """
    查询验证码剩余题分
    :param username: 用户名
    :param password: 密码
    :return: JSON
        err_no,(数值) 返回代码
        err_str,(字符串) 中文描述的返回信息
        tifen,(数值) 题分
        tifen_lock,(数值) 锁定题分
    """

WinBot开发手册

窗口操作

def find_window(class_name: str = None, window_name: str = None) -> Optional[str]:
    """
    查找窗口句柄，仅查找顶级窗口，不包含子窗口
    :param class_name: 窗口类名
    :param window_name: 窗口名
    :return:
    """


def find_windows(class_name: str = None, window_name: str = None) -> List[str]:
    """
    查找窗口句柄数组，仅查找顶级窗口，不包含子窗口
    class_name 和 window_name 都为 None，则返回所有窗口句柄
    :param class_name: 窗口类名
    :param window_name: 窗口名
    :return: 窗口句柄的列表
    """


def find_sub_window(hwnd: str, class_name: str = None, window_name: str = None) -> Optional[str]:
    """
    查找子窗口句柄
    :param hwnd: 当前窗口句柄
    :param class_name: 窗口类名
    :param window_name: 窗口名
    :return: 子窗口句柄或 None
    """


def find_parent_window(hwnd: str) -> Optional[str]:
    """
    查找父窗口句柄
    :param hwnd: 当前窗口句柄
    :return: 父窗口句柄或 None
    """


def find_desktop_window() -> Optional[str]:
    """
    查找桌面窗口句柄
    :return: 桌面窗口句柄或 None
    """


def get_window_name(hwnd: str) -> Optional[str]:
    """
    获取窗口名称
    :param hwnd: 当前窗口句柄
    :return: 窗口名称或 None
    """


def show_window(hwnd: str, show: bool) -> bool:
    """
    显示/隐藏窗口
    :param hwnd: 当前窗口句柄
    :param show: 是否显示窗口
    :return:
    """


def set_window_top(hwnd: str, top: bool) -> bool:
    """
    设置窗口到最顶层
    :param hwnd: 当前窗口句柄
    :param top: 是否置顶，True 置顶， False 取消置顶
    :return:
    """


def get_window_pos(hwnd: str, wait_time: float = None, interval_time: float = None) -> Optional[Tuple[Point, Point]]:
    """
    获取窗口位置
    :param hwnd: 窗口句柄
    :return:
    """


def set_window_pos(hwnd: str, left: float, top: float, width: float, height: float) -> bool:
    """
    设置窗口位置
    :param hwnd: 当前窗口句柄
    :param left: 左上角横坐标
    :param top: 左上角纵坐标
    :param width: 窗口宽度
    :param height: 窗口高度
    :return:
    """

键鼠操作

def move_mouse(hwnd: str, x: float, y: float, mode: bool = False, ele_hwnd: str = "0") -> bool:
    """
    移动鼠标
    :param hwnd: 当前窗口句柄
    :param x: 横坐标
    :param y: 纵坐标
    :param mode: 操作模式，后台 true，前台 false, 默认前台操作
    :param ele_hwnd: 元素句柄，如果 mode=True 且目标控件有单独的句柄，则需要通过 get_element_window 获得元素句柄，指定 ele_hwnd 的值(极少应用窗口由父窗口响应消息，则无需指定);
    :return:
    """


def move_mouse_relative(hwnd: str, x: float, y: float, mode: bool = False) -> bool:
    """
    移动鼠标(相对坐标)
    :param hwnd: 当前窗口句柄
    :param x: 相对横坐标
    :param y: 相对纵坐标
    :param mode: 操作模式，后台 true，前台 false, 默认前台操作
    :return:
    """


def scroll_mouse(hwnd: str, x: float, y: float, count: int, mode: bool = False) -> bool:
    """
    滚动鼠标
    :param hwnd: 当前窗口句柄
    :param x: 横坐标
    :param y: 纵坐标
    :param count: 鼠标滚动次数, 负数下滚鼠标, 正数上滚鼠标
    :param mode: 操作模式，后台 true，前台 false, 默认前台操作
    :return:
    """


def click_mouse(hwnd: str, x: float, y: float, typ: int, mode: bool = False, ele_hwnd: str = "0") -> bool:
    """
    鼠标点击
    :param hwnd: 当前窗口句柄
    :param x: 横坐标
    :param y: 纵坐标
    :param typ: 点击类型，单击左键:1 单击右键:2 按下左键:3 弹起左键:4 按下右键:5 弹起右键:6 双击左键:7 双击右键:8
    :param mode: 操作模式，后台 true，前台 false, 默认前台操作
    :param ele_hwnd: 元素句柄，如果 mode=True 且目标控件有单独的句柄，则需要通过 get_element_window 获得元素句柄，指定 ele_hwnd 的值(极少应用窗口由父窗口响应消息，则无需指定);
    :return:
    """


def send_keys(text: str) -> bool:
    """
    输入文本
    :param text: 输入的文本
    :return:
    """


def send_keys_by_hwnd(hwnd: str, text: str) -> bool:
    """
    后台输入文本(杀毒软件可能会拦截)
    :param hwnd: 窗口句柄
    :param text: 输入的文本
    :return:
    """


def send_vk(vk: int, typ: int) -> bool:
    """
    输入虚拟键值(VK)
    :param vk: VK键值
    :param typ: 输入类型，按下弹起:1 按下:2 弹起:3
    :return:
    """


def send_vk_by_hwnd(hwnd: str, vk: int, typ: int) -> bool:
    """
    后台输入虚拟键值(VK)
    :param hwnd: 窗口句柄
    :param vk: VK键值
    :param typ: 输入类型，按下弹起:1 按下:2 弹起:3
    :return:
    """

图色操作

def save_screenshot(hwnd: str, save_path: str, region: _Region = None, algorithm: _Algorithm = None, mode: bool = False) -> bool:
    """
    截图
    :param hwnd: 窗口句柄；
    :param save_path: 图片存储路径；
    :param region: 截图区域，默认全屏；
    :param algorithm: 处理截图所用算法和参数，默认保存原图；
    :param mode: 操作模式，后台 true，前台 false, 默认前台操作；
    :return:

    # 区域相关参数
    region = (0, 0, 0, 0) 按元素顺序分别代表：起点x、起点y、终点x、终点y，最终得到一个矩形。
    # 算法相关参数
    algorithm = (0, 0, 0) # 按元素顺序分别代表：algorithm_type 算法类型、threshold 阈值、max_val 最大值。
    threshold 和 max_val 同为 255 时灰度处理.
    0   THRESH_BINARY      算法，当前点值大于阈值 threshold 时，取最大值 max_val，否则设置为 0；
    1   THRESH_BINARY_INV  算法，当前点值大于阈值 threshold 时，设置为 0，否则设置为最大值 max_val；
    2   THRESH_TOZERO      算法，当前点值大于阈值 threshold 时，不改变，否则设置为 0；
    3   THRESH_TOZERO_INV  算法，当前点值大于阈值 threshold 时，设置为 0，否则不改变；
    4   THRESH_TRUNC       算法，当前点值大于阈值 threshold 时，设置为阈值 threshold，否则不改变；
    5   ADAPTIVE_THRESH_MEAN_C      算法，自适应阈值；
    6   ADAPTIVE_THRESH_GAUSSIAN_C  算法，自适应阈值；
    """


def get_color(hwnd: str, x: float, y: float, mode: bool = False) -> Optional[str]:
    """
    获取指定坐标点的色值，返回色值字符串(#008577)或者 None
    :param hwnd: 窗口句柄；
    :param x: x 坐标；
    :param y: y 坐标；
    :param mode: 操作模式，后台 true，前台 false, 默认前台操作；
    :return:
    """


def find_color(hwnd: str, color: str, sub_colors: _SubColors = None, region: _Region = None,
               similarity: float = 0.9, mode: bool = False, wait_time: float = None,
               interval_time: float = None):
    """
    获取指定色值的坐标点，返回坐标或者 None
    :param hwnd: 窗口句柄；
    :param color: 颜色字符串，必须以 # 开头，例如：#008577；
    :param sub_colors: 辅助定位的其他颜色；
    :param region: 在指定区域内找色，默认全屏；
    :param similarity: 相似度，0-1 的浮点数，默认 0.9；
    :param mode: 操作模式，后台 true，前台 false, 默认前台操作；
    :param wait_time: 等待时间，默认取 .wait_timeout；
    :param interval_time: 轮询间隔时间，默认取 .interval_timeout；
    :return:

    # 区域相关参数
    region = (0, 0, 0, 0) 按元素顺序分别代表：起点x、起点y、终点x、终点y，最终得到一个矩形。
    # 算法相关参数
    algorithm = (0, 0, 0) # 按元素顺序分别代表：algorithm_type 算法类型、threshold 阈值、max_val 最大值。
    threshold 和 max_val 同为 255 时灰度处理.
    0   THRESH_BINARY      算法，当前点值大于阈值 threshold 时，取最大值 max_val，否则设置为 0；
    1   THRESH_BINARY_INV  算法，当前点值大于阈值 threshold 时，设置为 0，否则设置为最大值 max_val；
    2   THRESH_TOZERO      算法，当前点值大于阈值 threshold 时，不改变，否则设置为 0；
    3   THRESH_TOZERO_INV  算法，当前点值大于阈值 threshold 时，设置为 0，否则不改变；
    4   THRESH_TRUNC       算法，当前点值大于阈值 threshold 时，设置为阈值 threshold，否则不改变；
    5   ADAPTIVE_THRESH_MEAN_C      算法，自适应阈值；
    6   ADAPTIVE_THRESH_GAUSSIAN_C  算法，自适应阈值；
    """


def compare_color(hwnd: str,main_x: float,main_y: float,color: str,sub_colors: _SubColors = None,region: _Region = None,similarity: float = 0.9,mode: bool = False,wait_time: float = None,interval_time: float = None,raise_err: bool = None) -> Optional[Point]:
    """
    比较指定坐标点的颜色值
    :param hwnd: 窗口句柄；
    :param main_x: 主颜色所在的X坐标；
    :param main_y: 主颜色所在的Y坐标；
    :param color: 颜色字符串，必须以 # 开头，例如：#008577；
    :param sub_colors: 辅助定位的其他颜色；
    :param region: 截图区域，默认全屏，``region = (起点x、起点y、终点x、终点y)``，得到一个矩形
    :param similarity: 相似度，0-1 的浮点数，默认 0.9；
    :param mode: 操作模式，后台 true，前台 false, 默认前台操作；
    :param wait_time: 等待时间，默认取 self.wait_timeout；
    :param interval_time: 轮询间隔时间，默认取 self.interval_timeout；
    :param raise_err: 超时是否抛出异常；
    :return: True或者 False
    """


def extract_image_by_video(video_path: str, save_folder: str, jump_frame: int = 1) -> bool:
    """
    提取视频帧
    :param video_path: 视频路径
    :param save_folder: 提取的图片保存的文件夹目录
    :param jump_frame: 跳帧，默认为1 不跳帧
    :return: True或者False
    """


def crop_image(image_path, save_path, left, top, rigth, bottom) -> bool:
    """
    裁剪图片
    :param image_path: 图片路径
    :param save_path: 裁剪后保存的图片路径
    :param left: 裁剪的左上角横坐标
    :param top: 裁剪的左上角纵坐标
    :param rigth: 裁剪的右下角横坐标
    :param bottom: 裁剪的右下角纵坐标
    :return: True或者False
    """


def find_images(hwnd: str, image_path: str, region: _Region = None, algorithm: _Algorithm = None,
                similarity: float = 0.9, mode: bool = False, multi: int = 1, wait_time: float = None,
                interval_time: float = None) -> List[_Point]:
    """
    寻找图片坐标，在当前屏幕中寻找给定图片中心点的坐标，返回坐标列表
    :param hwnd: 窗口句柄；
    :param image_path: 图片的绝对路径；
    :param region: 从指定区域中找图，默认全屏；
    :param algorithm: 处理屏幕截图所用的算法，默认原图，注意：给定图片处理时所用的算法，应该和此方法的算法一致；
    :param similarity: 相似度，0-1 的浮点数，默认 0.9；
    :param mode: 操作模式，后台 true，前台 false, 默认前台操作；
    :param multi: 返回图片数量，默认1张；
    :param wait_time: 等待时间，默认取 .wait_timeout；
    :param interval_time: 轮询间隔时间，默认取 .interval_timeout；
    :return:

    # 区域相关参数
    region = (0, 0, 0, 0) 按元素顺序分别代表：起点x、起点y、终点x、终点y，最终得到一个矩形。
    # 算法相关参数
    algorithm = (0, 0, 0) # 按元素顺序分别代表：algorithm_type 算法类型、threshold 阈值、max_val 最大值。
    threshold 和 max_val 同为 255 时灰度处理.
    0   THRESH_BINARY      算法，当前点值大于阈值 threshold 时，取最大值 max_val，否则设置为 0；
    1   THRESH_BINARY_INV  算法，当前点值大于阈值 threshold 时，设置为 0，否则设置为最大值 max_val；
    2   THRESH_TOZERO      算法，当前点值大于阈值 threshold 时，不改变，否则设置为 0；
    3   THRESH_TOZERO_INV  算法，当前点值大于阈值 threshold 时，设置为 0，否则不改变；
    4   THRESH_TRUNC       算法，当前点值大于阈值 threshold 时，设置为阈值 threshold，否则不改变；
    5   ADAPTIVE_THRESH_MEAN_C      算法，自适应阈值；
    6   ADAPTIVE_THRESH_GAUSSIAN_C  算法，自适应阈值；
    """


def find_dynamic_image(hwnd: str, interval_ti: int, region: _Region = None, mode: bool = False,
                       wait_time: float = None, interval_time: float = None) -> List[_Point]:
    """
    找动态图，对比同一张图在不同时刻是否发生变化，返回坐标列表
    :param hwnd: 窗口句柄；
    :param interval_ti: 前后时刻的间隔时间，单位毫秒；
    :param region: 在指定区域找图，默认全屏；
    :param mode: 操作模式，后台 true，前台 false, 默认前台操作；
    :param wait_time: 等待时间，默认取 .wait_timeout；
    :param interval_time: 轮询间隔时间，默认取 .interval_timeout；
    :return:
    """

OCR

def init_ocr_server(ip: str, port: int = 9752) -> bool:
    """
    初始化 OCR 服务
    :param ip:
    :param port:
    :return:
    """


def get_text(hwnd_or_image_path: str, region: _Region = None, algorithm: _Algorithm = None,mode: bool = False) -> List[str]:
    """
    通过 OCR 识别窗口/图片中的文字，返回文字列表
    :param hwnd_or_image_path: 窗口句柄或者图片路径；
    :param region: 识别区域，默认全屏；
    :param algorithm: 处理图片/屏幕所用算法和参数，默认保存原图；
    :param mode: 操作模式，后台 true，前台 false, 默认前台操作；
    :return:
    """


def find_text(hwnd_or_image_path: str, text: str, region: _Region = None, algorithm: _Algorithm = None,mode: bool = False) -> List[Point]:
    """
    通过 OCR 识别窗口/图片中的文字，返回文字列表
    :param hwnd_or_image_path: 句柄或者图片路径
    :param text: 要查找的文字
    :param region: 识别区域，默认全屏
    :param algorithm: 处理图片/屏幕所用算法和参数，默认保存原图
    :param mode: 操作模式，后台 true，前台 false, 默认前台操作
    :return: 文字列表
    """

元素操作

def get_element_name(hwnd: str, xpath: str, wait_time: float = None, interval_time: float = None) -> Optional[str]:
    """
    获取元素名称
    :param hwnd: 窗口句柄
    :param xpath: 元素路径
    :param wait_time: 等待时间，默认取 .wait_timeout；
    :param interval_time: 轮询间隔时间，默认取 .interval_timeout；
    :return: 元素名称字符串或 None
    """


def get_element_value(hwnd: str, xpath: str, wait_time: float = None, interval_time: float = None) -> Optional[str]:
    """
    获取元素文本
    :param hwnd: 窗口句柄
    :param xpath: 元素路径
    :param wait_time: 等待时间，默认取 .wait_timeout；
    :param interval_time: 轮询间隔时间，默认取 .interval_timeout；
    :return: 元素文本字符串或 None
    """


def get_element_rect(hwnd: str, xpath: str, wait_time: float = None, interval_time: float = None) -> Optional[Tuple[_Point, _Point]]:
    """
    获取元素矩形，返回左上和右下坐标
    :param hwnd: 窗口句柄
    :param xpath: 元素路径
    :param wait_time: 等待时间，默认取 .wait_timeout；
    :param interval_time: 轮询间隔时间，默认取 .interval_timeout；
    :return: 左上和右下坐标
    """


def get_element_window(hwnd: str, xpath: str, wait_time: float = None, interval_time: float = None) -> Optional[str]:
    """
    获取元素窗口句柄
    :param hwnd: 窗口句柄
    :param xpath: 元素路径
    :param wait_time: 等待时间，默认取 .wait_timeout；
    :param interval_time: 轮询间隔时间，默认取 .interval_timeout；
    :return: 元素窗口句柄字符串或 None
    """


def click_element(hwnd: str, xpath: str, typ: int, wait_time: float = None,
                  interval_time: float = None) -> bool:
    """
    获取元素窗口句柄
    :param hwnd: 窗口句柄
    :param xpath: 元素路径
    :param typ: 操作类型，单击左键:1 单击右键:2 按下左键:3 弹起左键:4 按下右键:5 弹起右键:6 双击左键:7 双击右键:8
    :param wait_time: 等待时间，默认取 .wait_timeout；
    :param interval_time: 轮询间隔时间，默认取 .interval_timeout；
    :return:
    """


def invoke_element(hwnd: str, xpath: str, wait_time: float = None,
                      interval_time: float = None) -> bool:
    """
    执行元素默认操作(一般是点击操作)
    :param hwnd: 窗口句柄
    :param xpath: 元素路径
    :param wait_time: 等待时间，默认取 self.wait_timeout；
    :param interval_time: 轮询间隔时间，默认取 self.interval_timeout；
    :return:
    """


def set_element_focus(hwnd: str, xpath: str, wait_time: float = None,
                      interval_time: float = None) -> bool:
    """
    设置元素作为焦点
    :param hwnd: 窗口句柄
    :param xpath: 元素路径
    :param wait_time: 等待时间，默认取 .wait_timeout；
    :param interval_time: 轮询间隔时间，默认取 .interval_timeout；
    :return:
    """


def set_element_value(hwnd: str, xpath: str, value: str,
                      wait_time: float = None, interval_time: float = None) -> bool:
    """
    设置元素文本
    :param hwnd: 窗口句柄
    :param xpath: 元素路径
    :param value: 要设置的内容
    :param wait_time: 等待时间，默认取 .wait_timeout；
    :param interval_time: 轮询间隔时间，默认取 .interval_timeout；
    :return:
    """


def scroll_element(hwnd: str, xpath: str, horizontal: int, vertical: int,
                   wait_time: float = None, interval_time: float = None) -> bool:
    """
    滚动元素
    :param hwnd: 窗口句柄
    :param xpath: 元素路径
    :param horizontal: 水平百分比 -1不滚动
    :param vertical: 垂直百分比 -1不滚动
    :param wait_time: 等待时间，默认取 .wait_timeout；
    :param interval_time: 轮询间隔时间，默认取 .interval_timeout；
    :return:
    """


def is_selected(hwnd: str, xpath: str,
                       wait_time: float = None, interval_time: float = None) -> bool:
    """
    单/复选框是否选中
    :param hwnd: 窗口句柄
    :param xpath: 元素路径
    :param wait_time: 等待时间，默认取 self.wait_timeout；
    :param interval_time: 轮询间隔时间，默认取 self.interval_timeout；
    :return:
    """


def close_window(hwnd: str, xpath: str) -> bool:
    """
    关闭窗口
    :param hwnd: 窗口句柄
    :param xpath: 元素路径
    :return:
    """


def set_element_state(hwnd: str, xpath: str, state: str) -> bool:
    """
    设置窗口状态
    :param hwnd: 窗口句柄
    :param xpath: 元素路径
    :param state: 0正常 1最大化 2 最小化
    :return:
    """

系统剪切板

def set_clipboard_text(text: str) -> bool:
    """
    设置剪切板内容
    :param text: 要设置的内容
    :return:
    """


def get_clipboard_text() -> str:
    """
    设置剪切板内容
    :return:
    """

启动进程

def start_process(cmd: str, show_window=True, is_wait=False) -> bool:
    """
    执行cmd命令
    :param cmd: 命令
    :param show_window: 是否显示窗口，默认显示
    :param is_wait: 是否等待程序结束， 默认不等待
    :return:
    """


def execute_command(command: str, waitTimeout: int = 300) -> str:
    """
    执行cmd命令
    :param command: cmd命令，不能含 "cmd"字串
    :param waitTimeout: 可选参数，等待结果返回超时，单位毫秒，默认300毫秒
    :return: cmd执行结果
    """


def download_file(url: str, file_path: str, is_wait: bool) -> bool:
    """

    :param url: 文件地址
    :param file_path: 文件保存的路径
    :param is_wait: 是否等待下载完成
    :return:
    """

EXCEL操作

def open_excel(excel_path: str) -> Optional[dict]:
    """
    打开excel文档
    :param excel_path: excle路径
    :return: excel对象或者None
    """


def open_excel_sheet(excel_object: dict, sheet_name: str) -> Optional[dict]:
    """
    打开excel表格
    :param excel_object: excel对象
    :param sheet_name: 表名
    :return: sheet对象或者None
    """


def save_excel(excel_object: dict)  -> bool:
    """
    保存excel文档
    :param excel_object: excel对象
    :return: True或者False
    """


def write_excel_num(excel_object: dict, row: int, col: int, value: int)  -> bool:
    """
    写入数字到excel表格
    :param excel_object: excel对象
    :param row: 行
    :param col: 列
    :param value: 写入的值
    :return: True或者False
    """


def write_excel_str(excel_object: dict, row: int, col: int, str_value: str)  -> bool:
    """
    写入字符串到excel表格
    :param excel_object: excel对象
    :param row: 行
    :param col: 列
    :param str_value: 写入的值
    :return: True或者False
    """


def read_excel_num(excel_object: dict, row: int, col: int)  -> int:
    """
    读取excel表格数字
    :param excel_object: excel对象
    :param row: 行
    :param col: 列
    :return: 读取到的数字
    """


def read_excel_str(excel_object: dict, row: int, col: int)  -> str:
    """
    读取excel表格字符串
    :param excel_object: excel对象
    :param row: 行
    :param col: 列
    :return: 读取到的字符
    """


def remove_excel_row(excel_object: dict, row_first: int, row_last: int)  -> bool:
    """
    删除excel表格行
    :param excel_object: excel对象
    :param row_first: 起始行
    :param row_last: 结束行
    :return: True或者False
    """


def remove_excel_col(excel_object: dict, col_first: int, col_last: int)  -> bool:
    """
    删除excel表格列
    :param excel_object: excel对象
    :param col_first: 起始列
    :param col_last: 结束列
    :return: True或者False
    """

验证码

def get_captcha(file_path: str, username: str, password: str, soft_id: str, code_type: str, len_min: str = '0') -> Optional[dict]:
    """
    识别验证码
    :param file_path: 图片文件路径
    :param username: 用户名
    :param password: 密码
    :param soft_id: 软件ID
    :param code_type: 图片类型 参考https://www.chaojiying.com/price.html
    :param len_min: 最小位数 默认0为不启用,图片类型为可变位长时可启用这个参数
    :return: JSON
        err_no,(数值) 返回代码  为0 表示正常，错误代码 参考https://www.chaojiying.com/api-23.html
        err_str,(字符串) 中文描述的返回信息 
        pic_id,(字符串) 图片标识号，或图片id号
        pic_str,(字符串) 识别出的结果
        md5,(字符串) md5校验值,用来校验此条数据返回是否真实有效
    """


def error_captcha(username: str, password: str, soft_id: str,pic_id: str)  -> Optional[dict]:
    """
    识别报错返分
    :param username: 用户名
    :param password: 密码
    :param soft_id: 软件ID
    :param pic_id: 图片ID 对应 getCaptcha返回值的pic_id 字段
    :return: JSON
        err_no,(数值) 返回代码
        err_str,(字符串) 中文描述的返回信息
    """


def score_captcha(username: str, password: str)  -> Optional[dict]:
    """
    查询验证码剩余题分
    :param username: 用户名
    :param password: 密码
    :return: JSON
        err_no,(数值) 返回代码
        err_str,(字符串) 中文描述的返回信息
        tifen,(数值) 题分
        tifen_lock,(数值) 锁定题分
    """

语音服务

 def activate_speech_service(activate_key: str)  -> bool:
    """
    激活 initSpeechService (不支持win7)
    :param activate_key: 激活密钥，联系管理员
    :return: True或者False
    """


def init_speech_service(speech_key: str, speech_region: str)  -> bool:
    """
    初始化语音服务(不支持win7)，需要调用 activateSpeechService 激活
    :param speech_key: 密钥
    :param speech_region: 区域
    :return: True或者False
    """


def audio_file_to_text(file_path, language: str) -> Optional[str]:
    """
    音频文件转文本
    :param file_path: 音频文件路径
    :param language: 语言，参考开发文档 语言和发音人
    :return: 转换后的音频文本或者None
    """


def microphone_to_text(language: str) -> Optional[str]:
    """
    麦克风输入流转换文本
    :param language: 语言，参考开发文档 语言和发音人
    :return: 转换后的音频文本或者None
    """


def text_to_bullhorn(ssmlPath_or_text: str, language: str, voice_name: str)  -> bool:
    """
    文本合成音频到扬声器
    :param ssmlPath_or_text: 要转换语音的文本或者".xml"格式文件路径
    :param language: 语言，参考开发文档 语言和发音人
    :param voice_name: 发音人，参考开发文档 语言和发音人
    :return: True或者False
    """


def text_to_audio_file(ssmlPath_or_text: str, language: str, voice_name: str, audio_path: str)  -> bool:
    """
    文本合成音频并保存到文件
    :param ssmlPath_or_text: 要转换语音的文本或者".xml"格式文件路径
    :param language: 语言，参考开发文档 语言和发音人
    :param voice_name: 发音人，参考开发文档 语言和发音人
    :param audio_path: 保存音频文件路径
    :return: True或者False
    """


def microphone_translation_text(source_language: str, target_language: str) -> Optional[str]:
    """
    麦克风输入流转换文本
    :param source_language: 要翻译的语言，参考开发文档 语言和发音人
    :param target_language: 翻译后的语言，参考开发文档 语言和发音人
    :return: 转换后的音频文本或者None
    """


def audio_file_translation_text(audio_path: str, source_language: str, target_language: str) -> Optional[str]:
    """
    麦克风输入流转换文本
    :param audio_path: 要翻译的音频文件路径
    :param source_language: 要翻译的语言，参考开发文档 语言和发音人
    :param target_language: 翻译后的语言，参考开发文档 语言和发音人
    :return: 转换后的音频文本或者None
    """

数字人

def init_metahuman(metahuman_mde_path: str, metahuman_scale_value: str, is_update_metahuman: bool = False)  -> bool:
    """
    初始化数字人，第一次初始化需要一些时间
    :param metahuman_mde_path: 数字人模型路径
    :param metahuman_scale_value: 数字人缩放倍数，1为原始大小。为0.5时放大一倍，2则缩小一半
    :param is_update_metahuman: 是否强制更新，默认fasle。为true时强制更新会拖慢初始化速度
    :return: True或者False
    """


def metahuman_speech(save_voice_folder: str, text: str, language: str, voice_name: str, 
                         quality: int = 0, wait_play_sound: bool = True, speech_rate: int = 0, voice_style: str = "General")  -> bool:
    """
    数字人说话，此函数需要调用 initSpeechService 初始化语音服务

    :param save_voice_folder: 保存的发音文件目录，文件名以0开始依次增加，扩展为.wav格式
    :param text: 要转换语音的文本
    :param language: 语言，参考开发文档 语言和发音人
    :param voice_name: 发音人，参考开发文档 语言和发音人
    :param quality: 音质，0低品质  1中品质  2高品质， 默认为0低品质
    :param wait_play_sound: 等待音频播报完毕，默认为 true等待
    :param speech_rate:  语速，默认为0，取值范围 -100 至 200
    :param voice_style: 语音风格，默认General常规风格，其他风格参考开发文档 语言和发音人
    :return: True或者False
    """


def metahuman_speech_cache(save_voice_folder: str, text: str, language: str, voice_name: str, 
                         quality: int = 0, wait_play_sound: bool = True, speech_rate: int = 0, voice_style: str = "General")  -> bool:
        """
        *数字人说话缓存模式，需要调用 initSpeechService 初始化语音服务。函数一般用于常用的话术播报，非常用话术切勿使用，否则内存泄漏
        :param save_voice_folder: 保存的发音文件目录，文件名以0开始依次增加，扩展为.wav格式
        :param text: 要转换语音的文本
        :param language: 语言，参考开发文档 语言和发音人
        :param voice_name: 发音人，参考开发文档 语言和发音人
        :param quality: 音质，0低品质  1中品质  2高品质， 默认为0低品质
        :param wait_play_sound: 等待音频播报完毕，默认为 true等待
        :param speech_rate:  语速，默认为0，取值范围 -100 至 200
        :param voice_style: 语音风格，默认General常规风格，其他风格参考开发文档 语言和发音人
        :return: True或者False
        """


def metahuman_insert_video(video_file_path: str, audio_file_path: str, wait_play_video:bool = True)  -> bool:
    """
    数字人插入视频
    :param video_file_path: 插入的视频文件路径
    :param audio_file_path: 插入的音频文件路径
    :param wait_play_video: 等待视频播放完毕，默认为 true等待
    :return: True或者False
    """


def replace_background(bg_file_path: str, replace_red: int = -1, replace_green: int = -1, replace_blue: int = -1, sim_value: int = 0)  -> bool:
    """
    替换数字人背景
    :param bg_file_path: 数字人背景 图片/视频 路径，默认不替换背景。仅替换绿幕背景的数字人模型
    :param replace_red: 数字人背景的三通道之一的 R通道色值。默认-1 自动提取
    :param replace_green: 数字人背景的三通道之一的 G通道色值。默认-1 自动提取
    :param replace_blue: 数字人背景的三通道之一的 B通道色值。默认-1 自动提取
    :param sim_value: 相似度。 默认为0，取值应当大于等于0
    :return: True或者False
    """


def show_speech_text(origin_y: int = 0, font_type: str = "Arial", font_size: int = 30, font_red: int = 128,
                          font_green: int = 255, font_blue: int = 0, italic:bool = False, underline:bool = False)  -> bool:
    """
    显示数字人说话的文本
    :param origin_y, 第一个字显示的起始Y坐标点。 默认0 自适应高度
    :param font_type, 字体样式，支持操作系统已安装的字体。例如"Arial"、"微软雅黑"、"楷体"
    :param font_size, 字体的大小。默认30
    :param font_red, 字体颜色三通道之一的 R通道色值。默认128
    :param font_green, 字体颜色三通道之一的 G通道色值。默认255
    :param font_blue, 字体颜色三通道之一的 B通道色值。默认0
    :param italic, 是否斜体,默认false
    :param underline, 是否有下划线,默认false
    :return: True或者False
    """

驱动程序相关

def get_extend_param() -> Optional[str]:
    """
    获取WindowsDriver.exe 命令扩展参数
    :return: WindowsDriver 驱动程序的命令行["extendParam"] 字段的参数
    """


def close_driver() -> bool:
    """
    关闭WindowsDriver.exe驱动程序
    :return:
    """

WebBot开发手册

页面和导航

def goto(url: str) -> bool:
    """
    跳转页面
    :param url: url 地址
    :return:
    """


def new_page(url: str) -> bool:
    """
    新建 Tab 并跳转页面
    :param url: url 地址
    :return:
    """


def back() -> bool:
    """
    后退
    :return:
    """


def forward() -> bool:
    """
    前进
    :return:
    """


def refresh() -> bool:
    """
    刷新
    :return:
    """


def save_screenshot(xpath: str = None) -> Optional[str]:
    """
    截图，返回 PNG 格式的 base64
    :param xpath: 元素路径，如果指定该参数则截取元素图片；
    :return: PNG 格式的 base64 的字符串或 None
    """


def get_current_page_id() -> Optional[str]:
    """
    获取当前页面 ID
    :return:
    """


def get_all_page_id() -> list:
    """
    获取所有页面 ID
    :return:
    """


def switch_to_page(page_id: str) -> bool:
    """
    切换到指定页面
    :param page_id:
    :return:
    """


def close_current_page() -> bool:
    """
    关闭当前页面
    :return:
    """


def ger_current_url() -> Optional[str]:
    """
    获取当前页面 URL
    :return: 当前页面 URL 字符串或 None
    """


def get_current_title() -> Optional[str]:
    """
    获取当前页面标题
    :return:
    """

iframe 操作

def switch_to_frame(xpath) -> bool:
    """
    切换到指定 frame
    :param xpath: xpath 路径
    :return:
    """


def switch_to_main_frame() -> bool:
    """
    切回主 frame
    :return:
    """

元素操作

def click_element(xpath: str) -> bool:
    """
    点击元素
    :param xpath:
    :return:
    """


def get_element_text(xpath: str) -> Optional[str]:
    """
    获取元素文本
    :param xpath: xpath 路径
        :return: 元素文本字符串或 None
    """


def get_element_rect(xpath: str) -> Optional[Tuple[_Point, _Point]]:
    """
    获取元素矩形坐标
    :param xpath: xpath 路径
        :return: 元素矩形坐标或None
    """


def get_element_attr(xpath: str, attr_name: str) -> Optional[str]:
    """
    获取元素的属性
    :param xpath: xpath 路径
    :param attr_name: 属性名称字符串
    :return:
    """


def get_element_outer_html(xpath: str) -> Optional[str]:
    """
    获取元素的 outerHtml
    :param xpath: xpath 路径
    :return:
    """


def get_element_inner_html(xpath: str) -> Optional[str]:
    """
    获取元素的 innerHtml
    :param xpath: xpath 路径
    :return:
    """


def is_selected(xpath: str) -> bool:
    """
    元素是否已选中
    :param xpath: xpath 路径
    :return:
    """


def is_displayed(xpath: str) -> bool:
    """
    元素是否可见
    :param xpath: xpath 路径
    :return:
    """


def is_available(xpath: str) -> bool:
    """
    元素是否可用
    :param xpath: xpath 路径
    :return:
    """


def clear_element(xpath: str) -> bool:
    """
    清除元素值
    :param xpath: xpath 路径
    :return:
    """


def set_element_focus(xpath: str) -> bool:
    """
    设置元素焦点
    :param xpath: xpath 路径
    :return:
    """


def upload_file_by_element(xpath: str, file_path: str) -> bool:
    """
    通过元素上传文件
    :param xpath:  元素 xpath 路径
    :param file_path: 文件路径
    :return:
    """


def send_keys(xpath: str, value: str) -> bool:
    """
    输入值；如果元素不能设置焦点，应先 click_mouse 点击元素获得焦点后再输入
    :param xpath: 元素 xpath 路径
    :param value: 输入的内容
    :return:
    """


def set_element_value(xpath: str, value: str) -> bool:
    """
    设置元素值
    :param xpath: 元素 xpath 路径
    :param value: 设置的内容
    :return:
    """


def set_element_attr(xpath: str, attr_name: str, attr_value: str) -> bool:
    """
    设置元素属性
    :param xpath: 元素 xpath 路径
    :param attr_name: 属性名称
    :param attr_value: 属性值
    :return:
    """


def send_vk(vk: str) -> bool:
    """
    输入值
    :param vk: 输入内容
    :return:
    """

键鼠操作

def click_mouse(point: _Point_Tuple, typ: int) -> bool:
    """
    点击鼠标
    :param point: 坐标点
    :param typ: 点击类型，单击左键:1 单击右键:2 按下左键:3 弹起左键:4 按下右键:5 弹起右键:6 双击左键:7
    :return:
    """


def move_mouse(point: _Point_Tuple) -> bool:
    """
    移动鼠标
    :param point: 坐标点
    :return:
    """


def scroll_mouse(offset_x: float, offset_y: float, x: float = 0, y: float = 0) -> bool:
    """
    滚动鼠标
    :param offset_x: 水平滚动条移动的距离
    :param offset_y: 垂直滚动条移动的距离
    :param x: 鼠标横坐标位置， 默认为0
    :param y: 鼠标纵坐标位置， 默认为0
    :return:
    """


def click_mouse_by_element(xpath: str, typ: int) -> bool:
    """
    根据元素位置点击鼠标(元素中心点)
    :param xpath: 元素 xpath 路径
    :param typ: 点击类型，单击左键:1 单击右键:2 按下左键:3 弹起左键:4 按下右键:5 弹起右键:6 双击左键:7
    :return:
    """


def move_to_element(xpath: str) -> bool:
    """
    移动鼠标到元素位置(元素中心点)
    :param xpath: 元素 xpath 路径
    :return:
    """


def scroll_mouse_by_element(xpath: str, offset_x: float, offset_y: float) -> bool:
    """
    根据元素位置滚动鼠标
    :param xpath: 元素路径
    :param offset_x: 水平滚动条移动的距离
    :param offset_y: 垂直滚动条移动的距离
    :return:
    """

Alert

def click_alert(accept: bool, prompt_text: str) -> bool:
    """
    点击警告框
    :param accept: 确认或取消
    :param prompt_text: 警告框文本
    :return:
    """


def get_alert_text() -> Optional[str]:
    """
    获取警告框文本
    :return: 警告框文本字符串
    """

窗口操作

def get_window_pos():
    """
    获取窗口位置和状态
    :return: 返回窗口左上角坐标点，宽度和高度，状态
    """


def set_window_pos(left: float, top: float, width: float, height: float, status) -> bool:
    """
    设置窗口位置和状态
    :param left: 窗口 x 坐标
    :param top: 窗口 y 坐标
    :param width: 宽度
    :param height: 高度
    :param status: 状态
    :return:
    """


def mobile_emulation(width: int, height: int, ua: str, _sys: Literal["Android", "iOS"], sys_version: str,
                         lang: str = "", tz: str = "", latitude: float = 0, longitude: float = 0,
                         accuracy: float = 0) -> bool:
    """
    模拟移动端浏览器
    :param width: 宽度
    :param height: 高度
    :param ua: 用户代理
    :param _sys: 系统
    :param sys_version: 系统版本
    :param lang: 语言
    :param tz: 时区
    :param latitude: 纬度
    :param longitude: 经度
    :param accuracy: 准确度
    :return:
    """

Cookies

def get_cookies(url: str) -> Optional[list]:
    """
    获取指定 url 的 Cookies
    :param url: url 字符串
    :return:
    """


def get_all_cookies() -> Optional[list]:
    """
    获取所有的 Cookies
    :return: 列表格式的 cookies
    """


def set_cookies(url: str, name: str, value: str, options: dict = None) -> bool:
    """
    设置指定 url 的 Cookies
    :param url: 要设置 Cookie 的域
    :param name: Cookie 名
    :param value: Cookie 值
    :param options: 其他属性
    :return:
    """


def delete_cookies(name: str, url: str = "", domain: str = "", path: str = "") -> bool:
    """
    删除指定 Cookie
    :param name: 要删除的 Cookie 的名称
    :param url: 删除所有匹配 url 和 name 的 Cookie
    :param domain: 删除所有匹配 domain 和 name 的 Cookie
    :param path: 删除所有匹配 path 和 name 的 Cookie
    :return:
    """


def delete_all_cookies() -> bool:
    """
    删除所有 Cookie
    :return:
    """


def clear_cache() -> bool:
    """
    清除缓存
    :return:
    """

JS 注入

def execute_script(script: str) -> Optional[Any]:
    """
    注入执行 JS
    :param script: 要执行的 JS 代码
    :return: 假如注入代码有返回值，则返回此值，否则返回 None;

    result = execute_script('(()=>"aibote rpa")()')
    print(result)  # "aibote rpa"
    """

浏览器操作

def quit() -> bool:
    """
    退出浏览器
    :return:
    """

驱动程序相关

def get_extend_param() -> Optional[str]:
    """
    获取WebDriver.exe 命令扩展参数
    :return: WebDriver 驱动程序的命令行["extendParam"] 字段的参数
    """


def close_driver(self) -> bool:
    """
    关闭WebDriver.exe驱动程序
    :return:
    """