冰狐智能辅助 QQ群：693133887
首页
文档&下载
移动端
微服务
社区
码农教程
管理中心
关于我们
登录/注册
辅助和控件操作函数

辅助及控件操作函数是实现自动化脚本的核心函数，它提炼和扩展了Android系统的原生辅助函数，极大地降低了使用辅助功能的难度。launchApp、findView、findRoot、click、gestureClick、multiGestureClick、back2Page、switchPage、switchPages、paste、getWidgetColor、scroll、gesture、back、recentApps、home、openPowerDialog、openNotification、refresh、cbNotification、cbWindowChange。

点击这里查看可直接运行的hello world!程序源码。

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 checkbox控件是否被选中
selected boolean selected控件是否被选中
enabled boolean 控件是否可用
parent node 父控件
height integer 控件高，单位像素
width integer 控件宽，单位像素
left integer 控件左边距离屏幕最左边距离，单位像素
top integer 控件上边距离屏幕最上边距离，单位像素
right integer 控件右边距离屏幕最左边距离，单位像素
bottom integer 控件下边距离屏幕最上边距离，单位像素
prevSibling node对象 上一个兄弟控件
nextSibling node对象 下一个兄弟控件 
例子：
var ret = findView('txt:我的');
if (ret.length > 0) {
    var view = ret.views[0];
    console.log('left:' + view.left);
}

launchApp

启动APP。返回integer值，1表示成功，0表示该app没有安装，-1表示启动失败。
参数：
参数名 类型 必填 说明
packageName/appName string 必填 app名称或者包名
tag string 选填 app启动后首页中出现的某个控件的tag，出现该tag就表示app启动成功。默认为空
options json object 选填 默认值：{flag:'', failed:null, maxStep:30, refresh: true}。flag见findView；failed表示搜索控件失败后调用的函数，主要用于处理在操作期间出现弹窗的场景；maxStep表示检测app是否启动时重试的步数。refresh为true时在启动app过程中会刷新和重新启动app，可以根据具体情况来关闭该选项。 
例子：
var ret = launchApp('com.tencent.mm', 'txt:微信');
if (1 == ret) {
    console.log('启动成功');
}

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（注意@后的tag目前仅支持cn和id的精确表示），表示必须同时满足才可以。例：findView('txt:hello@cn:android.view.View|id:app');表示搜索text为hello且className为cn:android.view.View的控件，或者id为app的控件。（注意：如果tag中包含符号:、@、|、#，则需要转义才可以用，&%0;表示:，&%1;表示@，&%2;表示|，&%3;表示#，例:txt:a&%1;b，表示txt:a@b。）
options json object {flag:'', root:null, fast: false, family: [], region:null, duration:500, maxStep:5, beforeWait:0, afterWait:0, failed: null} flag支持clickable（搜索clickable为true的控件）、unclickable（搜索clickable为false的控件）、selected（搜索selected为true的控件）、unselected（搜索slected为false的控件）、checked（搜索checked为true的控件）、unchecked（搜索checked为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，则搜索会更精确效率更高；注意root也可以为tag。点击查看family「视频教程」。region可以在搜索时指定区域[left, top, right, bottom]，注意：若取值在[0, 1]之间表示比例，例：[0.5, 100, 900, 2000]表示left位于屏幕x轴中点；若取值大于1表示像素值。duration表示两次搜索的间隔时间，单位毫秒。maxStep表示当搜索失败时，重搜索的最大次数。beforeWait表示在搜索前等待的时间，单位毫秒。afterWait表示在搜索完成后等待的时间，单位毫秒。failed表示搜索控件失败后调用的函数，主要用于在操作期间出现弹窗的场景。fast为true时表示快速搜索，如果搜索控件比较慢时使用该参数，注意开启后可能会出现某些文本搜索不到，具体使用时注意观察。 
例子：
var ret = findView('txt:确认', {flag:'find_all'});
if (ret.length > 0) {
    console.log('找到目标控件:' + ret.views[0]);

    // 注意：控件个数为ret.views.length不是ret.length
    console.log('找到控件个数:' + ret.views.length);
}

findRoot

通过tag或者index来寻找UI的根容器，返回界面的NodeObject对象。由于android系统在一个UI上除了主界面外，还有很多其他根界面（也即有多个根界面），比如输入法界面，状态栏，某个悬浮的界面等。一般情况下默认我们都是直接使用主界面，如果我们想要操作其他界面时，就需要用到findRoot，通过界面中的某个独特的tag来定位这个界面，然后在后续的操作中把找到的界面作为root。注意:可以先在ui树中查找根控件，通过改变ui树右上角的“根索引”（可以取值：0，1，2，3，4，5等整数值）来快速查看，每个不同的取值表示不同的根界面。
参数：
参数名 类型 默认值 说明
tag string/integer 必填 当为string类型时表示tag如上。，当为integer类型时表示第几个根界面
options json object {duration:500, maxStep:5, beforeWait:0, afterWait:0} duration表示两次搜索的间隔时间，单位毫秒，默认500ms。maxStep表示当搜索失败时重搜索的最大次数，默认5。beforeWait表示在搜索前等待的时间，单位毫秒，默认0。afterWait表示在搜索完成后等待的时间，单位毫秒，默认0。 
例子：
var root = findRoot('txt:数字键盘');
if (null != root) {
    console.log('找到根容器:' + root);
    // 在root下查找tag为good的控件
    var ret = findView('txt:good', {root: root});
}

root = findRoot(1);
if (null != root) {
    console.log('找到根容器:' + root);
}

click

点击控件,返回值为boolean。(进入「移动端」/「我的设备」，点击对应设备的"UI树"即可获取当前页面的控件的所有信息)
参数：
参数名 类型 默认值 说明
tag/node object string/object 必填 tag如上。或者控件对象
options json object {click: false, isLongClick: false, clickDuration: -1, fast: false, random: true, clickCount:1, flag:'', family: [], region:null, root:null, widgetIndex:0, failed:null, duration:500, maxStep:5, beforeWait:0, afterWait:0} 点击查看family「视频教程」。click表示是否使用UI控件原生的click功能，false表示使用手势模拟点击，注意使用控件内置原生点击功能的前提是控件的clickable属性必须为true，或者其某一个祖先控件的clickable属性为true。random表示模拟点击时，是否使用随机位置，不随机则为中点位置。clickCount表示点击次数，默认点击一次，2表示双击。widgetIndex表示点击搜索到的第几个控件，默认为0，0表示第一个，-1表示最后一个依次类推。当为模拟点击时clickDuration有效，表示点击动作的时长。其它选项如上。 
例子：
var ret = findView('txt:确定');
if (ret.length > 0) {
    click(ret.views[0], {click: true, afterWait: 3000});
}

click('txt:确定', {click: true, afterWait: 3000});

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表示多长时间完成一次点击，单位：毫秒。其它选项如上。 
例子：
gestureClick(100, 200, {afterWait: 3000});

multiGestureClick

多点手势点击。在duration时间内，快速同时模拟点击n个点。
参数：
参数名 类型 默认值 说明
cordArray json array 必填 偶数个点的坐标为浮点型，依次顺序排列:x1,y1,x2,y2...
options json object {unit: 'px', duration: 300, 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表示多长时间完成一次手势操作，单位：毫秒。其它选项如上。 
例子：
// 同时点击坐标(10,10) (20, 20)
gesture([10, 10, 20, 20], {duration: 1000, afterWait: 2000});

back2Page

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

switchPage

切换页面，通过findTag找ui控件，若找到则点击该控件，然后通过checkTag来判断新的控件是否出现，如果出现则页面切换成功。 返回json object，对象的length大于0表示成功，否则失败;tag属性表示成功时找到的checkTag,views属性为切换成功后找到的NodeObject数组。
参数：
参数名 类型 默认值 说明
findTag/node object string/object 必填 tag如上。或者为ui控件对象
checkTag string 必填 如上。
options json object {findFlag: '', family: [], region: null, checkFlag: '', click: false, root:null, clickWidgetIndex: 0, failed: null, duration:500, random: true, maxStep:5, maxFindStep:1, maxCheckStep:2, beforeWait:0, afterWait:0} findFlag和checkFlag分别表示两次寻找控件的flag。点击查看family「视频教程」。click表示找到控件后是否使用原生的点击功能，注意使用控件内置原生点击功能的前提是控件的clickable属性必须为true，或者其某一个祖先控件的clickable属性为true。failed表示搜索控件失败后调用的函数，主要用于在操作过程中出现弹窗的场景。clickWidgetIndex，默认为0，0表示第一个，-1表示最后一个依次类推。其它选项如上。maxFindStep表示搜索findTag时最大尝试次数，maxCheckStep表示搜索checkTag时最大尝试次数，maxStep表示切换页面最大尝试次数。duration表示点击后等多长时间后开始检查是否切换到目标页面。 
例子：点击'我的'，进入关于我的页面，如果页面中包含tag：'设置'，说明进入新页面成功。
var ret = switchPage('txt:我的', 'txt:设置', {maxStep: 6, maxFindStep: 1, maxCheckStep: 5});
if (ret.length > 0) {
    console.log('进入页面成功');
}

var ret = findView('txt:test');
if (ret.length > 0) {
    var item = ret.views[0];
    var ret = switchPage(item, 'txt:设置', {maxStep: 3, maxCheckStep: 5});
    if (ret.length > 0) {
        console.log('进入页面成功');
    }
}

switchPages

切换多个页面，将多个switchPage操作集成在一起，适合连续切换多个页面场景。返回整型数，2表示第1个和2个切换页面成功后面的失败，依次类推。
参数：
参数名 类型 默认值 说明
params array 必填 每个数组元素为一个数组，表示一个switchPage的参数（具体参数如上） 
例子：切换3个页面，若返回2表示第1和第2个页面切换成功，后面的切换失败；若返回3，表示页面切换全部成功。
var ret = switchPages([['txt:我的', 'txt:设置'],['txt:我', 'txt:新闻', {click: true}],['txt:set', 'txt:add', {family:[0, -1]}]]);
console.log('ret', ret);

paste

粘贴文本，设置文本，返回boolean。
参数：
参数名 类型 默认值 说明
tag/node object string/object 必填 tag如上。或者控件对象
data string 必填 粘贴的数据
options json object {type:'set', flag:'', family: [], region: null, fast: false, root:null, widgetIndex: 0, failed:null, duration:500, maxStep:5, beforeWait: 0, afterWait: 0} 点击查看family「视频教程」。type值为：'set' 或者 'paste'。 widgetIndex表示点击搜索到的第几个控件，默认为0，0表示第一个，-1表示最后一个依次类推。其它选项如上。 
例子：
var ret = findView('cn:com.android.EditText');
if (ret.length > 0) {
    paste(ret.views[0], '谢谢！', {afterWait: 3000});
}

paste('cn:com.android.EditText', '谢谢！', {afterWait: 3000});

getWidgetColor

通过tag找到控件，然后获取控件某点的颜色，默认获取控件中点的颜色值，返回整型值。注意：第一次调用前必须先申请截屏权限
参数：
参数名 类型 默认值 说明
tag/node object string/object 必填 tag如上。或者控件对象
options json object {flag:'', family: [], region: null, root:null, fast: false, widgetIndex: 0, failed:null, duration:500, maxStep:5, beforeWait: 0, afterWait: 0} 点击查看family「视频教程」。widgetIndex表示点击搜索到的第几个控件，默认为0，0表示第一个，-1表示最后一个依次类推。其它选项如上。
x integer 选填 相对控件的x坐标，默认取控件中心点
y integer 选填 相对控件的y坐标，默认取控件中心点 
例子：获取控件中心的颜色值
function main() {
    requestScreenShot();

    var ret = findView('txt:name');
    if (ret.length > 0) {
        var color = getWidgetColor(ret.views[0]);
        console.log('color:' + color);
    }

    var color = getWidgetColor('txt:name');
    console.log('color:' + color);
}

scroll

滚动。返回值为boolean。
参数：
参数名 类型 默认值 说明
tag/node object string/object 必填 控件tag或者控件对象。null表示以整个屏幕作为参考进行滚动。
direction string 必填 滚动方向，up向上滚动，down向下滚动，left向左滚动，right向右滚动
options json object {flag:'', family: [], fast: false, root: null, widgetIndex: 0, type: 1, distance: 0.8, duration: 500, beforeWait: 0, afterWait: 0} root表示搜索tag时使用root作为根控件搜索，若为null则全局搜索。type表示滚动类型，1手势滚动，2使用系统翻页，3表示先使用系统翻页再立马使用手势滚动。distance表示每次滑动的距离，取值(0-1]，1表示整个控件高度（左、右滚动时为宽度）。duration表示完成滚动的时间，单位：毫秒。widgetIndex表示点击搜索到的第几个控件，默认为0，0表示第一个，-1表示最后一个依次类推。其它选项如上。 
例子：
scroll('id:com.libra.wxhelper:id/device_name', 'up', {type: 2, distance: 0.95, afterWait: 3000});

gesture

手势操作。在duration时间内，快速依次连接所有点，模拟手势移动。
参数：
参数名 类型 默认值 说明
cordArray json array 必填 偶数个点的坐标为浮点型，依次顺序排列:x1,y1,x2,y2...。或者为数组，数组中为具体的坐标值，可以模拟多个手指同时滑动，比如：放大、缩小等操作。
options json object {unit: 'px', duration: 300, 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表示多长时间完成一次手势操作，单位：毫秒。其它选项如上。 
例子：
gesture([10, 10, 20, 20, 30, 55], {duration: 1000, afterWait: 2000});

// 地图，模拟手指来缩小
gesture([[ 650, 300, 600, 300], [450, 300, 500, 300]])

back

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

recentApps

切换到最近运行的app界面。
参数：
参数名 类型 默认值 说明 
例子：
recentApps();

home

返回桌面。
参数：
参数名 类型 默认值 说明 
例子：
home();

openPowerDialog

长按电源键弹出重启，关机对话框。
参数：
参数名 类型 默认值 说明 
例子：
openPowerDialog();

openNotification

当通知来的时候，打开通知。
参数：
参数名 类型 默认值 说明
event AccessibilityEvent类型object 必填 通知事件。当系统有通知到来时，系统会主动调用cbNotification回调函数，该函数最后一个参数为AccessibilityEvent类型。 
例子：
openNotification(event);

refresh

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

cbNotification

通知事件回调函数。开发者可以脚本的最外层实现该函数，当操作系统收到通知时，系统会自动调用该函数。注意：如果有自定义ui，请不在ui代码中使用，请在任务（runTask）代码中使用。
参数：
参数名 类型 默认值 说明
textList array [] 通知中的文本数组
className string 空 当前窗口的类名
packageName string 空 app的包名
rawEvent object null raw事件 
例子：
function main() {
    console.log('enter main');
}

function cbNotification(textList, className, packageName, rawEvent) {
    console.log('=====>notification textList:' + textList + '  className:' + className + '  packageName:' + packageName);
}

cbWindowChange

窗口改变事件回调函数。开发者可以脚本的最外层实现该函数，当窗口改变时（包括toast），系统会自动调用该函数。
参数：
参数名 类型 默认值 说明
textList array [] 当前窗口中的文本数组
className string 空 当前窗口的类名
packageName string 空 app的包名
rawEvent object null raw事件 
例子：注意不支持调试执行，需要直接执行脚本才可以
function main() {
    console.log('enter main');
}

function cbWindowChange(textList, className, packageName, rawEvent) {
    console.log('=====>windowChange textList:' + textList + '  className:' + className + '  packageName:' + packageName);
}