辅助API

辅助API提炼和扩展了Android系统的原生辅助API,极大地降低了使用辅助功能的难度。findViewclickclickByTaggestureClickback2PageswitchPagepastepasteByTagscrollgesturebackrecentAppshomeopenPowerDialogopenNotificationrefresh

node对象

UI控件对象,每个UI元素都应对一个node对象(以下很多函数都会用到这个对象)。node对象的parent和child均为node对象,findView函数返回的结果中的views属性为node数组。
属性名 类型 说明
id string 控件id
text string 控件文本
className string 类名
size/length integer 子控件个数
visible boolean 控件是否可见
clickable boolean 控件是否可点击
checked boolean 控件是否被选中
enabled boolean 控件是否可用
parent node 父控件
height integer 控件高,单位像素
width integer 控件宽,单位像素
left integer 控件左边距离屏幕最左边距离,单位像素
top integer 控件上边距离屏幕最上边距离,单位像素
right integer 控件右边距离屏幕最左边距离,单位像素
bottom integer 控件下边距离屏幕最上边距离,单位像素

findView

通过UI控件的id、text、className等属性来找到控件(进入「移动端」/「我的设备」,点击对应设备的"获取UI树"即可获取当前页面的控件的所有信息),返回值为json对象,包含tag和views两个key,如果没找到则对象的length为0,tag为匹配到的tag, views为找到的Node数组,例:{tag:'hello', views:[node1, node2]}。注意默认找到一个就返回,若需找到所有满足条件的控件则添加flag:find_all
参数:
参数名 类型 默认值 说明
tag string 必填 UI控件的id、text或者className,用|分割多个tag,找到任意一个就成功。前缀,id:表示精确搜索id为tag的控件,id$:表示搜索id以tag结尾的控件,id^:表示搜索id以tag开始的控件,id*:表示搜索id包含tag的控件。txt:表示精确搜索text为tag的控件,txt$:表示搜索text以tag结尾的控件,txt^:表示搜索text以tag开始的控件,txt*:表示搜索text包含tag的控件。cn:表示精确搜索className为tag的控件。注意:一个tag内部可以用@链接多个tag,表示必须同时满足才可以。例:findView('txt:hello@cn:android.view.View|id:app');表示搜索text为hello且className为cn:android.view.View的控件,或者id为app的控件。
options json object {flag:'', root:null, duration:500, maxStep:5, beforeWait:0, afterWait:0, failed: null} flag支持clickable(搜索clickable为true的控件)、unclickable(搜索clickable为false的控件)、traverse_one_by_one(每个tag搜索一遍,效率有点低,当无法搜索到控件时可以使用这个flag)、find_all(搜索所有满足条件的控件)、traverse_invisible(搜索包含不可见的控件,当无法搜索到控件时可以使用这个flag),用|分割多个flag,例:findView('txt^:hello', {flag:'find_all|traverse_invisible|clickable'});表示搜索clickable为true、text以hello开头的所有控件,搜索时包含不可见的控件。root表示搜索时指定的根控件,root为null时,从顶端开始搜索,若指定root,则搜索会更精确效率更高。duration表示两次搜索的间隔时间,单位毫秒。maxStep表示当搜索失败时,重搜索的最大次数。beforeWait表示在搜索前等待的时间,单位毫秒。afterWait表示在搜索完成后等待的时间,单位毫秒。failed表示搜索控件失败后调用的函数,主要用于在操作期间出现弹窗的场景。

click

点击某个UI控件。返回boolean类型。
参数:
参数名 类型 默认值 说明
node Node对象 必填 UI控件的对象,findView函数可以返回node对象。
options json object {click:false, random:true, clickCount:1, beforeWait:0, afterWait:0} click表示是否使用UI的控件原生的click功能,false表示使用手势模拟点击。random表示模拟点击时,是否使用随机位置,不随机则为中点位置。clickCount表示点击次数,默认点击一次,2表示双击。其它选项如上。

clickByTag

通过UI控件的id、text、className来找到控件并点击,返回值为boolean。(进入「移动端」/「我的设备」,点击对应设备的"获取UI树"即可获取当前页面的控件的所有信息)
参数:
参数名 类型 默认值 说明
tag string 必填 如上。
options json object {click: false, flag:'', root:null, duration:500, maxStep:5, beforeWait:0, afterWait:0} click表示是否使用UI控件原生的click功能,false表示使用手势模拟点击。其它选项如上。

gestureClick

通过手势点击屏幕任何位置。
参数:
参数名 类型 默认值 说明
x float 必填 点击区域的x坐标
y float 必填 点击区域的y坐标
options json object {unit:'px', duration:100, beforeWait:0, afterWait:0} unit表示坐标的单位,默认为像素(px),可以取dp,percent,px,控件的尺寸(px单位)可以在UI树中获取;dp为设备无关单位,换算公式为:px=dp*rsDensity;percent,取[0-1],表示为屏幕宽或高成比例,换算公式:宽(px)=rsScreenWidth*x,高(px)=rsScreenHeight*y。duration表示多长时间完成一次点击,单位:毫秒。其它选项如上。

back2Page

多次调用bac函数,返回到目标页面。通过id,text或者className来判断是否已经返回了目标页面。
参数:
参数名 类型 默认值 说明
tag string 必填 如上。
options json object {backFirst: true, failed: null, flag:'', root:null, duration:500, maxStep:5, beforeWait:0, afterWait:0} backFirst表示是否先back再找ui控件。failed表示搜索目标控件失败后调用的函数,主要用于在back过程中出现弹窗的场景。其它选项如上。

switchPage

切换页面,通过findTag找ui控件,若找到则点击该控件,然后通过checkTag来判断新的控件是否出现,如果出现则页面切换成功。 返回json object,对象的length大于0表示成功,否则失败,tag属性表示是否成功,views属性为切换成功后找到的NodeObject数组。
参数:
findTag string 必填 如上。
checkTag string 必填 如上。
options json object {findFlag: '', descendant: [], checkFlag: '', click: false, failed: null, duration:500, maxStep:5, beforeWait:0, afterWait:0} descendant为整型数组表示find到的后代index,-1表示父控件,例:descendant:[-1, 1, 0]等价于node.parent[1][0],node为find到的控件。findFlag和checkFlag分别表示两次寻找控件的flag。click表示找到控件后是否使用原生的点击功能。failed表示搜索控件失败后调用的函数,主要用于在操作过程中出现弹窗的场景。其它选项如上。

paste

粘贴文本。
参数:
参数名 类型 默认值 说明
node editText对象 必填 editText对象
data string 必填 粘贴的数据
options json object {type: 'set', beforeWait: 0, afterWait: 0} type表示粘贴类型,默认为set,可选set、paste。其它选项如上。

pasteByTag

通过tag找到控件,然后粘贴文本,返回boolean。
参数:
参数名 类型 默认值 说明
tag string 必填 如上。
data string 必填 粘贴的数据
options json object {type: 'set', flag:'', root:null, duration:500, maxStep:5, beforeWait: 0, afterWait: 0} 如上。

scroll

滚动屏幕。返回值为boolean。
参数:
参数名 类型 默认值 说明
direction string 必填 滚动方向,up向上滚动,down向下滚动
options json object {root: null, type: 1, distance: 0.8, duration: 500, beforeWait: 0, afterWait: 0} root表示滚动的控件,如果为null则表示使用手势全局滚动。type表示滚动类型,1手势滚动,2使用系统翻页,3表示先使用系统翻页再立马使用手势滚动。distance表示每次滑动的距离,取值(0-1],1表示整个控件高度。duration表示完成滚动的时间,单位:毫秒。其它选项如上。

gesture

手势操作。在duration时间内,快速依次连接所有点,模拟手势移动。
参数:
参数名 类型 默认值 说明
cordArray json array 必填 偶数个点的坐标为浮点型,依次顺序排列:x1,y1,x2,y2...
options json object {unit: 'px', duration: 300, beforeWait: 0, afterWait: 9} 示坐标的单位,默认为像素(px),可以取dp,percent,px,控件的尺寸(px单位)可以在UI树中获取;dp为设备无关单位,换算公式为:px=dp*rsDensity;percent,取[0-1],表示为屏幕宽或高成比例,换算公式:宽(px)=rsScreenWidth*x,高(px)=rsScreenHeight*y。duration表示多长时间完成一次手势操作,单位:毫秒。其它选项如上。

back

模拟返回键。
参数:
参数名 类型 默认值 说明
options json object {count: 1, duration: 1000, beforeWait: 0, afterWait: 0} count表示做几次back,默认1。duration表示两次back间隔时间,默认1000,单位:毫秒。其它选项如上。

recentApps

切换到最近运行的app界面。
参数:
参数名 类型 默认值 说明

home

返回桌面。
参数:
参数名 类型 默认值 说明

openPowerDialog

长按电源键弹出重启,关机对话框。
参数:
参数名 类型 默认值 说明

openNotification

当通知来的时候,打开通知。
参数:
参数名 类型 默认值 说明
event AccessibilityEvent类型object 必填 通知事件。当系统有通知到来时,系统会主动调用rsNotification回调函数,该函数最后一个参数为AccessibilityEvent类型。

refresh

刷新当前运行的app的UI。
参数:
参数名 类型 默认值 说明
options jsonObject {appName: '', packageName: '', beforeWait: 0, afterWait: 0} appName和packageName表示刷新后切换该app,如果都为空,表示切换到智能辅助客户端程序。其它选项如上。
Copyright © 2021 冰狐智能辅助. All rights reserved.