Skip to main content

Python 引擎API

tip

本文档主要用于归纳讲解以及新手速成, 并非所有函数, 查看Python 引擎API(由sphinx生成) 查阅所有函数以及类定义

info

[进阶]软件采用模块化思想进行设计, 几乎所有函数都为rpc(远程接口)调用, 为了序列化与rpc接口定义的便利, 与自动化引擎通讯所有参数以及结果将会转为字符串

调试相关​

engine_set_debug() # 打印引擎接口日志

界面交互​

# 注意此操作需要调动应用函数, 需要打开“后台弹出界面”权限
toast("提示")

触控操作​

# 点击滑动函数技术实现细节：使用adb激活引擎则直接反射系统函数模拟手工点击写入事件(需要打开adb点击功能), 若使用root激活则把事件直接写到系统内核层, 避开某些自动化检测！
# 点击坐标点400, 500
click(400, 500)
# 滑动 从(100,100) 滑动到 (500, 600) 耗时 1.2秒
# 为了使滑动轨迹过风控, 我们可以进行一些随机性的滑动, 即加上is_ramdom参数
swipe(100, 100, 500, 600, 1200, is_ramdom=True)
swipe_up()    # 往上滑动
swipe_down()  # 往下滑动
swipe_left()  # 往左滑动
swipe_right() # 往右滑动


# 设置引擎 使用内核点击 全局生效 (需要 root 权限)
ensure_kernel_click()
cancel_kernel_click()

# 如果需要长按, 或者自定义滑动操作的轨迹, 可以使用; 一个完整的滑动事件是由一个按下与若干个移动操作与一个手指弹起事件组成
EngineDebug._press_down()
EngineDebug._press_move()
EngineDebug._press_up()

按键与输入​

key_code()    # 注入按键
key_confirm() # 确认搜索
key_home()    # 回到主页
key_back()    # 返回
key_menu()    # 菜单键或后台任务

set_yy_input_enable() # 启用或禁用YY 输入法

# 往编辑框输入文本, 支持中文, 往往配合key_confirm()使用
# 比如你需要在抖音搜索 红烧肉怎么做好吃？  如果你不需要使用中文输入, 使用input_text即可
x_input_text("红烧肉怎么做好吃?")
x_input_clear() # 清空编辑框文本

set_text() # 对上面函数进行封装从而进行编辑框输入

# 复制文本到粘贴板📋
set_clipboard("早上好")

# 获取粘贴板文本📋
get_clipboard()

打开应用与链接​

使用例子
# 根据包名打开应用
open_app(pkg_name)
# 打开浏览器, 跳到某网站
open_url(link)

设备信息​

# 获取屏幕尺寸大小
# ⚠️ 注意:竖屏与横屏返回的数值在屏幕发生旋转时候不一样, 比如竖屏时候, 返回(1080, 1920); 在横屏时候, 返回(1920, 1080), 我们在使用百分比坐标系统时候尤其需要注意这一点
device_get_screen_size() 

# 获取设备硬件标识码, 每台手机获取到的都不一样, 重启刷机不发生变化
device_code()

# 获取手机型号
device_model()

# 网络是否在线
is_net_online()

shell("getprop ro.build.version.sdk") # 获取安卓版本号

# 当前手机是否打开调试模式
shell("settings get global adb_enabled") == "1"

# 打开手机调试模式
shell("settings put global development_settings_enabled 1 && settings put global adb_enabled 1")

# 列出手机所有安装的app的包名
shell("pm list packages")

应用运行​

# 获取前台应用信息, 对于自动化脚本来说非常重要
# 当前应用包名, 应用activity名(注意有时候是缩写, 有时候是全称), 进程pid
device_foreground()
# 返回当前前台活动界面名
device_foreground_activity()
# 返回当前前台报名
device_foreground_package()

# 判断当前应用是否在后台运行
is_app_running()

# 将后台应用拉回前台运行
bring_app_to_top()

# 当前是否在某个应用界面内
is_in_app()

# 停止与关闭应用
stop_app()

图色识别与定位​

# ocr文本识别, yolo目标检测, 基于深度学习的识别
screen_ocr(use_gpu=True) # 默认使用gpu加速运算
image_ocr(image_path)
screen_yolo_locate(use_gpu=True) # 默认使用gpu加速运算
model_yolo_reload(ncnn_bin_path, nacc_param_path)


# 使用ocr判断元素文字是否存在
ocr_exists_all()
ocr_exists_any()

# 对一张图像进行多次匹配
match_images()

# 找色(同时支持单点, 多点, 与反色)
find_color()

# 查色
"""
查找到颜色后, 我们可以使用Color.similarity_to()计算颜色相似度, 从而定位信息或者获取目标.
"""
get_color(399, 400) # 查询单个坐标的颜色
get_multi_color([(300, 452), (534, 223)]) # 查询多个坐标的颜色


# 图片相似度 常见用法是截两张图, 对比两张图片的相似度判断画面的变化
image_similarity("/sdcard/1.jpg", "/sdcard/2.jpg") # 返回0-100的浮点数, 数字越大, 图片越相似

# 截图
screen_shot("/sdcard/screen.png")
"""
目标定位函数之一找图
暂不支持多分辨率找图, 且不提倡多分辨率找图, 而是提倡你截多点图片进行适配（本系统致力于稳定性, 这与稳定性相悖）
与其它脚本引擎找图不一样的是, 你可以同时在很短的时间内查找100张图, 并给这100张图特征匹配的置信率, 综合图片置信率进行获取界面信息判断
"""
# 全部查找图片
screen_find_images("/sdcard/1.png;/sdcard/2.png")
# 限定范围的图片查找 x y w h, 可为百分比形式, 可为像素模式, 可缺省其它参数
screen_find_images("/sdcard/1.png;/sdcard/2.png", y=0.5) # 从屏幕下方开始寻找
screen_find_images("/sdcard/1.png;/sdcard/2.png", y=960) # 从屏幕中间往下开始寻找, 若分辨率 h=1920
screen_find_images("/sdcard/1.png;/sdcard/2.png", y=960, h=0.2, x=100) # 从屏幕中间往下(1920*0.2)高度, 左边100像素开始寻找, 若分辨率 h=1920
# 三个screen查找系列函数都支持指定范围定位

# 使用相对目录
screen_find_image_x(("img/1.jpg",))
find_image_click("img/1.jpg", min_prob=0.8) # 如果查找到1.jpg 图片, 则进行点击, 限制图片最低相似度为0.8

节点与控件抓取​

🥴与其它脚本引擎不一样的是

1.你会使用一堆函数去匹配控件, 这样代码非常凌乱
2.在控件信息中增加parent-count, child-count, drawing-order这三个属性

😏Yyds.Auto精心设计了一套超级强大的控件查找机制, 只要结合多种特征就定位一个元素, 成功找到它所在的位置, 最后转换为坐标进行操作。

以下是支持的匹配规则

  1. 使用正则(适用java正则)
  2. 使用范围限定(可使用大于小于号进行数值限定)
  3. 结合父子兄关系进行定位
    • 所有父节点 以par_开头
    • 所有兄节点 以sib_开头
    • 所有子节点 以chi_开头
  4. 使用控件尺寸进行定位, 支持 > 与 <范围
    • width 宽
    • height 高
  5. 限制控件屏幕方位
    • top 上
    • bottom 下
    • left 左
    • right 右
# 重点!‼️使用ui_match函数, 传入多少的参数以为着需要同时匹配多少个条件

ui_match(match_params)
ui_match(text="我*")  # 使用正则进行匹配
ui_match(text="我的") # 如果只使用一个属性就能定位到唯一元素, 就只用它最好了
ui_match(context_desc="资讯", drawing_order="2") # 因为python中变量命名无法包含横杠-, 所以使用_代替, class用class_代替

# 指定范围定位可以大大提高精确率以及查找速度
ui_match(text="我的", top=0.5, width=">10") # 结合位置, 大于进行定位, top=0.5意思是从屏幕中间往下开始找, width>10 意思是控件的宽大于10
ui_match(text="我.*", sid_class_="android.widget.ImageView") # 结合方位与父子节点的匹配, sid_class_即表示是否存在任一兄弟节点的class=android.widget.ImageView, 一般就是文字旁边有张图片

ui_match(text="\\*") # !! ⚠️ 所有text内容转换为正则进行匹配 如果你要的text内容是 * 你应该写成
ui_match(text=".+", top=0.5) # 匹配屏幕中间以下的所有text不为空的控件

ui_match(resource_id="com.yyds.auto:id/image_icon_con")
# 如果 ui tree 没有改变, 则可以从缓存匹配, 加快匹配速度
ui_match(True, height="<50", width="<50")
ui_exist(match_params) # 控件是否存在

# 类似于执行 uiautomator --dump 命令
ui_dump_xml(path)

# 匹配节点
ui_match(context_desc="快手")

# 获取父节点
ui_parent()
# 获取兄弟节点(旁系节点), 不包括自己
ui_sib()
# 获取子节点
ui_child()

UI配置读取​

若用户未配置ui的值, 则返回读到None

read_config_value()  # 读取配置值
write_config_value() # 写入配置值
read_ui_value()      # 读取ui.yml 文件的 value 值, 用于默认配置操作

APK提取与应用数据备份、还原​

函数原型与说明
app_apk_install()  # 应用安装
app_apk_backup()  # 应用APK备份
app_data_backup() # 应用数据备份
app_data_recovery() # 应用数据还原

Shell(with busybox)​

安卓属于linux系统分支, 天然适合使用shell脚本执行一些简单的任务

拥有busybox你可以运行一些安卓不自带的二进制命令, 并且确保你的shell命令的兼容性, 如使用wget下载一个文件(一般很多系统都没有自带wget的, curl倒是常见), busybox犹如一把超级瑞士军刀, 熟练使用shell, 你可以实现很多强大的功能！

😏有些命令需要root权限, 推荐使用Yyds.Msu

# 通过shell调用系统服务获取imei
shell("service call iphonesubinfo 1 | cut -c 52-66 | tr -d '.[:space:]")

shell("wget -q -O /sdcard/temp.apk https://127.0.0.1/file/temp.apk")
# 或者连接ftp服务器下载一个文件
ftp_user = "admin"
ftp_pass = "123456"
ftp_ip = "192.168.0.2"
ftp_remote_path = "/app/qq.apk" 
ftp_local_path = "/sdcard/qq.apk"
shell(f"ftpget -u {ftp_user} -p ${ftp_pass} {ftp_local_path} {ftp_remote_path}")
# 一般来说, 你想了解一个命令的用法, 你直接不加参数或者加上--help
shell("wget")
# 你还可以运行更复杂的shell脚本, shell天然适合帮你在linux下执行一些任务
shell("""
{
i=0
while [ $i -ne 5 ]
do
        i=$(($i+1))
        echo "$i"
done
} >> /sdcard/log.txt 2&>1
""")
# 如果你使用adb激活, 则你的shell命令权限为shell(uid=2000)；如果你使用root激活, 则你的shell命令权限为root(uid=0)

# 如使用killall强行杀死微信进程
shell("killall com.tencent.mm")

# 更多的busybox命令, 你可以直接运行busybox
# busybox二进制文件来源于magisk
shell("busybox")