autojs 开发文档集合

加入我们的QQ群553908361,和各作者同群交流
教程会优先发布于收费脚本v群。
该代码选自于aj开发者的文档,群里有人反馈开发文档打开慢.所以做了这个.方便搜索.如有侵权,请私信我进行删除

同时也上传了一份源码到点击网站,供大家更快的查询代码

Auto.js Pro-8.1.0 文档
索引 | 查看全部

综述 Q & A 如何定时运行脚本定时任何如何获取外部参数如何把图片和脚本一起打包，或者打包多个脚本如何使打包的应用不显示主界面
Auto.js自带的模块和函数中没有的功能如何实现 App app.versionCode app.versionName
app.autojs.versionCode app.autojs.versionName app.launchApp(appName)
app.launch(packageName) app.launchPackage(packageName)
app.getPackageName(appName) app.getAppName(packageName)
app.openAppSetting(packageName) app.viewFile(path)
app.editFile(path) app.uninstall(packageName) app.openUrl(url)
app.sendEmail(options) app.startActivity(name) 进阶: 意图Intent
app.intent(options) app.startActivity(options)
app.sendBroadcast(options) app.startService(options)
app.sendBroadcast(name) app.intentToShell(options) app.parseUri(uri)
app.getUriForFile(path) app.getInstalledApps([options]) Console
console.show() console.hide() console.clear() console.log([data][,
…args]) console.verbose([data][, …args]) console.info([data][,
…args]) console.warn([data][, …args]) console.error([data][,
…args]) console.assert(value, message) console.time([label])
console.timeEnd(label) console.trace([data][, …args])
console.input(data[, …args]) console.rawInput(data[, …args])
console.setSize(w, h) console.setPosition(x, y)
console.setGlobalLogConfig(config) print(text) 基于坐标的触摸模拟
setScreenMetrics(width, height) 安卓7.0以上的触摸和手势模拟 click(x, y)
longClick(x, y) press(x, y, duration) swipe(x1, y1, x2, y2,
duration) gesture(duration, [x1, y1], [x2, y2], …)
gestures([delay1, duration1, [x1, y1], [x2, y2], …], [delay2,
duration2, [x3, y3], [x4, y4], …], …) RootAutomator
RootAutomator.tap(x, y[, id]) RootAutomator.swipe(x1, x2, y1, y2[,
duration, id]) RootAutomator.press(x, y, duration[, id])
RootAutomator.longPress(x, y[, id]) RootAutomator.touchDown(x, y[,
id]) RootAutomator.touchMove(x, y[, id]) RootAutomator.touchUp([id])
使用root权限点击和滑动的简单命令 Tap(x, y) Swipe(x1, y1, x2, y2, [duration])
Crypto $crypto.digest(message, algorithm[, options])
$crypto.encrypt(data, key, algorithm, options) 输入和输出的类型和格式 Device
device.width device.height device.buildId device.broad device.brand
device.device deivce.model device.product device.bootloader
device.hardware device.fingerprint device.serial device.sdkInt
device.incremental device.release device.baseOS device.securityPatch
device.codename device.getIMEI() device.getAndroidId()
device.getMacAddress() device.getBrightness()
device.getBrightnessMode() device.setBrightness(b)
device.setBrightnessMode(mode) device.getMusicVolume()
device.getNotificationVolume() device.getAlarmVolume()
device.getMusicMaxVolume() device.getNotificationMaxVolume()
device.getAlarmMaxVolume() device.setMusicVolume(volume)
device.setNotificationVolume(volume) device.setAlarmVolume(volume)
device.getBattery() device.isCharging() device.getTotalMem()
device.getAvailMem() device.isScreenOn() device.wakeUp()
device.wakeUpIfNeeded() device.keepScreenOn([timeout])
device.keepScreenDim([timeout]) device.cancelKeepingAwake()
device.vibrate(millis) device.cancelVibration() Dialogs
dialogs.alert(title[, content, callback]) dialogs.confirm(title[,
content, callback]) dialogs.rawInput(title[, prefill, callback])
dialogs.input(title[, prefill, callback]) dialogs.prompt(title[,
prefill, callback]) dialogs.select(title, items, callback)
dialogs.singleChoice(title, items[, index, callback])
dialogs.multiChoice(title, items[, indices, callback])
dialogs.build(properties) Dialog 事件: show 事件: cancel 事件: dismiss 事件:
positive 事件: negative 事件: neutral 事件: any 事件: item_select 事件:
single_choice 事件: multi_choice 事件: input 事件: input_change
dialog.getProgress() dialog.getMaxProgress()
dialog.getActionButton(action) Engines engines.execScript(name,
script[, config]) engines.execScriptFile(path[, config])
engines.execAutoFile(path[, config]) engines.stopAll()
engines.stopAllAndToast() engines.myEngine() engines.all()
ScriptExecution ScriptExecution.getEngine()
ScriptExecution.getConfig() ScriptEngine ScriptEngine.forceStop()
ScriptEngine.cwd() ScriptEngine.getSource()
ScriptEngine.emit(eventName[, …args]) ScriptConfig delay interval
loopTimes getPath() Events events.emitter() events.observeKey()
events.onKeyDown(keyName, listener) events.onKeyUp(keyName,
listener) events.onceKeyDown(keyName, listener)
events.onceKeyUp(keyName, listener)
events.removeAllKeyDownListeners(keyName)
events.removeAllKeyUpListeners(keyName)
events.setKeyInterceptionEnabled([key, ]enabled)
events.observeTouch() events.setTouchEventTimeout(timeout)
events.getTouchEventTimeout() events.onTouch(listener)
events.removeAllTouchListeners() 事件: ‘key’ 事件: ‘key_down’ 事件:
‘key_up’ 事件: 'exit` events.observeNotification()
events.observeToast() 事件: ‘toast’ 事件: ‘notification’ Notification
Notification.number Notification.when Notification.getPackageName()
Notification.getTitle() Notification.getText() Notification.click()
Notification.delete() KeyEvent KeyEvent.getAction()
KeyEvent.getKeyCode() KeyEvent.getEventTime() KeyEvent.getDownTime()
KeyEvent.keyCodeToString(keyCode) keys EventEmitter
EventEmitter.defaultMaxListeners EventEmitter.addListener(eventName,
listener) EventEmitter.emit(eventName[, …args])
EventEmitter.eventNames() EventEmitter.getMaxListeners()
EventEmitter.listenerCount(eventName)
EventEmitter.listeners(eventName) EventEmitter.on(eventName,
listener) EventEmitter.once(eventName, listener)
EventEmitter.prependListener(eventName, listener)
EventEmitter.prependOnceListener(eventName, listener)
EventEmitter.removeAllListeners([eventName])
EventEmitter.removeListener(eventName, listener)
EventEmitter.setMaxListeners(n) events.broadcast: 脚本间广播 Floaty
floaty.window(layout) floaty.rawWindow(layout) floaty.closeAll()
FloatyWindow window.setAdjustEnabled(enabled) window.setPosition(x,
y) window.getX() window.getY() window.setSize(width, height)
window.getWidht() window.getHeight() window.close()
window.exitOnClose() FloatyRawWindow window.setTouchable(touchable)
window.setPosition(x, y) window.getX() window.getY()
window.setSize(width, height) window.getWidht() window.getHeight()
window.close() window.exitOnClose() Files files.isFile(path)
files.isDir(path) files.isEmptyDir(path) files.join(parent, child)
files.create(path) files.createWithDirs(path) files.exists(path)
files.ensureDir(path) files.read(path[, encoding = “utf-8”])
files.readBytes(path) files.write(path, text[, encoding = “utf-8”])
files.writeBytes(path, bytes) files.append(path, text[, encoding =
‘utf-8’]) files.appendBytes(path, text[, encoding = ‘utf-8’])
files.copy(fromPath, toPath) files.move(fromPath, toPath)
files.rename(path, newName) files.renameWithoutExtension(path,
newName) files.getName(path) files.getNameWithoutExtension(path)
files.getExtension(path) files.remove(path) files.removeDir(path)
files.getSdcardPath() files.cwd() files.path(relativePath)
files.listDir(path[, filter]) open(path[, mode = “r”, encoding =
“utf-8”, bufferSize = 8192]) ReadableTextFile
ReadableTextFile.read() ReadableTextFile.read(maxCount)
ReadableTextFile.readline() ReadableTextFile.readlines() close()
PWritableTextFile PWritableTextFile.write(text)
PWritableTextFile.writeline(line)
PWritableTextFile.writelines(lines) PWritableTextFile.flush()
PWritableTextFile.close() 全局变量与函数 sleep(n) currentPackage()
currentActivity() setClip(text) getClip() toast(message)
toastLog(message) waitForActivity(activity[, period = 200])
waitForPackage(package[, period = 200]) exit() random(min, max)
random() requiresApi(api) requiresAutojsVersion(version)
runtime.requestPermissions(permissions) runtime.loadJar(path)
runtime.loadDex(path) context HTTP http.get(url[, options,
callback]) http.post(url, data[, options, callback])
http.postJson(url[, data, options, callback])
http.postMultipart(url, files[, options, callback])
http.request(url[, options, callback]) Response Response.statusCode
Response.statusMessage Response.headers Response.body
Response.request Response.url Response.method colors
colors.toString(color) colors.red(color) colors.green(color)
colors.blue(color) colors.alpha(color) colors.rgb(red, green, blue)
colors.argb(alpha, red, green, blue) colors.parseColor(colorStr)
colors.isSimilar(color2, color2[, threshold, algorithm])
colors.equals(color1, color2) colors.BLACK colors.DKGRAY colors.GRAY
colors.LTGRAY colors.WHITE colors.RED colors.GREEN colors.BLUE
colors.YELLOW colors.CYAN colors.MAGENTA colors.TRANSPARENT Images
图片处理 images.read(path) images.load(url) images.copy(img)
images.save(image, path[, format = “png”, quality = 100])
images.fromBase64(base64) images.toBase64(img[, format = “png”,
quality = 100]) images.fromBytes(bytes) images.toBytes(img[, format
= “png”, quality = 100]) images.clip(img, x, y, w, h) images.resize(img, size[, interpolation]) images.scale(img, fx, fy[,
interpolation]) images.rotate(img, degress[, x, y])
images.concat(img1, image2[, direction]) images.grayscale(img)
image.threshold(img, threshold, maxVal[, type])
images.adaptiveThreshold(img, maxValue, adaptiveMethod,
thresholdType, blockSize, C) images.cvtColor(img, code[, dstCn])
images.inRange(img, lowerBound, upperBound) images.interval(img,
color, interval) images.blur(img, size[, anchor, type])
images.medianBlur(img, size) images.gaussianBlur(img, size[, sigmaX,
sigmaY, type]) images.matToImage(mat) 找图找色
images.requestScreenCapture([landscape]) images.captureScreen()
images.captureScreen(path) images.pixel(image, x, y)
images.findColor(image, color, options)
images.findColorInRegion(img, color, x, y[, width, height,
threshold]) images.findColorEquals(img, color[, x, y, width,
height]) images.findMultiColors(img, firstColor, colors[, options])
images.detectsColor(image, color, x, y[, threshold = 16, algorithm =
“diff”]) images.findImage(img, template[, options])
images.findImageInRegion(img, template, x, y[, width, height,
threshold]) images.matchTemplate(img, template, options)
MatchingResult matches points first() last() leftmost() topmost()
rightmost() bottommost() best() worst() sortBy(cmp) Image
Image.getWidth() Image.getHeight() Image.saveTo(path) Image.pixel(x,
y) Point Point.x Point.y Keys back() home() powerDialog()
notifications() quickSettings() recents() splitScreen() Home()
Back() Power() Menu() VolumeUp() VolumeDown() Camera() Up() Down()
Left() Right() OK() Text(text) KeyCode(code) 附录: KeyCode对照表 Media
media.scanFile(path) media.playMusic(path[, volume, looping])
media.musicSeekTo(msec) media.pauseMusic() media.resumeMusic()
media.stopMusic() media.isMusicPlaying() media.getMusicDuration()
media.getMusicCurrentPosition() module (模块) 基于控件的操作 auto([mode])
auto.waitFor() auto.setMode(mode) auto.setFlags(flags) auto.serivce
auto.windows auto.root auto.rootInActiveWindow
auto.setWindowFilter(filter) auto.windowRoots SimpleActionAutomator
click(text[, i]) click(left, top, bottom, right) longClick(text[,
i])) scrollUp([i]) scrollDown([i]) setText([i, ]text) input([i,
]text) UiSelector selector() UiSelector.algorithm(algorithm)
UiSelector.text(str) UiSelector.textContains(str)
UiSelector.textStartsWith(prefix) UiSelector.textEndsWith(suffix)
UiSelector.textMatches(reg) UiSelector.desc(str)
UiSelector.descContains(str) UiSelector.descStartsWith(prefix)
UiSelector.descEndsWith(suffix) UiSelector.descMatches(reg)
UiSelector.id(resId) UiSelector.idContains(str)
UiSelector.idStartsWith(prefix) UiSelector.idEndsWith(suffix)
UiSelector.idMatches(reg) UiSelector.className(str)
UiSelector.classNameContains(str)
UiSelector.classNameStartsWith(prefix)
UiSelector.classNameEndsWith(suffix)
UiSelector.classNameMatches(reg) UiSelector.packageName(str)
UiSelector.packageNameContains(str)
UiSelector.packageNameStartsWith(prefix)
UiSelector.packageNameEndsWith(suffix)
UiSelector.packageNameMatches(reg) UiSelector.bounds(left, top,
right, buttom) UiSelector.boundsInside(left, top, right, buttom)
UiSelector.boundsContains(left, top, right, buttom)
UiSelector.drawingOrder(order) UiSelector.clickable([b = true])
UiSelector.longClickable([b = true]) UiSelector.checkable([b =
true]) UiSelector.selected([b = true]) UiSelector.enabled([b =
true]) UiSelector.scrollable([b = true]) UiSelector.editable([b =
true]) UiSelector.multiLine([b = true]) UiSelector.findOne()
UiSelector.findOne(timeout) UiSelector.findOnce()
UiSelector.findOnce(i) UiSelector.find() UiSelector.untilFind()
UiSelector.exists() UiSelector.waitFor() UiSelector.filter(f)
UiObject UiObject.click() UiObject.longClick()
UiObject.setText(text) UiObject.copy() UiObject.cut()
UiObject.paste() UiObject.setSelection(start, end)
UiObject.scrollForward() UiObject.scrollBackward() UiObject.select()
UiObject.collapse() UiObject.expand() UiObject.show()
UiObject.scrollUp() UiObject.scrollDown() UiObject.scrollLeft()
UiObject.scrollRight() children() childCount() child(i) parent()
bounds() boundsInParent() drawingOrder() id() text() findByText(str)
findOne(selector) find(selector) UiCollection UiCollection.size()
UiCollection.get(i) UiCollection.each(func) empty() nonEmpty()
UiCollection.find(selector) UiCollection.findOne(selector) Rect
Rect.left Rect.right Rect.top Rect.bottom Rect.centerX()
Rect.centerY() Rect.width() Rect.height() Rect.contains®
Rect.intersect® UiSelector进阶 Sensors sensors.register(sensorName[,
delay]) sensors.unregister(emitter) sensors.unregisterAll()
sensors.ignoresUnsupportedSensor 事件: ‘unsupported_sensor’
SensorEventEmitter 事件: ‘change’ 事件: ‘accuracy_change’ shell函数
shell(cmd[, root]) Shell new Shell(root) Shell.exec(cmd)
Shell.exit() Shell.exitAndWaitFor() Shell.setCallback(callback) 附录:
shell命令简介 am命令 start [options] intent startservice [options] intent
force-stop package kill [options] package kill-all broadcast
[options] intent instrument [options] component dumpheap [options]
process file monitor [options] 启动对崩溃或 ANR 的监控。 screen-compat |
package display-size [reset|widthxheight] display-density dpi
to-uri intent to-intent-uri intent intent参数的规范 URI component package
应用包名 pm命令 list packages [options] filter list permission-groups list
permissions [options] group list instrumentation [options] list
features list libraries list users path package install [options]
path uninstall [options] package clear package enable
package_or_component disable package_or_component disable-user
[options] package_or_component grant package_name permission revoke
package_name permission set-install-location location
get-install-location set-permission-enforced permission [true|false]
trim-caches desired_free_space create-user user_name remove-user
user_id get-max-users 其他命令进行屏幕截图列表文件 Storages
storages.create(name) storages.remove(name) Storages
Storage.get(key[, defaultValue]) Storage.put(key, value)
Storage.remove(key) Storage.contains(key) Storage.clear() Threads
threads.start(action) threads.shutDownAll() threads.currentThread()
threads.disposable() threads.atomic([initialValue]) threads.lock()
Thread Thread.interrupt() Thread.join([timeout]) isAlive() waitFor()
Thread.setTimeout(callback, delay[, …args])
Thread.setInterval(callback, delay[, …args])
Thread.setImmediate(callback[, …args]) Thread.clearInterval(id)
Thread.clearTimeout(id) Thread.clearImmediate(id) 线程安全 sync(func)
线程通信 Timers setInterval(callback, delay[, …args])
setTimeout(callback, delay[, …args]) setImmediate(callback[,
…args]) clearInterval(id) clearTimeout(id) clearImmediate(id)
用户界面: UI 视图: View attr(name, value) attr(name) w h id gravity
layout_gravity margin marginLeft marginRight marginTop marginBottom
padding paddingLeft paddingRight paddingTop paddingBottom bg alpha
foreground minHeight minWidth visibility rotation transformPivotX
transformPivotY style 文本控件: text text textColor textSize textStyle
lines maxLines typeface ellipsize ems autoLink 按钮控件: button 输入框控件:
input hint textColorHint textSizeHint inputType password numeric
phoneNumber digits singleLine 图片控件: img src tint scaleType radius
radiusTopLeft radiusTopRight radiusBottomLeft radiusBottomRight
borderWidth borderColor circle 垂直布局: vertical layout_weight 水平布局:
horizontal layout_weight 线性布局: linear 帧布局: frame 相对布局: relative
勾选框控件: checkbox 选择框控件: radio 选择框布局: radiogroup 开关控件: Switch checked
text 进度条控件: progressbar 拖动条控件: seekbar 下来菜单控件: spinner 时间选择控件:
timepicker 日期选择控件: datepicker 浮动按钮控件: fab 标题栏控件: toolbar 卡片: card
cardBackgroundColor cardCornerRadius cardElevation contentPadding
foreground 抽屉布局: drawer 列表: list Tab: tab ui ui.layout(xml)
ui.layoutFile(xmlFile) ui.inflate(xml[, parent = null,
attachToParent = false]) ui.registerWidget(name, widget)
ui.isUiThread() ui.findView(id) ui.finish() ui.setContentView(view)
ui.post(callback[, delay = 0]) ui.run(callback)
ui.statusBarColor(color) ui.useAndroidResources() 尺寸的单位: Dimension
Drawables 颜色

综述#
Auto.js使用JavaScript作为脚本语言，目前使用Rhino 1.7.7.2作为脚本引擎，支持ES5与部分ES6特性。

因为Auto.js是基于JavaScript的，学习Auto.js的API之前建议先学习JavaScript的基本语法和内置对象，可以使用教程前面的两个JavaScript教程链接来学习。
如果您想要使用TypeScript来开发，目前已经有开发者公布了一个可以把使用TypeScript进行Auto.js开发的工具，参见Auto.js DevTools。
如果想要在电脑而不是手机上开发Auto.js，可以使用VS Code以及相应的Auto.js插件使得在电脑上编辑的脚本能推送到手机运行，参见Auto.js-VSCode-Extension，Auto.js Pro用户则需要使用Auto.js-Pro-Ext。
本文档的章节大致上是以模块来分的，总体上可以分成"自动操作"类模块(控件操作、触摸模拟、按键模拟等)和其他类模块(设备、应用、界面等)。

"自动操作"的部分又可以大致分为基于控件和基于坐标的操作。基于坐标的操作是传统按键精灵、触摸精灵等脚本软件采用的方式，通过屏幕坐标来点击、长按指定位置模拟操作，从而到达目的。例如click(100, 200), press(100, 200, 500)等。这种方式在游戏类脚本中比较有可行性，结合找图找色、坐标放缩功能也能达到较好的兼容性。但是，这种方式对一般软件脚本却难以达到想要的效果，而且这种方式需要安卓7.0版本以上或者root权限才能执行。所以对于一般软件脚本(例如批量添加联系人、自动提取短信验证码等等)，我们采用基于控件的模拟操作方式，结合通知事情、按键事情等达成更好的工作流。这些部分的文档参见基于控件的操作和基于坐标的操作。

其他部分主要包括：

app: 应用。启动应用，卸载应用，使用应用查看、编辑文件、访问网页，发送应用间广播等。
console: 控制台。记录运行的日志、错误、信息等。
device: 设备。获取设备屏幕宽高、系统版本等信息，控制设备音量、亮度等。
engines: 脚本引擎。用于启动其他脚本。
events: 事件与监听。按键监听，通知监听，触摸监听等。
floaty: 悬浮窗。用于显示自定义的悬浮窗。
files: 文件系统。文件创建、获取信息、读写。
http: HTTP。发送HTTP请求，例如GET, POST等。
images, colors: 图片和图色处理。截图，剪切图片，找图找色，读取保存图片等。
keys: 按键模拟。比如音量键、Home键模拟等。
shell: Shell命令。
threads: 多线程支持。
ui: UI界面。用于显示自定义的UI界面，和用户交互。
除此之外，Auto.js内置了对Promise。
Q & A#
如何定时运行脚本#
点击脚本右边的菜单按钮->更多->定时任务即可定时运行脚本，但是必须保持Auto.js后台运行(自启动白名单、电源管理白名单等)。同时，可以在脚本的开头使用device.wakeUp()来唤醒屏幕；但是，Auto.js没有解锁屏幕的功能，因此难以在有锁屏密码的设备上达到效果。

定时任何如何获取外部参数#
如果一个脚本是用intent"启动"的，比如定时任务中的特定事件（网络状态变化等）触发而启动的，则可以通过engines.myEngine().execArgv.intent获取启动的intent，从而获取外部参数。

如何把图片和脚本一起打包，或者打包多个脚本#
如果除了单脚本以外还有其他脚本、图片、音乐等资源一起打包，则需要使用项目功能。

点击Auto.js的"+"号，选择项目，填写项目名称、包名等信息以后，点击"√"即可新建一个项目。可以在项目中放多个脚本、模块、资源文件，点击项目工具栏的apk打包图标即可打包一个项目，点击工具栏可以重新配置项目。

例如，主脚本要读取同一文件夹下的图片1.png，再执行找图，则可以通过images.read("./1.png")来读取，其中"./1.png"表示同一目录1.png图片；ui中的图片控件要引用同一文件夹的2.png图片则为。Auto.js内置的函数和模块都支持相对路径，但是，其他情况则需要使用files.path()函数来把相对路径转换为绝对路径。

如何使打包的应用不显示主界面#
需要使用项目功能。新建项目后，修改项目下的project.json文件，增加以下条目：

“launchConfig”: {
“hideLogs”: true
}
例如：

{
“name”: “项目名称”,
“versionName”: “1.0.0”,
“versionCode”: 1,
“packageName”: “org.autojs.example”,
“main”: “main.js”,
“launchConfig”: {
“hideLogs”: true
}
}
"launchConfig"表示启动配置，"hideLogs"表示隐藏日志。

参见项目与项目配置。

Auto.js自带的模块和函数中没有的功能如何实现#
由于Auto.js支持直接调用Android的API，对于Auto.js没有内置的函数，可以直接通过修改Android代码为JavaScript代码实现。例如旋转图片的Android代码为：

import android.graphics.Bitmap;
import android.graphics.Matrix;

public static Bitmap rotate(final Bitmap src,
final int degrees,
final float px,
final float py) {
if (degrees == 0) return src;
Matrix matrix = new Matrix();
matrix.setRotate(degrees, px, py);
Bitmap ret = Bitmap.createBitmap(src, 0, 0, src.getWidth(), src.getHeight(), matrix, true);
return ret;
}
转换为JavaScript的代码后为：

importClass(android.graphics.Bitmap);
importClass(android.graphics.Matrix);

function rotate(src, degrees, px, py){
if (degrees == 0) return src;
var matrix = new Matrix();
matrix.setRotate(degrees, px, py);
var ret = Bitmap.createBitmap(src, 0, 0, src.getWidth(), src.getHeight(), matrix, true);
return ret;
}
有关调用Android和Java的API的更多信息，参见Work with Java。
App#
app模块提供一系列函数，用于使用其他应用、与其他应用交互。例如发送意图、打开文件、发送邮件等。

同时提供了方便的进阶函数startActivity和sendBroadcast，用他们可完成app模块没有内置的和其他应用的交互。

app.versionCode#

当前软件版本号，整数值。例如160, 256等。

如果在Auto.js中运行则为Auto.js的版本号；在打包的软件中则为打包软件的版本号。

toastLog(app.versionCode);
app.versionName#

当前软件的版本名称，例如"3.0.0 Beta"。

如果在Auto.js中运行则为Auto.js的版本名称；在打包的软件中则为打包软件的版本名称。

toastLog(app.verionName);
app.autojs.versionCode#

Auto.js版本号，整数值。例如160, 256等。

app.autojs.versionName#

Auto.js版本名称，例如"3.0.0 Beta"。

app.launchApp(appName)#
appName 应用名称
通过应用名称启动应用。如果该名称对应的应用不存在，则返回false; 否则返回true。如果该名称对应多个应用，则只启动其中某一个。

该函数也可以作为全局函数使用。

launchApp(“Auto.js”);
app.launch(packageName)#
packageName 应用包名
通过应用包名启动应用。如果该包名对应的应用不存在，则返回false；否则返回true。

该函数也可以作为全局函数使用。

//启动微信
launch(“com.tencent.mm”);
app.launchPackage(packageName)#
packageName 应用包名
相当于app.launch(packageName)。

app.getPackageName(appName)#
appName 应用名称
获取应用名称对应的已安装的应用的包名。如果该找不到该应用，返回null；如果该名称对应多个应用，则只返回其中某一个的包名。

该函数也可以作为全局函数使用。

var name = getPackageName(“QQ”); //返回"com.tencent.mobileqq"
app.getAppName(packageName)#
packageName 应用包名
获取应用包名对应的已安装的应用的名称。如果该找不到该应用，返回null。

该函数也可以作为全局函数使用。

var name = getAppName(“com.tencent.mobileqq”); //返回"QQ"
app.openAppSetting(packageName)#
packageName 应用包名
打开应用的详情页(设置页)。如果找不到该应用，返回false; 否则返回true。

该函数也可以作为全局函数使用。

app.viewFile(path)#
path 文件路径
用其他应用查看文件。文件不存在的情况由查看文件的应用处理。

如果找不出可以查看该文件的应用，则抛出ActivityNotException。

//查看文本文件
app.viewFile("/sdcard/1.txt");
app.editFile(path)#
path 文件路径
用其他应用编辑文件。文件不存在的情况由编辑文件的应用处理。

如果找不出可以编辑该文件的应用，则抛出ActivityNotException。

//编辑文本文件
app.editFile("/sdcard/1.txt/);
app.uninstall(packageName)#
packageName 应用包名
卸载应用。执行后会会弹出卸载应用的提示框。如果该包名的应用未安装，由应用卸载程序处理，可能弹出"未找到应用"的提示。

//卸载QQ
app.uninstall(“com.tencent.mobileqq”);
app.openUrl(url)#
url 网站的Url，如果不以"http://"或"https://“开头则默认是"http://”。
用浏览器打开网站url。

如果没有安装浏览器应用，则抛出ActivityNotException。

app.sendEmail(options)#
options 发送邮件的参数。包括:
email | 收件人的邮件地址。如果有多个收件人，则用字符串数组表示
cc | 抄送收件人的邮件地址。如果有多个抄送收件人，则用字符串数组表示
bcc | 密送收件人的邮件地址。如果有多个密送收件人，则用字符串数组表示
subject 邮件主题(标题)
text 邮件正文
attachment 附件的路径。
根据选项options调用邮箱应用发送邮件。这些选项均是可选的。

如果没有安装邮箱应用，则抛出ActivityNotException。

//发送邮件给10086@qq.com和10001@qq.com。
app.sendEmail({
email: [“10086@qq.com”, “10001@qq.com”],
subject: “这是一个邮件标题”,
text: “这是邮件正文”
});
app.startActivity(name)#
name 活动名称，可选的值为:
console 日志界面
settings 设置界面
启动Auto.js的特定界面。该函数在Auto.js内运行则会打开Auto.js内的界面，在打包应用中运行则会打开打包应用的相应界面。

app.startActivity(“console”);
进阶: 意图Intent#
Intent(意图) 是一个消息传递对象，您可以使用它从其他应用组件请求操作。尽管 Intent 可以通过多种方式促进组件之间的通信，但其基本用例主要包括以下三个：

启动活动(Activity)： Activity 表示应用中的一个"屏幕"。例如应用主入口都是一个Activity，应用的功能通常也以Activity的形式独立，例如微信的主界面、朋友圈、聊天窗口都是不同的Activity。通过将 Intent 传递给 startActivity()，您可以启动新的 Activity 实例。Intent 描述了要启动的 Activity，并携带了任何必要的数据。

启动服务(Service)： Service 是一个不使用用户界面而在后台执行操作的组件。通过将 Intent 传递给 startService()，您可以启动服务执行一次性操作（例如，下载文件）。Intent 描述了要启动的服务，并携带了任何必要的数据。

传递广播：广播是任何应用均可接收的消息。系统将针对系统事件（例如：系统启动或设备开始充电时）传递各种广播。通过将 Intent 传递给 sendBroadcast()、sendOrderedBroadcast() 或 sendStickyBroadcast()，您可以将广播传递给其他应用。

本模块提供了构建Intent的函数(app.intent()), 启动Activity的函数app.startActivity(), 发送广播的函数app.sendBroadcast()。

使用这些方法可以用来方便的调用其他应用。例如直接打开某个QQ号的个人卡片页，打开某个QQ号的聊天窗口等。

var qq = “2732014414”;
app.startActivity({
action: “android.intent.action.VIEW”,
data:“mqq://im/chat?chat_type=wpa&version=1&src_type=web&uin=” + qq,
packageName: “com.tencent.mobileqq”,
});

app.intent(options)#
options 选项，包括：

action 意图的Action，指意图要完成的动作，是一个字符串常量，比如"android.intent.action.SEND"。当action以"android.intent.action"开头时，可以省略前缀，直接用"SEND"代替。参见Actions。

type 意图的MimeType，表示和该意图直接相关的数据的类型，表示比如"text/plain"为纯文本类型。

data 意图的Data，表示和该意图直接相关的数据，是一个Uri, 可以是文件路径或者Url等。例如要打开一个文件, action为"android.intent.action.VIEW", data为"file:///sdcard/1.txt"。

category 意图的类别。比较少用。参见Categories。

packageName 目标包名

className 目标Activity或Service等组件的名称

extras 以键值对构成的这个Intent的Extras(额外信息)。提供该意图的其他信息，例如发送邮件时的邮件标题、邮件正文。参见Extras。

flags intent的标识，字符串数组，例如[“activity_new_task”, “grant_read_uri_permission”]。参见Flags。

[v4.1.0新增]

root 是否以root权限启动、发送该intent。使用该参数后，不能使用context.startActivity()等方法，而应该直接使用诸如app.startActivity({…})的方法。

[v4.1.0新增]

根据选项，构造一个意图Intent对象。

例如：

//打开应用来查看图片文件
var i = app.intent({
action: “VIEW”,
type: “image/png”,
data: “file:///sdcard/1.png”
});
context.startActivity(i);
需要注意的是，除非应用专门暴露Activity出来，否则在没有root权限的情况下使用intent是无法跳转到特定Activity、应用的特定界面的。例如我们能通过Intent跳转到QQ的分享界面，是因为QQ对外暴露了分享的Activity；而在没有root权限的情况下，我们无法通过intent跳转到QQ的设置界面，因为QQ并没有暴露这个Activity。

但如果有root权限，则在intent的参数加上"root": true即可。例如使用root权限跳转到Auto.js的设置界面为：

app.startActivity({
packageName: “org.autojs.autojs”,
className: “org.autojs.autojs.ui.settings.SettingsActivity_”,
root: true
});
另外，关于intent的参数如何获取的问题，一些intent是意外发现并且在网络中传播的（例如跳转QQ聊天窗口是因为QQ给网页提供了跳转到客服QQ的方法），如果要自己获取活动的intent的参数，可以通过例如"intent记录"，"隐式启动"等应用拦截内部intent或者查询暴露的intent。其中拦截内部intent需要XPosed框架，或者可以通过反编译等手段获取参数。总之，没有简单直接的方法。

更多信息，请百度安卓Intent或参考Android指南: Intent。

app.startActivity(options)#
options 选项
根据选项构造一个Intent，并启动该Activity。

app.startActivity({
action: “SEND”,
type: “text/plain”,
data: “file:///sdcard/1.txt”
});
app.sendBroadcast(options)#
options 选项
根据选项构造一个Intent，并发送该广播。

app.startService(options)#
options 选项
根据选项构造一个Intent，并启动该服务。

app.sendBroadcast(name)#
[v4.1.0新增]

name 特定的广播名称，包括：
inspect_layout_hierarchy 布局层次分析
inspect_layout_bounds 布局范围
发送以上特定名称的广播可以触发Auto.js的布局分析，方便脚本调试。这些广播在Auto.js发送才有效，在打包的脚本上运行将没有任何效果。

app.sendBroadcast(“inspect_layout_bounds”);
app.intentToShell(options)#
[v4.1.0新增]

options 选项
根据选项构造一个Intent，转换为对应的shell的intent命令的参数。

例如:

shell("am start " + app.intentToShell({
packageName: “org.autojs.autojs”,
className: “org.autojs.autojs.ui.settings.SettingsActivity_”
}), true);
参见intent参数的规范。

app.parseUri(uri)#
[v4.1.0新增]

uri 一个代表Uri的字符串，例如"file:///sdcard/1.txt", “https://www.autojs.org”
返回一个代表Uri的对象，参见android.net.Uri。
解析uri字符串并返回相应的Uri对象。即使Uri格式错误，该函数也会返回一个Uri对象，但之后如果访问该对象的scheme, path等值可能因解析失败而返回null。

需要注意的是，在高版本Android上，由于系统限制直接在Uri暴露文件的绝对路径，因此如果uri字符串是文件file://…，返回的Uri会是诸如content://…的形式。

app.getUriForFile(path)#
[v4.1.0新增]

path 文件路径，例如"/sdcard/1.txt"
返回一个指向该文件的Uri的对象，参见android.net.Uri。
从一个文件路径创建一个uri对象。需要注意的是，在高版本Android上，由于系统限制直接在Uri暴露文件的绝对路径，因此返回的Uri会是诸如content://…的形式。

app.getInstalledApps([options])#
[Pro 8.0.0新增]

options 选项，包括：
get: 指定返回的应用信息中包含的信息
“activities” 应用的Activity组件信息
“configurations” 应用的硬件配置
“gids” 应用的group id
“instrumentation” 应用的Instrumentation信息
“intent_filters” 应用的意图过滤
“meta_data” 应用的元信息（默认）
“permissions” 应用的权限信息
“providers” 应用的ContentProvider组件信息
“receivers” 应用的BroadcastReceiver组件信息
“services” 应用的Service组件信息
“shared_library_files” 应用的动态链接库文件信息
“signatures” 应用的签名信息（已弃用
“signing_certificates” 应用的签名信息
“uri_permission_patterns”
“disabled_components” 被卸载的但保留了数据的应用
“disabled_until_used_components” 禁用直到被使用的组件
“uninstalled_packages” 被卸载的但保留了数据的应用
match: 指定要匹配的应用列表
“uninstalled_packages” 被卸载的但保留了数据的应用
“disabled_components” 被禁用的组件
“disabled_until_used_components” 禁用直到被使用的组件
“system_only” 只匹配系统应用
“factory_only” 只匹配预装应用
“apex” APEX应用
返回 <Array<ApplicationInfo>>
返回为当前用户安装的所有应用程序包的列表。如果设置了match选项 uninstalled_packages，则包括被删除但保留了数据的应用程序。获取安装的应用列表。

返回值是ApplicationInfo对象的数组。如果没有安装任何应用，则返回一个空数组。

选项options的match选项用于指定要返回哪些应用程序，get选项用于指定返回的应用程序携带哪些信息。

let apps = $app.getInstalledApps({
matcg
})
Console#
Stability: 2 - Stable
控制台模块提供了一个和Web浏览器中相似的用于调试的控制台。用于输出一些调试信息、中间结果等。 console模块中的一些函数也可以直接作为全局函数使用，例如log, print等。

console.show()#
显示控制台。这会显示一个控制台的悬浮窗(需要悬浮窗权限)。

console.hide()#
隐藏控制台悬浮窗。

console.clear()#
清空控制台。

console.log([data][, …args])#
data
…args
打印到控制台，并带上换行符。可以传入多个参数，第一个参数作为主要信息，其他参数作为类似于 printf(3) 中的代替值（参数都会传给 util.format()）。

const count = 5;
console.log(‘count: %d’, count);
// 打印: count: 5 到 stdout
console.log(‘count:’, count);
// 打印: count: 5 到 stdout
详见 util.format()。

该函数也可以作为全局函数使用。

console.verbose([data][, …args])#
data
…args
与console.log类似，但输出结果以灰色字体显示。输出优先级低于log，用于输出观察性质的信息。

console.info([data][, …args])#
data
…args
与console.log类似，但输出结果以绿色字体显示。输出优先级高于log, 用于输出重要信息。

console.warn([data][, …args])#
data
…args
与console.log类似，但输出结果以蓝色字体显示。输出优先级高于info, 用于输出警告信息。

console.error([data][, …args])#
data
…args
与console.log类似，但输出结果以红色字体显示。输出优先级高于warn, 用于输出错误信息。

console.assert(value, message)#
value 要断言的布尔值
message value为false时要输出的信息
断言。如果value为false则输出错误信息message并停止脚本运行。

var a = 1 + 1;
console.assert(a == 2, “加法出错啦”);
console.time([label])#
[v4.1.0新增]

label 计时器标签，可省略
启动一个定时器，用以计算一个操作的持续时间。定时器由一个唯一的 label 标识。当调用 console.timeEnd() 时，可以使用相同的 label 来停止定时器，并以毫秒为单位将持续时间输出到控制台。重复启动同一个标签的定时器会覆盖之前启动同一标签的定时器。

console.timeEnd(label)#
[v4.1.0新增]

label 计时器标签
停止之前通过调用 console.time() 启动的定时器，并打印结果到控制台。调用 console.timeEnd() 后定时器会被删除。如果不存在标签指定的定时器则会打印 NaNms。

console.time(‘求和’);
var sum = 0;
for(let i = 0; i < 100000; i++){
sum += i;
}
console.timeEnd(‘求和’);
// 打印求和: xxx ms
console.trace([data][, …args])#
[v4.1.0新增]

data
…args
与console.log类似，同时会打印出调用这个函数所在的调用栈信息（即当前运行的文件、行数等信息）。

console.trace(‘Show me’);
// 打印: (堆栈跟踪会根据被调用的跟踪的位置而变化)
// Show me
// at :7
console.input(data[, …args])#
data
…args
与console.log一样输出信息，并在控制台显示输入框等待输入。按控制台的确认按钮后会将输入的字符串用eval计算后返回。

部分机型可能会有控制台不显示输入框的情况，属于bug。

例如：

var n = console.input(“请输入一个数字:”);
//输入123之后：
toast(n + 1);
//显示124
console.rawInput(data[, …args])#
data
…args
与console.log一样输出信息，并在控制台显示输入框等待输入。按控制台的确认按钮后会将输入的字符串直接返回。

部分机型可能会有控制台不显示输入框的情况，属于bug。

例如：

var n = console.rawInput(“请输入一个数字:”);
//输入123之后：
toast(n + 1);
//显示1231
console.setSize(w, h)#
w 宽度
h 高度
设置控制台的大小，单位像素。

console.show();
//设置控制台大小为屏幕的四分之一
console.setSize(device.width / 2, device.height / 2);
console.setPosition(x, y)#
x 横坐标
y 纵坐标
设置控制台的位置，单位像素。

console.show();
console.setPosition(100, 100);
console.setGlobalLogConfig(config)#
[v4.1.0新增]

config 日志配置，可选的项有：
file 日志文件路径，将会把日志写入该文件中
maxFileSize 最大文件大小，单位字节，默认为512 * 1024 (512KB)
rootLevel 写入的日志级别，默认为"ALL"（所有日志），可以为"OFF"(关闭), “DEBUG”, “INFO”, “WARN”, “ERROR”, “FATAL"等。
maxBackupSize 日志备份文件最大数量，默认为5
filePattern 日志写入格式，参见PatternLayout
设置日志保存的路径和配置。例如把日志保存到”/sdcard/1.txt":

console.setGlobalLogConfig({
“file”: “/sdcard/1.txt”
});
注意该函数会影响所有脚本的日志记录。

print(text)#
text | 要打印到控制台的信息
相当于log(text)。

基于坐标的触摸模拟#
Stability: 2 - Stable
本章节介绍了一些使用坐标进行点击、滑动的函数。这些函数有的需要安卓7.0以上，有的需要root权限。

要获取要点击的位置的坐标，可以在开发者选项中开启"指针位置"。

基于坐标的脚本通常会有分辨率的问题，这时可以通过setScreenMetrics()函数来进行自动坐标放缩。这个函数会影响本章节的所有点击、长按、滑动等函数。通过设定脚本设计时的分辨率，使得脚本在其他分辨率下自动放缩坐标。

控件和坐标也可以相互结合。一些控件是无法点击的(clickable为false), 无法通过.click()函数来点击，这时如果安卓版本在7.0以上或者有root权限，就可以通过以下方式来点击：

//获取这个控件
var widget = id(“xxx”).findOne();
//获取其中心位置并点击
click(widget.bounds().centerX(), widget.bounds().centerY());
//如果用root权限则用Tap
setScreenMetrics(width, height)#
width 屏幕宽度，单位像素
height 屏幕高度，单位像素
设置脚本坐标点击所适合的屏幕宽高。如果脚本运行时，屏幕宽度不一致会自动放缩坐标。

例如在1920*1080的设备中，某个操作的代码为

setScreenMetrics(1080, 1920);
click(800, 200);
longClick(300, 500);
那么在其他设备上AutoJs会自动放缩坐标以便脚本仍然有效。例如在540 * 960的屏幕中click(800, 200)实际上会点击位置(400, 100)。

安卓7.0以上的触摸和手势模拟#
Stability: 2 - Stable
注意以下命令只有Android7.0及以上才有效

click(x, y)#
x 要点击的坐标的x值
y 要点击的坐标的y值
模拟点击坐标(x, y)，并返回是否点击成功。只有在点击执行完成后脚本才继续执行。

一般而言，只有点击过程(大约150毫秒)中被其他事件中断(例如用户自行点击)才会点击失败。

使用该函数模拟连续点击时可能有点击速度过慢的问题，这时可以用press()函数代替。

longClick(x, y)#
x 要长按的坐标的x值
y 要长按的坐标的y值
模拟长按坐标(x, y), 并返回是否成功。只有在长按执行完成（大约600毫秒）时脚本才会继续执行。

一般而言，只有长按过程中被其他事件中断(例如用户自行点击)才会长按失败。

press(x, y, duration)#
x 要按住的坐标的x值
y 要按住的坐标的y值
duration 按住时长，单位毫秒
模拟按住坐标(x, y), 并返回是否成功。只有按住操作执行完成时脚本才会继续执行。

如果按住时间过短，那么会被系统认为是点击；如果时长超过500毫秒，则认为是长按。

一般而言，只有按住过程中被其他事件中断才会操作失败。

一个连点器的例子如下：

//循环100次
for(var i = 0; i < 100; i++){
//点击位置(500, 1000), 每次用时1毫秒
press(500, 1000, 1);
}
swipe(x1, y1, x2, y2, duration)#
x1 滑动的起始坐标的x值
y1 滑动的起始坐标的y值
x2 滑动的结束坐标的x值
y2 滑动的结束坐标的y值
duration 滑动时长，单位毫秒
模拟从坐标(x1, y1)滑动到坐标(x2, y2)，并返回是否成功。只有滑动操作执行完成时脚本才会继续执行。

一般而言，只有滑动过程中被其他事件中断才会滑动失败。

gesture(duration, [x1, y1], [x2, y2], …)#
duration 手势的时长
[x, y] … 手势滑动路径的一系列坐标
模拟手势操作。例如gesture(1000, [0, 0], [500, 500], [500, 1000])为模拟一个从(0, 0)到(500, 500)到(500, 100)的手势操作，时长为2秒。

gestures([delay1, duration1, [x1, y1], [x2, y2], …], [delay2, duration2, [x3, y3], [x4, y4], …], …)#
同时模拟多个手势。每个手势的参数为[delay, duration, 坐标], delay为延迟多久(毫秒)才执行该手势；duration为手势执行时长；坐标为手势经过的点的坐标。其中delay参数可以省略，默认为0。

例如手指捏合：

gestures([0, 500, [800, 300], [500, 1000]],
[0, 500, [300, 1500], [500, 1000]]);
RootAutomator#
Stability: 2 - Stable
RootAutomator是一个使用root权限来模拟触摸的对象，用它可以完成触摸与多点触摸，并且这些动作的执行没有延迟。

一个脚本中最好只存在一个RootAutomator，并且保证脚本结束退出他。可以在exit事件中退出RootAutomator，例如：

var ra = new RootAutomator();
events.on(‘exit’, function(){
ra.exit();
});
//执行一些点击操作
…

注意以下命令需要root权限

RootAutomator.tap(x, y[, id])#
x 横坐标
y 纵坐标
id 多点触摸id，可选，默认为1，可以通过setDefaultId指定。
点击位置(x, y)。其中id是一个整数值，用于区分多点触摸，不同的id表示不同的"手指"，例如：

var ra = new RootAutomator();
//让"手指1"点击位置(100, 100)
ra.tap(100, 100, 1);
//让"手指2"点击位置(200, 200);
ra.tap(200, 200, 2);
ra.exit();
如果不需要多点触摸，则不需要id这个参数。多点触摸通常用于手势或游戏操作，例如模拟双指捏合、双指上滑等。

某些情况下可能存在tap点击无反应的情况，这时可以用RootAutomator.press()函数代替。

RootAutomator.swipe(x1, x2, y1, y2[, duration, id])#
x1 滑动起点横坐标
y1 滑动起点纵坐标
x2 滑动终点横坐标
y2 滑动终点纵坐标
duration 滑动时长，单位毫秒，默认值为300
id 多点触摸id，可选，默认为1
模拟一次从(x1, y1)到(x2, y2)的时间为duration毫秒的滑动。

RootAutomator.press(x, y, duration[, id])#
x 横坐标
y 纵坐标
duration 按下时长
id 多点触摸id，可选，默认为1
模拟按下位置(x, y)，时长为duration毫秒。

RootAutomator.longPress(x, y[, id])#
x 横坐标
y 纵坐标
duration 按下时长
id 多点触摸id，可选，默认为1
模拟长按位置(x, y)。

以上为简单模拟触摸操作的函数。如果要模拟一些复杂的手势，需要更底层的函数。

RootAutomator.touchDown(x, y[, id])#
x 横坐标
y 纵坐标
id 多点触摸id，可选，默认为1
模拟手指按下位置(x, y)。

RootAutomator.touchMove(x, y[, id])#
x 横坐标
y 纵坐标
id 多点触摸id，可选，默认为1
模拟移动手指到位置(x, y)。

RootAutomator.touchUp([id])#
id 多点触摸id，可选，默认为1
模拟手指弹起。

使用root权限点击和滑动的简单命令#
Stability: 1 - Experimental
注意：本章节的函数在后续版本很可能有改动！请勿过分依赖本章节函数的副作用。推荐使用RootAutomator代替本章节的触摸函数。

以下函数均需要root权限，可以实现任意位置的点击、滑动等。

这些函数通常首字母大写以表示其特殊的权限。
这些函数均不返回任何值。
并且，这些函数的执行是异步的、非阻塞的，在不同机型上所用的时间不同。脚本不会等待动作执行完成才继续执行。因此最好在每个函数之后加上适当的sleep来达到期望的效果。
例如:

Tap(100, 100);
sleep(500);
注意，动作的执行可能无法被停止，例如：

for(var i = 0; i < 100; i++){
Tap(100, 100);
}
这段代码执行后可能会出现在任务管理中停止脚本后点击仍然继续的情况。因此，强烈建议在每个动作后加上延时：

for(var i = 0; i < 100; i++){
Tap(100, 100);
sleep(500);
}
Tap(x, y)#
x, y 要点击的坐标。
点击位置(x, y), 您可以通过"开发者选项"开启指针位置来确定点击坐标。

Swipe(x1, y1, x2, y2, [duration])#
x1, y1 滑动起点的坐标
x2, y2 滑动终点的坐标
duration 滑动动作所用的时间
滑动。从(x1, y1)位置滑动到(x2, y2)位置。
Crypto#
[Pro 8.0.0新增]

$crypto模块提供了对称加密(例如AES)、非对称加密(例如RSA)、消息摘要(例如MD5, SHA)等支持。

$crypto.digest(message, algorithm[, options])#
message
algorithm 消息摘要算法，包括：
MD5
SHA-1
SHA-256
SHA-384
SHA-512
options
对信息message使用消息摘要算法algorithm进行摘要并返回结果，默认的输出格式为hex。

参数message的类型默认为字符串，返回值默认为hex；可以通过options来指定参数message的类型和返回值的类型、格式，比如文件、base64、字节数组、hex等。参见《输入和输出的类型和格式》。

// 计算字符串abc的md5
toastLog(crypto.digest("abc","MD5"));//计算字符串abc的sha−256toastLog(crypto.digest("abc", "MD5")); // 计算字符串abc的sha-256 toastLog(crypto.digest("abc","MD5"));//计算字符串abc的sha−256toastLog(crypto.digest(“abc”, “SHA-256”));
// 计算文件/sdcard/1.txt的md5
toastLog($crypto.digest("/sdcard/1.txt", “MD5”, {
input: “file”
}));
$crypto.encrypt(data, key, algorithm, options)#
data 明文消息
key 密钥
algorithm 加密算法，包括：

AES
AES/ECB/NoPadding
AES/ECB/PKCS5Padding
AES/CBC/NoPadding
AES/CBC/PKCS5Padding
AES/CFB/NoPadding
AES/CFB/PKCS5Padding
AES/CTR/NoPadding
AES/CTR/PKCS5Padding
AES/OFB/PKCS5Padding
AES/OFB/PKCS5Padding
RSA/ECB/PKCS1Padding
RSA/ECB/NoPadding
… 具体可参阅 javax.crypto.Cipher
options 加密选项

输入和输出的类型和格式#
Device#
Stability: 2 - Stable
device模块提供了与设备有关的信息与操作，例如获取设备宽高，内存使用率，IMEI，调整设备亮度、音量等。

此模块的部分函数，例如调整音量，需要"修改系统设置"的权限。如果没有该权限，会抛出SecurityException并跳转到权限设置界面。

device.width#

设备屏幕分辨率宽度。例如1080。

device.height#

设备屏幕分辨率高度。例如1920。

device.buildId#

Either a changelist number, or a label like “M4-rc20”.

修订版本号，或者诸如"M4-rc20"的标识。

device.broad#

The name of the underlying board, like “goldfish”.

设备的主板(?)型号。

device.brand#

The consumer-visible brand with which the product/hardware will be associated, if any.

与产品或硬件相关的厂商品牌，如"Xiaomi", "Huawei"等。

device.device#

The name of the industrial design.

设备在工业设计中的名称。

deivce.model#

The end-user-visible name for the end product.

设备型号。

device.product#

The name of the overall product.

整个产品的名称。

device.bootloader#

The system bootloader version number.

设备Bootloader的版本。

device.hardware#

The name of the hardware (from the kernel command line or /proc).

设备的硬件名称(来自内核命令行或者/proc)。

device.fingerprint#

A string that uniquely identifies this build. Do not attempt to parse this value.

构建(build)的唯一标识码。

device.serial#

A hardware serial number, if available. Alphanumeric only, case-insensitive.

硬件序列号。

device.sdkInt#

The user-visible SDK version of the framework; its possible values are defined in Build.VERSION_CODES.

安卓系统API版本。例如安卓4.4的sdkInt为19。

device.incremental#

The internal value used by the underlying source control to represent this build. E.g., a perforce changelist number or a git hash.

device.release#

The user-visible version string. E.g., “1.0” or “3.4b5”.

Android系统版本号。例如"5.0", “7.1.1”。

device.baseOS#

The base OS build the product is based on.

device.securityPatch#

The user-visible security patch level.

安全补丁程序级别。

device.codename#

The current development codename, or the string “REL” if this is a release build.

开发代号，例如发行版是"REL"。

device.getIMEI()#

返回设备的IMEI.

device.getAndroidId()#

返回设备的Android ID。

Android ID为一个用16进制字符串表示的64位整数，在设备第一次使用时随机生成，之后不会更改，除非恢复出厂设置。

device.getMacAddress()#

返回设备的Mac地址。该函数需要在有WLAN连接的情况下才能获取，否则会返回null。

可能的后续修改：未来可能增加有root权限的情况下通过root权限获取，从而在没有WLAN连接的情况下也能返回正确的Mac地址，因此请勿使用此函数判断WLAN连接。

device.getBrightness()#

返回当前的(手动)亮度。范围为0~255。

device.getBrightnessMode()#

返回当前亮度模式，0为手动亮度，1为自动亮度。

device.setBrightness(b)#
b 亮度，范围0~255
设置当前手动亮度。如果当前是自动亮度模式，该函数不会影响屏幕的亮度。

此函数需要"修改系统设置"的权限。如果没有该权限，会抛出SecurityException并跳转到权限设置界面。

device.setBrightnessMode(mode)#
mode 亮度模式，0为手动亮度，1为自动亮度
设置当前亮度模式。

此函数需要"修改系统设置"的权限。如果没有该权限，会抛出SecurityException并跳转到权限设置界面。

device.getMusicVolume()#
整数值
返回当前媒体音量。

device.getNotificationVolume()#
整数值
返回当前通知音量。

device.getAlarmVolume()#
整数值
返回当前闹钟音量。

device.getMusicMaxVolume()#
整数值
返回媒体音量的最大值。

device.getNotificationMaxVolume()#
整数值
返回通知音量的最大值。

device.getAlarmMaxVolume()#
整数值
返回闹钟音量的最大值。

device.setMusicVolume(volume)#
volume 音量
设置当前媒体音量。

此函数需要"修改系统设置"的权限。如果没有该权限，会抛出SecurityException并跳转到权限设置界面。

device.setNotificationVolume(volume)#
volume 音量
设置当前通知音量。

此函数需要"修改系统设置"的权限。如果没有该权限，会抛出SecurityException并跳转到权限设置界面。

device.setAlarmVolume(volume)#
volume 音量
设置当前闹钟音量。

此函数需要"修改系统设置"的权限。如果没有该权限，会抛出SecurityException并跳转到权限设置界面。

device.getBattery()#
0.0~100.0的浮点数
返回当前电量百分比。

device.isCharging()#

返回设备是否正在充电。

device.getTotalMem()#

返回设备内存总量，单位字节(B)。1MB = 1024 * 1024B。

device.getAvailMem()#

返回设备当前可用的内存，单位字节(B)。

device.isScreenOn()#
返回
返回设备屏幕是否是亮着的。如果屏幕亮着，返回true; 否则返回false。

需要注意的是，类似于vivo xplay系列的息屏时钟不属于"屏幕亮着"的情况，虽然屏幕确实亮着但只能显示时钟而且不可交互，此时isScreenOn()也会返回false。

device.wakeUp()#
唤醒设备。包括唤醒设备CPU、屏幕等。可以用来点亮屏幕。

device.wakeUpIfNeeded()#
如果屏幕没有点亮，则唤醒设备。

device.keepScreenOn([timeout])#
timeout 屏幕保持常亮的时间, 单位毫秒。如果不加此参数，则一直保持屏幕常亮。
保持屏幕常亮。

此函数无法阻止用户使用锁屏键等正常关闭屏幕，只能使得设备在无人操作的情况下保持屏幕常亮；同时，如果此函数调用时屏幕没有点亮，则会唤醒屏幕。

在某些设备上，如果不加参数timeout，只能在Auto.js的界面保持屏幕常亮，在其他界面会自动失效，这是因为设备的省电策略造成的。因此，建议使用比较长的时长来代替"一直保持屏幕常亮"的功能，例如device.keepScreenOn(3600 * 1000)。

可以使用device.cancelKeepingAwake()来取消屏幕常亮。

//一直保持屏幕常亮
device.keepScreenOn()
device.keepScreenDim([timeout])#
timeout 屏幕保持常亮的时间, 单位毫秒。如果不加此参数，则一直保持屏幕常亮。
保持屏幕常亮，但允许屏幕变暗来节省电量。此函数可以用于定时脚本唤醒屏幕操作，不需要用户观看屏幕，可以让屏幕变暗来节省电量。

可以使用device.cancelKeepingAwake()来取消屏幕常亮。

device.cancelKeepingAwake()#
取消设备保持唤醒状态。用于取消device.keepScreenOn(), device.keepScreenDim()等函数设置的屏幕常亮。

device.vibrate(millis)#
millis 震动时间，单位毫秒
使设备震动一段时间。

//震动两秒
device.vibrate(2000);
device.cancelVibration()#
如果设备处于震动状态，则取消震动。

Dialogs#
Stability: 2 - Stable
dialogs 模块提供了简单的对话框支持，可以通过对话框和用户进行交互。最简单的例子如下：

alert(“您好”);
这段代码会弹出一个消息提示框显示"您好"，并在用户点击"确定"后继续运行。稍微复杂一点的例子如下：

var clear = confirm(“要清除所有缓存吗?”);
if(clear){
alert(“清除成功!”);
}
confirm()会弹出一个对话框并让用户选择"是"或"否"，如果选择"是"则返回true。

需要特别注意的是，对话框在ui模式下不能像通常那样使用，应该使用回调函数或者Promise的形式。理解这一点可能稍有困难。举个例子:

“ui”;
//回调形式
confirm(“要清除所有缓存吗?”, function(clear){
if(clear){
alert(“清除成功!”);
}
});
//Promise形式
confirm(“要清除所有缓存吗?”)
.then(clear => {
if(clear){
alert(“清除成功!”);
}
});
dialogs.alert(title[, content, callback])#
title 对话框的标题。
content 可选，对话框的内容。默认为空。
callback 回调函数，可选。当用户点击确定时被调用,一般用于ui模式。
显示一个只包含“确定”按钮的提示对话框。直至用户点击确定脚本才继续运行。

该函数也可以作为全局函数使用。

alert(“出现错误~”, "出现未知错误，请联系脚本作者”);
在ui模式下该函数返回一个Promise。例如:

“ui”;
alert(“嘿嘿嘿”).then(()=>{
//当点击确定后会执行这里
});
dialogs.confirm(title[, content, callback])#
title 对话框的标题。
content 可选，对话框的内容。默认为空。
callback 回调函数，可选。当用户点击确定时被调用,一般用于ui模式。
显示一个包含“确定”和“取消”按钮的提示对话框。如果用户点击“确定”则返回 true ，否则返回 false 。

该函数也可以作为全局函数使用。

在ui模式下该函数返回一个Promise。例如:

“ui”;
confirm(“确定吗”).then(value=>{
//当点击确定后会执行这里, value为true或false, 表示点击"确定"或"取消"
});
dialogs.rawInput(title[, prefill, callback])#
title 对话框的标题。
prefill 输入框的初始内容，可选，默认为空。
callback 回调函数，可选。当用户点击确定时被调用,一般用于ui模式。
显示一个包含输入框的对话框，等待用户输入内容，并在用户点击确定时将输入的字符串返回。如果用户取消了输入，返回null。

该函数也可以作为全局函数使用。

var name = rawInput(“请输入您的名字”, “小明”);
alert(“您的名字是” + name);
在ui模式下该函数返回一个Promise。例如:

“ui”;
rawInput(“请输入您的名字”, “小明”).then(name => {
alert(“您的名字是” + name);
});
当然也可以使用回调函数，例如:

rawInput(“请输入您的名字”, “小明”, name => {
alert(“您的名字是” + name);
});
dialogs.input(title[, prefill, callback])#
等效于 eval(dialogs.rawInput(title, prefill, callback)), 该函数和rawInput的区别在于，会把输入的字符串用eval计算一遍再返回，返回的可能不是字符串。

可以用该函数输入数字、数组等。例如：

var age = dialogs.input(“请输入您的年龄”, “18”);
// new Date().getYear() + 1900 可获取当前年份
var year = new Date().getYear() + 1900 - age;
alert(“您的出生年份是” + year);
在ui模式下该函数返回一个Promise。例如:

“ui”;
dialogs.input(“请输入您的年龄”, “18”).then(age => {
var year = new Date().getYear() + 1900 - age;
alert(“您的出生年份是” + year);
});
dialogs.prompt(title[, prefill, callback])#
相当于 dialogs.rawInput();

dialogs.select(title, items, callback)#
title 对话框的标题。
items 对话框的选项列表，是一个字符串数组。
callback 回调函数，可选。当用户点击确定时被调用,一般用于ui模式。
显示一个带有选项列表的对话框，等待用户选择，返回用户选择的选项索引(0 ~ item.length - 1)。如果用户取消了选择，返回-1。

var options = [“选项A”, “选项B”, “选项C”, “选项D”]
var i = dialogs.select(“请选择一个选项”, options);
if(i >= 0){
toast(“您选择的是” + options[i]);
}else{
toast(“您取消了选择”);
}
在ui模式下该函数返回一个Promise。例如:

“ui”;
dialogs.select(“请选择一个选项”, [“选项A”, “选项B”, “选项C”, “选项D”])
.then(i => {
toast(i);
});
dialogs.singleChoice(title, items[, index, callback])#
title 对话框的标题。
items 对话框的选项列表，是一个字符串数组。
index 对话框的初始选项的位置，默认为0。
callback 回调函数，可选。当用户点击确定时被调用,一般用于ui模式。
显示一个单选列表对话框，等待用户选择，返回用户选择的选项索引(0 ~ item.length - 1)。如果用户取消了选择，返回-1。

在ui模式下该函数返回一个Promise。

dialogs.multiChoice(title, items[, indices, callback])#
title 对话框的标题。
items 对话框的选项列表，是一个字符串数组。
indices 选项列表中初始选中的项目索引的数组，默认为空数组。
callback 回调函数，可选。当用户点击确定时被调用,一般用于ui模式。
显示一个多选列表对话框，等待用户选择，返回用户选择的选项索引的数组。如果用户取消了选择，返回[]。

在ui模式下该函数返回一个Promise。

dialogs.build(properties)#
properties 对话框属性，用于配置对话框。
返回
创建一个可自定义的对话框，例如：

dialogs.build({
//对话框标题
title: “发现新版本”,
//对话框内容
content: “更新日志: 新增了若干了BUG”,
//确定键内容
positive: “下载”,
//取消键内容
negative: “取消”,
//中性键内容
neutral: “到浏览器下载”,
//勾选框内容
checkBoxPrompt: “不再提示”
}).on(“positive”, ()=>{
//监听确定键
toast(“开始下载…”);
}).on(“neutral”, ()=>{
//监听中性键
app.openUrl(“https://www.autojs.org”);
}).on(“check”, (checked)=>{
//监听勾选框
log(checked);
}).show();
选项properties可供配置的项目为:

title 对话框标题
titleColor | 对话框标题的颜色
buttonRippleColor | 对话框按钮的波纹效果颜色
icon | 对话框的图标，是一个URL或者图片对象
content 对话框文字内容
contentColor | 对话框文字内容的颜色
contentLineSpacing 对话框文字内容的行高倍数，1.0为一倍行高
items 对话框列表的选项
itemsColor | 对话框列表的选项的文字颜色
itemsSelectMode 对话框列表的选项选择模式，可以为:
select 普通选择模式
single 单选模式
multi 多选模式
itemsSelectedIndex | 对话框列表中预先选中的项目索引，如果是单选模式为一个索引；多选模式则为数组
positive 对话框确定按钮的文字内容(最右边按钮)
positiveColor | 对话框确定按钮的文字颜色(最右边按钮)
neutral 对话框中立按钮的文字内容(最左边按钮)
neutralColor | 对话框中立按钮的文字颜色(最左边按钮)
negative 对话框取消按钮的文字内容(确定按钮左边的按钮)
negativeColor | 对话框取消按钮的文字颜色(确定按钮左边的按钮)
checkBoxPrompt 勾选框文字内容
checkBoxChecked 勾选框是否勾选
progress 配置对话框进度条的对象：
max 进度条的最大值，如果为-1则为无限循环的进度条
horizontal 如果为true, 则对话框无限循环的进度条为水平进度条
showMinMax 是否显示进度条的最大值和最小值
cancelable 对话框是否可取消，如果为false，则对话框只能用代码手动取消
canceledOnTouchOutside 对话框是否在点击对话框以外区域时自动取消，默认为true
inputHint 对话框的输入框的输入提示
inputPrefill 对话框输入框的默认输入内容
通过这些选项可以自定义一个对话框，并通过监听返回的Dialog对象的按键、输入事件来实现交互。下面是一些例子。

模拟alert对话框：

dialogs.build({
title: “你好”,
content: “今天也要元气满满哦”,
positive: “好的”
}).show();
模拟confirm对话框:

dialogs.build({
title: “你好”,
content: “请问你是笨蛋吗?”,
positive: “是的”,
negative: “我是大笨蛋”
}).on(“positive”, ()=>{
alert(“哈哈哈笨蛋”);
}).on(“negative”, ()=>{
alert(“哈哈哈大笨蛋”);
}).show();
模拟单选框:

dialogs.build({
title: “单选”,
items: [“选项1”, “选项2”, “选项3”, “选项4”],
itemsSelectMode: “single”,
itemsSelectedIndex: 3
}).on(“single_choice”, (index, item)=>{
toast(“您选择的是” + item);
}).show();
"处理中"对话框:

var d = dialogs.build({
title: “下载中…”,
progress: {
max: -1
},
cancelable: false
}).show();

setTimeout(()=>{
d.dismiss();
}, 3000);
输入对话框:

dialogs.build({
title: “请输入您的年龄”,
inputPrefill: “18”
}).on(“input”, (input)=>{
var age = parseInt(input);
toastLog(age);
}).show();
使用这个函数来构造对话框，一个明显的不同是需要使用回调函数而不能像dialogs其他函数一样同步地返回结果；但也可以通过threads模块的方法来实现。例如显示一个输入框并获取输入结果为：

var input = threads.disposable();
dialogas.build({
title: “请输入您的年龄”,
inputPrefill: “18”
}).on(“input”, text => {
input.setAndNotify(text);
}).show();
var age = parseInt(input.blockedGet());
tosatLog(age);
Dialog#
dialogs.build()返回的对话框对象，内置一些事件用于响应用户的交互，也可以获取对话框的状态和信息。

事件: show#
dialog 对话框
对话框显示时会触发的事件。例如：

dialogs.build({
title: “标题”
}).on(“show”, (dialog)=>{
toast(“对话框显示了”);
}).show();
事件: cancel#
dialog 对话框
对话框被取消时会触发的事件。一个对话框可能按取消按钮、返回键取消或者点击对话框以外区域取消。例如：

dialogs.build({
title: “标题”,
positive: “确定”,
negative: “取消”
}).on(“cancel”, (dialog)=>{
toast(“对话框取消了”);
}).show();
事件: dismiss#
dialog 对话框
对话框消失时会触发的事件。对话框被取消或者手动调用dialog.dismiss()函数都会触发该事件。例如：

var d = dialogs.build({
title: “标题”,
positive: “确定”,
negative: “取消”
}).on(“dismiss”, (dialog)=>{
toast(“对话框消失了”);
}).show();

setTimeout(()=>{
d.dismiss();
}, 5000);
事件: positive#
dialog 对话框
确定按钮按下时触发的事件。例如：

var d = dialogs.build({
title: “标题”,
positive: “确定”,
negative: “取消”
}).on(“positive”, (dialog)=>{
toast(“你点击了确定”);
}).show();
事件: negative#
dialog 对话框
取消按钮按下时触发的事件。例如：

var d = dialogs.build({
title: “标题”,
positive: “确定”,
negative: “取消”
}).on(“negative”, (dialog)=>{
toast(“你点击了取消”);
}).show();
事件: neutral#
dialog 对话框
中性按钮按下时触发的事件。例如：

var d = dialogs.build({
title: “标题”,
positive: “确定”,
negative: “取消”,
neutral: “稍后提示”
}).on(“positive”, (dialog)=>{
toast(“你点击了稍后提示”);
}).show();
事件: any#
dialog 对话框
action 被点击的按钮，可能的值为:
positive 确定按钮
negative 取消按钮
neutral 中性按钮
任意按钮按下时触发的事件。例如:

var d = dialogs.build({
title: “请选择”,
positive: “确定”,
negative: “取消”,
items: [“A”, “B”, “C”, “D”],
itemsSelectMode: “select”
}).on(“item_select”, (index, item, dialog)=>{
toast(“您选择的是第” + (index + 1) + “项, 选项为” + item);
}).show();
事件: single_choice#
index 被选中的项目索引，从0开始
item 被选中的项目
dialog 对话框
对话框单选列表(itemsSelectMode为"singleChoice")的项目被选中并点击确定时触发的事件。例如：

var d = dialogs.build({
title: “请选择”,
positive: “确定”,
negative: “取消”,
items: [“A”, “B”, “C”, “D”],
itemsSelectMode: “singleChoice”
}).on(“item_select”, (index, item, dialog)=>{
toast(“您选择的是第” + (index + 1) + “项, 选项为” + item);
}).show();
事件: multi_choice#
indices 被选中的项目的索引的数组
items 被选中的项目的数组
dialog 对话框
对话框多选列表(itemsSelectMode为"multiChoice")的项目被选中并点击确定时触发的事件。例如：

var d = dialogs.build({
title: “请选择”,
positive: “确定”,
negative: “取消”,
items: [“A”, “B”, “C”, “D”],
itemsSelectMode: “multiChoice”
}).on(“item_select”, (indices, items, dialog)=>{
toast(util.format(“您选择的项目为%o, 选项为%o”, indices, items);
}).show();
事件: input#
text 输入框的内容
dialog 对话框
带有输入框的对话框当点击确定时会触发的事件。例如：

dialogs.build({
title: “请输入”,
positive: “确定”,
negative: “取消”,
inputPrefill: “”
}).on(“input”, (text, dialog)=>{
toast(“你输入的是” + text);
}).show();
事件: input_change#
text 输入框的内容
dialog 对话框
对话框的输入框的文本发生变化时会触发的事件。例如：

dialogs.build({
title: “请输入”,
positive: “确定”,
negative: “取消”,
inputPrefill: “”
}).on(“input_change”, (text, dialog)=>{
toast(“你输入的是” + text);
}).show();
dialog.getProgress()#
返回
获取当前进度条的进度值，是一个整数

dialog.getMaxProgress()#
返回
获取当前进度条的最大进度值，是一个整数

dialog.getActionButton(action)#
action 动作，包括:
positive
negative
neutral
Engines#
Stability: 2 - Stable
engines模块包含了一些与脚本环境、脚本运行、脚本引擎有关的函数，包括运行其他脚本，关闭脚本等。

例如，获取脚本所在目录：

toast(engines.myEngine().cwd());
engines.execScript(name, script[, config])#
name 要运行的脚本名称。这个名称和文件名称无关，只是在任务管理中显示的名称。
script 要运行的脚本内容。
config 运行配置项
delay 延迟执行的毫秒数，默认为0
loopTimes 循环运行次数，默认为1。0为无限循环。
interval 循环运行时两次运行之间的时间间隔，默认为0
path | 指定脚本运行的目录。这些路径会用于require时寻找模块文件。
在新的脚本环境中运行脚本script。返回一个ScriptExectuion对象。

所谓新的脚本环境，指定是，脚本中的变量和原脚本的变量是不共享的，并且，脚本会在新的线程中运行。

最简单的例子如下：

engines.execScript(“hello world”, “toast(‘hello world’)”);
如果要循环运行，则：

//每隔3秒运行一次脚本，循环10次
engines.execScript(“hello world”, “toast(‘hello world’)”, {
loopTimes: 10,
interval: 3000
});
用字符串来编写脚本非常不方便，可以结合 Function.toString()的方法来执行特定函数:

function helloWorld(){
//注意，这里的变量和脚本主体的变量并不共享
toast(“hello world”);
}
engines.execScript(“hello world”, “helloWorld();\n” + helloWorld.toString());
如果要传递变量，则可以把这些封装成一个函数：

function exec(action, args){
args = args || {};
engines.execScript(action.name, action.name + “(” + JSON.stringify(args) + “);\n” + action.toString());
}

//要执行的函数，是一个简单的加法
function add(args){
toast(args.a + args.b);
}

//在新的脚本环境中执行 1 + 2
exec(add, {a: 1, b:2});
engines.execScriptFile(path[, config])#
path 要运行的脚本路径。
config 运行配置项
delay 延迟执行的毫秒数，默认为0
loopTimes 循环运行次数，默认为1。0为无限循环。
interval 循环运行时两次运行之间的时间间隔，默认为0
path | 指定脚本运行的目录。这些路径会用于require时寻找模块文件。
在新的脚本环境中运行脚本文件path。返回一个ScriptExecution对象。

engines.execScriptFile("/sdcard/脚本/1.js");
engines.execAutoFile(path[, config])#
path 要运行的录制文件路径。
config 运行配置项
delay 延迟执行的毫秒数，默认为0
loopTimes 循环运行次数，默认为1。0为无限循环。
interval 循环运行时两次运行之间的时间间隔，默认为0
path | 指定脚本运行的目录。这些路径会用于require时寻找模块文件。
在新的脚本环境中运行录制文件path。返回一个ScriptExecution对象。

engines.execAutoFile("/sdcard/脚本/1.auto");
engines.stopAll()#
停止所有正在运行的脚本。包括当前脚本自身。

engines.stopAllAndToast()#
停止所有正在运行的脚本并显示停止的脚本数量。包括当前脚本自身。

engines.myEngine()#
返回当前脚本的脚本引擎对象(ScriptEngine)

[v4.1.0新增] 特别的，该对象可以通过execArgv来获取他的运行参数，包括外部参数、intent等。例如：

log(engines.myEngine().execArgv);
普通脚本的运行参数通常为空，通过定时任务的广播启动的则可以获取到启动的intent。

engines.all()#
返回
返回当前所有正在运行的脚本的脚本引擎ScriptEngine的数组。

log(engines.all());
ScriptExecution#
执行脚本时返回的对象，可以通过他获取执行的引擎、配置等，也可以停止这个执行。

要停止这个脚本的执行，使用exectuion.getEngine().forceStop().

ScriptExecution.getEngine()#
返回执行该脚本的脚本引擎对象(ScriptEngine)

ScriptExecution.getConfig()#
返回该脚本的运行配置(ScriptConfig)

ScriptEngine#
脚本引擎对象。

ScriptEngine.forceStop()#
停止脚本引擎的执行。

ScriptEngine.cwd()#
返回
返回脚本执行的路径。对于一个脚本文件而言为这个脚本所在的文件夹；对于其他脚本，例如字符串脚本，则为null或者执行时的设置值。

ScriptEngine.getSource()#
返回 ScriptSource
返回当前脚本引擎正在执行的脚本对象。

log(engines.myEngine().getSource());
ScriptEngine.emit(eventName[, …args])#
eventName 事件名称
…args 事件参数
向该脚本引擎发送一个事件，该事件可以在该脚本引擎对应的脚本的events模块监听到并在脚本主线程执行事件处理。

例如脚本receiver.js的内容如下：

//监听say事件
events.on(“say”, function(words){
toastLog(words);
});
//保持脚本运行
setInterval(()=>{}, 1000);
同一目录另一脚本可以启动他并发送该事件：

//运行脚本
var e = engines.execScriptFile("./receiver.js");
//等待脚本启动
sleep(2000);
//向该脚本发送事件
e.getEngine().emit(“say”, “你好”);
ScriptConfig#
脚本执行时的配置。

delay#

延迟执行的毫秒数

interval#

循环运行时两次运行之间的时间间隔

loopTimes#

循环运行次数

getPath()#
返回
返回一个字符串数组表示脚本运行时模块寻找的路径。

Events#
Stability: 2 - Stable
events模块提供了监听手机通知、按键、触摸的接口。您可以用他配合自动操作函数完成自动化工作。

events本身是一个EventEmiiter, 但内置了一些事件、包括按键事件、通知事件、Toast事件等。

需要注意的是，事件的处理是单线程的，并且仍然在原线程执行，如果脚本主体或者其他事件处理中有耗时操作、轮询等，则事件将无法得到及时处理（会进入事件队列等待脚本主体或其他事件处理完成才执行）。例如:

auto();
events.observeNotification();
events.on(‘toast’, function(t){
//这段代码将得不到执行
log(t);
});
while(true){
//死循环
}
events.emitter()#
返回一个新的EventEmitter。这个EventEmitter没有内置任何事件。

events.observeKey()#
启用按键监听，例如音量键、Home键。按键监听使用无障碍服务实现，如果无障碍服务未启用会抛出异常并提示开启。

只有这个函数成功执行后, onKeyDown, onKeyUp等按键事件的监听才有效。

该函数在安卓4.3以上才能使用。

events.onKeyDown(keyName, listener)#
keyName 要监听的按键名称
listener 按键监听器。参数为一个KeyEvent。
注册一个按键监听函数，当有keyName对应的按键被按下会调用该函数。可用的按键名称参见Keys。

例如:

//启用按键监听
events.observeKey();
//监听音量上键按下
events.onKeyDown(“volume_up”, function(event){
toast(“音量上键被按下了”);
});
//监听菜单键按下
events.onKeyDown(“menu”, function(event){
toast(“菜单键被按下了”);
exit();
});
events.onKeyUp(keyName, listener)#
keyName 要监听的按键名称
listener 按键监听器。参数为一个KeyEvent。
注册一个按键监听函数，当有keyName对应的按键弹起会调用该函数。可用的按键名称参见Keys。

一次完整的按键动作包括了按键按下和弹起。按下事件会在手指按下一个按键的"瞬间"触发, 弹起事件则在手指放开这个按键时触发。

例如:

//启用按键监听
events.observeKey();
//监听音量下键弹起
events.onKeyDown(“volume_down”, function(event){
toast(“音量上键弹起”);
});
//监听Home键弹起
events.onKeyDown(“home”, function(event){
toast(“Home键弹起”);
exit();
});
events.onceKeyDown(keyName, listener)#
keyName 要监听的按键名称
listener 按键监听器。参数为一个KeyEvent
注册一个按键监听函数，当有keyName对应的按键被按下时会调用该函数，之后会注销该按键监听器。

也就是listener只有在onceKeyDown调用后的第一次按键事件被调用一次。

events.onceKeyUp(keyName, listener)#
keyName 要监听的按键名称
listener 按键监听器。参数为一个KeyEvent
注册一个按键监听函数，当有keyName对应的按键弹起时会调用该函数，之后会注销该按键监听器。

也就是listener只有在onceKeyUp调用后的第一次按键事件被调用一次。

events.removeAllKeyDownListeners(keyName)#
keyName 按键名称
删除该按键的KeyDown(按下)事件的所有监听。

events.removeAllKeyUpListeners(keyName)#
keyName 按键名称
删除该按键的KeyUp(弹起)事件的所有监听。

events.setKeyInterceptionEnabled([key, ]enabled)#
enabled
key 要屏蔽的按键
设置按键屏蔽是否启用。所谓按键屏蔽指的是，屏蔽原有按键的功能，例如使得音量键不再能调节音量，但此时仍然能通过按键事件监听按键。

如果不加参数key则会屏蔽所有按键。

例如，调用events.setKeyInterceptionEnabled(true)会使系统的音量、Home、返回等键不再具有调节音量、回到主页、返回的作用，但此时仍然能通过按键事件监听按键。

该函数通常于按键监听结合，例如想监听音量键并使音量键按下时不弹出音量调节框则为：

events.setKeyInterceptionEnabled(“volume_up”, true);
events.observeKey();
events.onKeyDown(“volume_up”, ()=>{
log(“音量上键被按下”);
});
只要有一个脚本屏蔽了某个按键，该按键便会被屏蔽；当脚本退出时，会自动解除所有按键屏蔽。

events.observeTouch()#
启用屏幕触摸监听。（需要root权限）

只有这个函数被成功执行后, 触摸事件的监听才有效。

没有root权限调用该函数则什么也不会发生。

events.setTouchEventTimeout(timeout)#
timeout 两个触摸事件的最小间隔。单位毫秒。默认为10毫秒。如果number小于0，视为0处理。
设置两个触摸事件分发的最小时间间隔。

例如间隔为10毫秒的话，前一个触摸事件发生并被注册的监听器处理后，至少要过10毫秒才能分发和处理下一个触摸事件，这10毫秒之间的触摸将会被忽略。

建议在满足需要的情况下尽量提高这个间隔。一个简单滑动动作可能会连续触发上百个触摸事件，如果timeout设置过低可能造成事件拥堵。强烈建议不要设置timeout为0。

events.getTouchEventTimeout()#
返回触摸事件的最小时间间隔。

events.onTouch(listener)#
listener 参数为Point的函数
注册一个触摸监听函数。相当于on(“touch”, listener)。

例如:

//启用触摸监听
events.observeTouch();
//注册触摸监听器
events.onTouch(function§{
//触摸事件发生时, 打印出触摸的点的坐标
log(p.x + ", " + p.y);
});
events.removeAllTouchListeners()#
删除所有事件监听函数。

事件: ‘key’#
keyCode 键值
event 事件
当有按键被按下或弹起时会触发该事件。例如：

auto();
events.observeKey();
events.on(“key”, function(keyCode, event){
//处理按键事件
});
其中监听器的参数KeyCode包括：

keys.home 主页键
keys.back 返回键
keys.menu 菜单键
keys.volume_up 音量上键
keys.volume_down 音量下键
例如：

auto();
events.observeKey();
events.on(“key”, function(keyCode, event){
if(keyCode == keys.menu && event.getAction() == event.ACTION_UP){
toast(“菜单键按下”);
}
});
事件: ‘key_down’#
keyCode 键值
event 事件
当有按键被按下时会触发该事件。

auto();
events.observeKey();
events.on(“key_down”, function(keyCode, event){
//处理按键按下事件
});
事件: ‘key_up’#
keyCode 键值
event 事件
当有按键弹起时会触发该事件。

auto();
events.observeKey();
events.on(“key_up”, function(keyCode, event){
//处理按键弹起事件
});
事件: 'exit`#
当脚本正常或者异常退出时会触发该事件。事件处理中如果有异常抛出，则立即中止exit事件的处理（即使exit事件有多个处理函数）并在控制台和日志中打印该异常。

一个脚本停止运行时，会关闭该脚本的所有悬浮窗，触发exit事件，之后再回收资源。如果exit事件的处理中有死循环，则后续资源无法得到及时回收。此时脚本会停留在任务列表，如果在任务列表中关闭，则会强制结束exit事件的处理并回收后续资源。

log(“开始运行”)
events.on(“exit”, function(){
log(“结束运行”);
});
log(“即将结束运行”);
events.observeNotification()#
开启通知监听。例如QQ消息、微信消息、推送等通知。

通知监听依赖于通知服务，如果通知服务没有运行，会抛出异常并跳转到通知权限开启界面。（有时即使通知权限已经开启通知服务也没有运行，这时需要关闭权限再重新开启一次）

例如：

events.obverseNotification();
events.onNotification(function(notification){
log(notification.getText());
});
events.observeToast()#
开启Toast监听。

Toast监听依赖于无障碍服务，因此此函数会确保无障碍服务运行。

事件: ‘toast’#
toast
getText() 获取Toast的文本内容
getPackageName() 获取发出Toast的应用包名
当有应用发出toast(气泡消息)时会触发该事件。但Auto.js软件本身的toast除外。

例如，要记录发出所有toast的应用：

events.observeToast();
events.onToast(function(toast){
log("Toast内容: " + toast.getText() + " 包名: " + toast.getPackageName());
});
事件: ‘notification’#
notification Notification 通知对象
当有应用发出通知时会触发该事件，参数为Notification。

例如：

events.observeNotification();
events.on(“notification”, function(n){
log(“收到新通知:\n 标题: %s, 内容: %s, \n包名: %s”, n.getTitle(), n.getText(), n.getPackageName());
});
Notification#
通知对象，可以获取通知详情，包括通知标题、内容、发出通知的包名、时间等，也可以对通知进行操作，比如点击、删除。

Notification.number#

通知数量。例如QQ连续收到两条消息时number为2。

Notification.when#

通知发出时间的时间戳，可以用于构造Date对象。例如：

events.observeNotification();
events.on(“notification”, function(n){
log(“通知时间为}” + new Date(n.when));
});
Notification.getPackageName()#
返回
获取发出通知的应用包名。

Notification.getTitle()#
返回
获取通知的标题。

Notification.getText()#
返回
获取通知的内容。

Notification.click()#
点击该通知。例如对于一条QQ消息，点击会进入具体的聊天界面。

Notification.delete()#
删除该通知。该通知将从通知栏中消失。

KeyEvent#
Stability: 2 - Stable
KeyEvent.getAction()#
返回事件的动作。包括：

KeyEvent.ACTION_DOWN 按下事件
KeyEvent.ACTION_UP 弹起事件
KeyEvent.getKeyCode()#
返回按键的键值。包括：

KeyEvent.KEYCODE_HOME 主页键
KeyEvent.KEYCODE_BACK 返回键
KeyEvent.KEYCODE_MENU 菜单键
KeyEvent.KEYCODE_VOLUME_UP 音量上键
KeyEvent.KEYCODE_VOLUME_DOWN 音量下键
KeyEvent.getEventTime()#
返回
返回事件发生的时间戳。

KeyEvent.getDownTime()#
返回最近一次按下事件的时间戳。如果本身是按下事件，则与getEventTime()相同。

KeyEvent.keyCodeToString(keyCode)#
把键值转换为字符串。例如KEYCODE_HOME转换为"KEYCODE_HOME"。

keys#
Stability: 2 - Stable
按键事件中所有可用的按键名称为：

volume_up 音量上键
volume_down 音量下键
home 主屏幕键
back 返回键
menu 菜单键
EventEmitter#
Stability: 2 - Stable
EventEmitter.defaultMaxListeners#
每个事件默认可以注册最多 10 个监听器。单个 EventEmitter 实例的限制可以使用 emitter.setMaxListeners(n) 方法改变。所有 EventEmitter 实例的默认值可以使用 EventEmitter.defaultMaxListeners 属性改变。

设置 EventEmitter.defaultMaxListeners 要谨慎，因为会影响所有 EventEmitter 实例，包括之前创建的。因而，调用 emitter.setMaxListeners(n) 优先于 EventEmitter.defaultMaxListeners。

注意，与Node.js不同，这是一个硬性限制。 EventEmitter 实例不允许添加更多的监听器，监听器超过最大数量时会抛出TooManyListenersException。

emitter.setMaxListeners(emitter.getMaxListeners() + 1);
emitter.once(‘event’, () => {
// 做些操作
emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0));
});
EventEmitter.addListener(eventName, listener)#
eventName
listener
emitter.on(eventName, listener) 的别名。

EventEmitter.emit(eventName[, …args])#
eventName
args
按监听器的注册顺序，同步地调用每个注册到名为 eventName 事件的监听器，并传入提供的参数。

如果事件有监听器，则返回 true ，否则返回 false。

EventEmitter.eventNames()#
返回一个列出触发器已注册监听器的事件的数组。数组中的值为字符串或符号。

const myEE = events.emitter();
myEE.on(‘foo’, () => {});
myEE.on(‘bar’, () => {});

const sym = Symbol(‘symbol’);
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// 打印: [ ‘foo’, ‘bar’, Symbol(symbol) ]
EventEmitter.getMaxListeners()#
返回 EventEmitter 当前的最大监听器限制值，该值可以通过 emitter.setMaxListeners(n) 设置或默认为 EventEmitter.defaultMaxListeners。

EventEmitter.listenerCount(eventName)#
eventName 正在被监听的事件名
返回正在监听名为 eventName 的事件的监听器的数量。

EventEmitter.listeners(eventName)#
eventName
返回名为 eventName 的事件的监听器数组的副本。

server.on(‘connection’, (stream) => {
console.log(‘someone connected!’);
});
console.log(util.inspect(server.listeners(‘connection’)));
// 打印: [ [Function] ]
EventEmitter.on(eventName, listener)#
eventName 事件名
listener 回调函数
添加 listener 函数到名为 eventName 的事件的监听器数组的末尾。不会检查 listener 是否已被添加。多次调用并传入相同的 eventName 和 listener 会导致 listener 被添加与调用多次。

server.on(‘connection’, (stream) => {
console.log(‘有连接！’);
});
返回一个 EventEmitter 引用，可以链式调用。

默认情况下，事件监听器会按照添加的顺序依次调用。 emitter.prependListener() 方法可用于将事件监听器添加到监听器数组的开头。

const myEE = events.emitter();
myEE.on(‘foo’, () => console.log(‘a’));
myEE.prependListener(‘foo’, () => console.log(‘b’));
myEE.emit(‘foo’);
// 打印:
// b
// a
EventEmitter.once(eventName, listener)#
eventName 事件名
listener 回调函数
添加一个单次 listener 函数到名为 eventName 的事件。下次触发 eventName 事件时，监听器会被移除，然后调用。

server.once(‘connection’, (stream) => {
console.log(‘首次调用！’);
});
返回一个 EventEmitter 引用，可以链式调用。

默认情况下，事件监听器会按照添加的顺序依次调用。 emitter.prependOnceListener() 方法可用于将事件监听器添加到监听器数组的开头。

const myEE = events.emitter();
myEE.once(‘foo’, () => console.log(‘a’));
myEE.prependOnceListener(‘foo’, () => console.log(‘b’));
myEE.emit(‘foo’);
// 打印:
// b
// a
EventEmitter.prependListener(eventName, listener)#
eventName 事件名
listener 回调函数
添加 listener 函数到名为 eventName 的事件的监听器数组的开头。不会检查 listener 是否已被添加。多次调用并传入相同的 eventName 和 listener 会导致 listener 被添加与调用多次。

server.prependListener(‘connection’, (stream) => {
console.log(‘有连接！’);
});
返回一个 EventEmitter 引用，可以链式调用。

EventEmitter.prependOnceListener(eventName, listener)#
eventName 事件名
listener 回调函数
添加一个单次 listener 函数到名为 eventName 的事件的监听器数组的开头。下次触发 eventName 事件时，监听器会被移除，然后调用。

server.prependOnceListener(‘connection’, (stream) => {
console.log(‘首次调用！’);
});
返回一个 EventEmitter 引用，可以链式调用。

EventEmitter.removeAllListeners([eventName])#
eventName
移除全部或指定 eventName 的监听器。

注意，在代码中移除其他地方添加的监听器是一个不好的做法，尤其是当 EventEmitter 实例是其他组件或模块创建的。

返回一个 EventEmitter 引用，可以链式调用。

EventEmitter.removeListener(eventName, listener)#
eventName
listener
从名为 eventName 的事件的监听器数组中移除指定的 listener。

const callback = (stream) => {
console.log(‘有连接！’);
};
server.on(‘connection’, callback);
// …
server.removeListener(‘connection’, callback);
removeListener 最多只会从监听器数组里移除一个监听器实例。如果任何单一的监听器被多次添加到指定 eventName 的监听器数组中，则必须多次调用 removeListener 才能移除每个实例。

注意，一旦一个事件被触发，所有绑定到它的监听器都会按顺序依次触发。这意味着，在事件触发后、最后一个监听器完成执行前，任何 removeListener() 或 removeAllListeners() 调用都不会从 emit() 中移除它们。随后的事件会像预期的那样发生。

const myEmitter = events.emitter();

const callbackA = () => {
console.log(‘A’);
myEmitter.removeListener(‘event’, callbackB);
};

const callbackB = () => {
console.log(‘B’);
};

myEmitter.on(‘event’, callbackA);

myEmitter.on(‘event’, callbackB);

// callbackA 移除了监听器 callbackB，但它依然会被调用。
// 触发是内部的监听器数组为 [callbackA, callbackB]
myEmitter.emit(‘event’);
// 打印:
// A
// B

// callbackB 被移除了。
// 内部监听器数组为 [callbackA]
myEmitter.emit(‘event’);
// 打印:
// A
因为监听器是使用内部数组进行管理的，所以调用它会改变在监听器被移除后注册的任何监听器的位置索引。虽然这不会影响监听器的调用顺序，但意味着由 emitter.listeners() 方法返回的监听器数组副本需要被重新创建。

返回一个 EventEmitter 引用，可以链式调用。

EventEmitter.setMaxListeners(n)#
n
默认情况下，如果为特定事件添加了超过 10 个监听器，则 EventEmitter 会打印一个警告。此限制有助于寻找内存泄露。但是，并不是所有的事件都要被限为 10 个。 emitter.setMaxListeners() 方法允许修改指定的 EventEmitter 实例的限制。值设为 Infinity（或 0）表明不限制监听器的数量。

返回一个 EventEmitter 引用，可以链式调用。

events.broadcast: 脚本间广播#
脚本间通信除了使用engines模块提供的ScriptEngine.emit()方法以外，也可以使用events模块提供的broadcast广播。

events.broadcast本身是一个EventEmitter，但它的事件是在脚本间共享的，所有脚本都能发送和监听这些事件；事件处理会在脚本主线程执行（后续可能加入函数onThisThread(eventName, …args)来提供在其他线程执行的能力）。

例如在一个脚本发送一个广播hello:

events.broadcast.emit(“hello”, “小明”);
在其他脚本中监听并处理：

events.broadcast.on(“hello”, function(name){
toast("你好, " + name);
});
//保持脚本运行
setInterval(()=>{}, 1000);
Floaty#
floaty模块提供了悬浮窗的相关函数，可以在屏幕上显示自定义悬浮窗，控制悬浮窗大小、位置等。

悬浮窗在脚本停止运行时会自动关闭，因此，要保持悬浮窗不被关闭，可以用一个空的setInterval来实现，例如：

setInterval(()=>{}, 1000);
floaty.window(layout)#
layout | 悬浮窗界面的XML或者View
指定悬浮窗的布局，创建并显示一个悬浮窗，返回一个FloatyWindow对象。

该悬浮窗自带关闭、调整大小、调整位置按键，可根据需要调用setAdjustEnabled()函数来显示或隐藏。

其中layout参数可以是xml布局或者一个View，更多信息参见ui模块的说明。

例子：

var w = floaty.window(

悬浮文字

);
setTimeout(()=>{
w.close();
}, 2000);
这段代码运行后将会在屏幕上显示悬浮文字，并在两秒后消失。

另外，因为脚本运行的线程不是UI线程，而所有对控件的修改操作需要在UI线程执行，此时需要用ui.run，例如:

ui.run(function(){
w.text.setText(“文本”);
});
有关返回的FloatyWindow对象的说明，参见下面的FloatyWindow章节。

floaty.rawWindow(layout)#
layout | 悬浮窗界面的XML或者View
指定悬浮窗的布局，创建并显示一个原始悬浮窗，返回一个FloatyRawWindow对象。

与floaty.window()函数不同的是，该悬浮窗不会增加任何额外设施（例如调整大小、位置按钮），您可以根据自己需要编写任何布局。

而且，该悬浮窗支持完全全屏，可以覆盖状态栏，因此可以做护眼模式之类的应用。

var w = floaty.rawWindow(

悬浮文字

);

w.setPosition(500, 500);

setTimeout(()=>{
w.close();
}, 2000);
这段代码运行后将会在屏幕上显示悬浮文字，并在两秒后消失。

有关返回的FloatyRawWindow对象的说明，参见下面的FloatyRawWindow章节。

floaty.closeAll()#
关闭所有本脚本的悬浮窗。

FloatyWindow#
悬浮窗对象，可通过FloatyWindow.{id}获取悬浮窗界面上的元素。例如, 悬浮窗window上一个控件的id为aaa, 那么window.aaa即可获取到该控件，类似于ui。

window.setAdjustEnabled(enabled)#
enabled 是否启用悬浮窗调整(大小、位置)
如果enabled为true，则在悬浮窗左上角、右上角显示可供位置、大小调整的标示，就像控制台一样；如果enabled为false，则隐藏上述标示。

window.setPosition(x, y)#
x x
x y
设置悬浮窗位置。

window.getX()#
返回悬浮窗位置的X坐标。

window.getY()#
返回悬浮窗位置的Y坐标。

window.setSize(width, height)#
width 宽度
height 高度
设置悬浮窗宽高。

window.getWidht()#
返回悬浮窗宽度。

window.getHeight()#
返回悬浮窗高度。

window.close()#
关闭悬浮窗。如果悬浮窗已经是关闭状态，则此函数将不执行任何操作。

被关闭后的悬浮窗不能再显示。

window.exitOnClose()#
使悬浮窗被关闭时自动结束脚本运行。

FloatyRawWindow#
原始悬浮窗对象，可通过window.{id}获取悬浮窗界面上的元素。例如, 悬浮窗window上一个控件的id为aaa, 那么window.aaa即可获取到该控件，类似于ui。

window.setTouchable(touchable)#
touchable 是否可触摸
设置悬浮窗是否可触摸，如果为true, 则悬浮窗将接收到触摸、点击等事件并且无法继续传递到悬浮窗下面；如果为false, 悬浮窗上的触摸、点击等事件将被直接传递到悬浮窗下面。处于安全考虑，被悬浮窗接收的触摸事情无法再继续传递到下层。

可以用此特性来制作护眼模式脚本。

var w = floaty.rawWindow(

);

w.setSize(-1, -1);
w.setTouchable(false);

setTimeout(()=>{
w.close();
}, 4000);

window.setPosition(x, y)#
x x
x y
设置悬浮窗位置。

window.getX()#
返回悬浮窗位置的X坐标。

window.getY()#
返回悬浮窗位置的Y坐标。

window.setSize(width, height)#
width 宽度
height 高度
设置悬浮窗宽高。

特别地，如果设置为-1，则为占满全屏；设置为-2则为根据悬浮窗内容大小而定。例如：

var w = floaty.rawWindow(

悬浮文字

);

w.setSize(-1, -1);

setTimeout(()=>{
w.close();
}, 2000);

window.getWidht()#
返回悬浮窗宽度。

window.getHeight()#
返回悬浮窗高度。

window.close()#
关闭悬浮窗。如果悬浮窗已经是关闭状态，则此函数将不执行任何操作。

被关闭后的悬浮窗不能再显示。

window.exitOnClose()#
使悬浮窗被关闭时自动结束脚本运行。

Files#
Stability: 2 - Stable
files模块提供了一些常见的文件处理，包括文件读写、移动、复制、删掉等。

一次性的文件读写可以直接使用files.read(), files.write(), files.append()等方便的函数，但如果需要频繁读写或随机读写，则使用open()函数打开一个文件对象来操作文件，并在操作完毕后调用close()函数关闭文件。

files.isFile(path)#
path 路径
返回
返回路径path是否是文件。

log(files.isDir("/sdcard/文件夹/")); //返回false
log(files.isDir("/sdcard/文件.txt")); //返回true
files.isDir(path)#
path 路径
返回
返回路径path是否是文件夹。

log(files.isDir("/sdcard/文件夹/")); //返回true
log(files.isDir("/sdcard/文件.txt")); //返回false
files.isEmptyDir(path)#
path 路径
返回
返回文件夹path是否为空文件夹。如果该路径并非文件夹，则直接返回false。

files.join(parent, child)#
parent 父目录路径
child 子路径
返回
连接两个路径并返回，例如files.join("/sdcard/", “1.txt”)返回"/sdcard/1.txt"。

files.create(path)#
path 路径
返回
创建一个文件或文件夹并返回是否创建成功。如果文件已经存在，则直接返回false。

files.create("/sdcard/新文件夹/");
files.createWithDirs(path)#
path 路径
返回
创建一个文件或文件夹并返回是否创建成功。如果文件所在文件夹不存在，则先创建他所在的一系列文件夹。如果文件已经存在，则直接返回false。

files.createWithDirs("/sdcard/新文件夹/新文件夹/新文件夹/1.txt");
files.exists(path)#
path 路径
返回
返回在路径path处的文件是否存在。

files.ensureDir(path)#
path 路径
确保路径path所在的文件夹存在。如果该路径所在文件夹不存在，则创建该文件夹。

例如对于路径"/sdcard/Download/ABC/1.txt"，如果/Download/文件夹不存在，则会先创建Download，再创建ABC文件夹。

files.read(path[, encoding = “utf-8”])#
path 路径
encoding 字符编码，可选，默认为utf-8
返回
读取文本文件path的所有内容并返回。如果文件不存在，则抛出FileNotFoundException。

log(files.read("/sdcard/1.txt"));
files.readBytes(path)#
path 路径
返回 <byte[]>
读取文件path的所有内容并返回一个字节数组。如果文件不存在，则抛出FileNotFoundException。

注意，该数组是Java的数组，不具有JavaScript数组的forEach, slice等函数。

一个以16进制形式打印文件的例子如下:

var data = files.readBytes("/sdcard/1.png");
var sb = new java.lang.StringBuilder();
for(var i = 0; i < data.length; i++){
sb.append(data[i].toString(16));
}
log(sb.toString());
files.write(path, text[, encoding = “utf-8”])#
path 路径
text 要写入的文本内容
encoding 字符编码
把text写入到文件path中。如果文件存在则覆盖，不存在则创建。

var text = “文件内容”;
//写入文件
files.write("/sdcard/1.txt", text);
//用其他应用查看文件
app.viewFile("/sdcard/1.txt");
files.writeBytes(path, bytes)#
path 路径
bytes <byte[]> 字节数组，要写入的二进制数据
把bytes写入到文件path中。如果文件存在则覆盖，不存在则创建。

files.append(path, text[, encoding = ‘utf-8’])#
path 路径
text 要写入的文本内容
encoding 字符编码
把text追加到文件path的末尾。如果文件不存在则创建。

var text = “追加的文件内容”;
files.append("/sdcard/1.txt", text);
files.append("/sdcard/1.txt", text);
//用其他应用查看文件
app.viewFile("/sdcard/1.txt");
files.appendBytes(path, text[, encoding = ‘utf-8’])#
path 路径
bytes <byte[]> 字节数组，要写入的二进制数据
把bytes追加到文件path的末尾。如果文件不存在则创建。

files.copy(fromPath, toPath)#
fromPath 要复制的原文件路径
toPath 复制到的文件路径
返回
复制文件，返回是否复制成功。例如files.copy("/sdcard/1.txt", “/sdcard/Download/1.txt”)。

files.move(fromPath, toPath)#
fromPath 要移动的原文件路径
toPath 移动到的文件路径
返回
移动文件，返回是否移动成功。例如files.move("/sdcard/1.txt", “/sdcard/Download/1.txt”)会把1.txt文件从sd卡根目录移动到Download文件夹。

files.rename(path, newName)#
path 要重命名的原文件路径
newName 要重命名的新文件名
返回
重命名文件，并返回是否重命名成功。例如files.rename("/sdcard/1.txt", “2.txt”)。

files.renameWithoutExtension(path, newName)#
path 要重命名的原文件路径
newName 要重命名的新文件名
返回
重命名文件，不包含拓展名，并返回是否重命名成功。例如files.rename("/sdcard/1.txt", “2”)会把"1.txt"重命名为"2.txt"。

files.getName(path)#
path 路径
返回
返回文件的文件名。例如files.getName("/sdcard/1.txt")返回"1.txt"。

files.getNameWithoutExtension(path)#
path 路径
返回
返回不含拓展名的文件的文件名。例如files.getName("/sdcard/1.txt")返回"1"。

files.getExtension(path)#
path 路径
返回
返回文件的拓展名。例如files.getExtension("/sdcard/1.txt")返回"txt"。

files.remove(path)#
path 路径
返回
删除文件或空文件夹，返回是否删除成功。

files.removeDir(path)#
path 路径
path 路径
返回
删除文件夹，如果文件夹不为空，则删除该文件夹的所有内容再删除该文件夹，返回是否全部删除成功。

files.getSdcardPath()#
返回
返回SD卡路径。所谓SD卡，即外部存储器。

files.cwd()#
返回
返回脚本的"当前工作文件夹路径"。该路径指的是，如果脚本本身为脚本文件，则返回这个脚本文件所在目录；否则返回null获取其他设定路径。

例如，对于脚本文件"/sdcard/脚本/1.js"运行files.cwd()返回"/sdcard/脚本/"。

files.path(relativePath)#
relativePath 相对路径
返回
返回相对路径对应的绝对路径。例如files.path("./1.png")，如果运行这个语句的脚本位于文件夹"/sdcard/脚本/“中，则返回”/sdcard/脚本/1.png"。

files.listDir(path[, filter])#
path 路径
filter 过滤函数，可选。接收一个string参数（文件名），返回一个boolean值。
列出文件夹path下的满足条件的文件和文件夹的名称的数组。如果不加filter参数，则返回所有文件和文件夹。

列出sdcard目录下所有文件和文件夹为:

var arr = files.listDir("/sdcard/");
log(arr);
列出脚本目录下所有js脚本文件为:

var dir = “/sdcard/脚本/”;
var jsFiles = files.listDir(dir, function(name){
return name.endsWith(".js") && files.isFile(files.join(dir, name));
});
log(jsFiles);
open(path[, mode = “r”, encoding = “utf-8”, bufferSize = 8192])#
path 文件路径，例如"/sdcard/1.txt"。
mode 文件打开模式，包括:
“r”: 只读文本模式。该模式下只能对文件执行文本读取操作。
“w”: 只写文本模式。该模式下只能对文件执行文本覆盖写入操作。
“a”: 附加文本模式。该模式下将会把写入的文本附加到文件末尾。
“rw”: 随机读写文本模式。该模式下将会把写入的文本附加到文件末尾。
目前暂不支持二进制模式，随机读写模式。
encoding 字符编码。
bufferSize 文件读写的缓冲区大小。
打开一个文件。根据打开模式返回不同的文件对象。包括：

“r”: 返回一个ReadableTextFile对象。
“w”, “a”: 返回一个WritableTextFile对象。
对于"w"模式，如果文件并不存在，则会创建一个，已存在则会清空该文件内容；其他模式文件不存在会抛出FileNotFoundException。

ReadableTextFile#
可读文件对象。

ReadableTextFile.read()#
返回该文件剩余的所有内容的字符串。

ReadableTextFile.read(maxCount)#
maxCount 最大读取的字符数量
读取该文件接下来最长为maxCount的字符串并返回。即使文件剩余内容不足maxCount也不会出错。

ReadableTextFile.readline()#
读取一行并返回（不包含换行符）。

ReadableTextFile.readlines()#
读取剩余的所有行，并返回它们按顺序组成的字符串数组。

close()#
关闭该文件。

打开一个文件不再使用时务必关闭

PWritableTextFile#
可写文件对象。

PWritableTextFile.write(text)#
text 文本
把文本内容text写入到文件中。

PWritableTextFile.writeline(line)#
text 文本
把文本line写入到文件中并写入一个换行符。

PWritableTextFile.writelines(lines)#
lines 字符串数组
把很多行写入到文件中…

PWritableTextFile.flush()#
把缓冲区内容输出到文件中。

PWritableTextFile.close()#
关闭文件。同时会被缓冲区内容输出到文件。

打开一个文件写入后，不再使用时务必关闭，否则文件可能会丢失

全局变量与函数#
全局变量和函数在所有模块中均可使用。但以下变量的作用域只在模块内，详见 module：

exports
module
require() 以下的对象是特定于 Auto.js 的。有些内置对象是 JavaScript 语言本身的一部分，它们也是全局的。
一些模块中的函数为了使用方便也可以直接全局使用，这些函数在此不再赘述。例如timers模块的setInterval, setTimeout等函数。

sleep(n)#
n 毫秒数
暂停运行n毫秒的时间。1秒等于1000毫秒。

//暂停5秒
sleep(5000);
currentPackage()#
返回
返回最近一次监测到的正在运行的应用的包名，一般可以认为就是当前正在运行的应用的包名。

此函数依赖于无障碍服务，如果服务未启动，则抛出异常并提示用户启动。

currentActivity()#
返回
返回最近一次监测到的正在运行的Activity的名称，一般可以认为就是当前正在运行的Activity的名称。

此函数依赖于无障碍服务，如果服务未启动，则抛出异常并提示用户启动。

setClip(text)#
text 文本
设置剪贴板内容。此剪贴板即系统剪贴板，在一般应用的输入框中"粘贴"既可使用。

setClip(“剪贴板文本”);
getClip()#
返回
返回系统剪贴板的内容。

toast(“剪贴板内容为:” + getClip());
toast(message)#
message 要显示的信息
以气泡显示信息message几秒。(具体时间取决于安卓系统，一般都是2秒)

注意，信息的显示是"异步"执行的，并且，不会等待信息消失程序才继续执行。如果在循环中执行该命令，可能出现脚本停止运行后仍然有不断的气泡信息出现的情况。例如:

for(var i = 0; i < 100; i++){
toast(i);
}
运行这段程序以后，会很快执行完成，且不断弹出消息，在任务管理中关闭所有脚本也无法停止。要保证气泡消息才继续执行可以用：

for(var i = 0; i < 100; i++){
toast(i);
sleep(2000);
}
或者修改toast函数：

var toast = toast;
toast = function(message){
toast(message);
sleep(2000);
}
for(var i = 0; i < 100; i++){
toast(i);
}
toastLog(message)#
message 要显示的信息
相当于toast(message);log(message)。显示信息message并在控制台中输出。参见console.log。

waitForActivity(activity[, period = 200])#
activity Activity名称
period 轮询等待间隔（毫秒）
等待指定的Activity出现，period为检查Activity的间隔。

waitForPackage(package[, period = 200])#
package 包名
period 轮询等待间隔（毫秒）
等待指定的应用出现。例如waitForPackage(“com.tencent.mm”)为等待当前界面为微信。

exit()#
立即停止脚本运行。

立即停止是通过抛出ScriptInterrupttedException来实现的，因此如果用try…catch把exit()函数的异常捕捉，则脚本不会立即停止，仍会运行几行后再停止。

random(min, max)#
min 随机数产生的区间下界
max 随机数产生的区间上界
返回
返回一个在[min…max]之间的随机数。例如random(0, 2)可能产生0, 1, 2。

random()#
返回
返回在[0, 1)的随机浮点数。

requiresApi(api)#
api Android版本号
表示此脚本需要Android API版本达到指定版本才能运行。例如requiresApi(19)表示脚本需要在Android 4.4以及以上运行。

调用该函数时会判断运行脚本的设备系统的版本号，如果没有达到要求则抛出异常。

可以参考以下Android API和版本的对照表:

平台版本： API级别

Android 7.0： 24

Android 6.0： 23

Android 5.1： 22

Android 5.0： 21

Android 4.4W： 20

Android 4.4： 19

Android 4.3： 18

requiresAutojsVersion(version)#
version | Auto.js的版本或版本号
表示此脚本需要Auto.js版本达到指定版本才能运行。例如requiresAutojsVersion(“3.0.0 Beta”)表示脚本需要在Auto.js 3.0.0 Beta以及以上运行。

调用该函数时会判断运行脚本的Auto.js的版本号，如果没有达到要求则抛出异常。

version参数可以是整数表示版本号，例如requiresAutojsVersion(250)；也可以是字符串格式表示的版本，例如"3.0.0 Beta", “3.1.0 Alpha4”, "3.2.0"等。

可以通过app.autojs.versionCode和app.autojs.versionName获取当前的Auto.js版本号和版本。

runtime.requestPermissions(permissions)#
permissions 权限的字符串数组
动态申请安卓的权限。例如：

//请求GPS权限
runtime.requestPermissions([“access_fine_location”]);
尽管安卓有很多权限，但必须写入Manifest才能动态申请，为了防止权限的滥用，目前Auto.js只能额外申请两个权限：

access_fine_location GPS权限
record_audio 录音权限
您可以通过APK编辑器来增加Auto.js以及Auto.js打包的应用的权限。

安卓所有的权限列表参见Permissions Overview。（并没有用）

runtime.loadJar(path)#
path jar文件路径
加载目标jar文件，加载成功后将可以使用该Jar文件的类。

// 加载jsoup.jar
runtime.loadJar("./jsoup.jar");
// 使用jsoup解析html
importClass(org.jsoup.Jsoup);
log(Jsoup.parse(files.read("./test.html")));
(jsoup是一个Java实现的解析Html DOM的库，可以在Jsoup下载)

runtime.loadDex(path)#
path dex文件路径
加载目标dex文件，加载成功后将可以使用该dex文件的类。

因为加载jar实际上是把jar转换为dex再加载的，因此加载dex文件会比jar文件快得多。可以使用Android SDK的build tools的dx工具把jar转换为dex。

context#
全局变量。一个android.content.Context对象。

注意该对象为ApplicationContext，因此不能用于界面、对话框等的创建。
HTTP#
Stability: 2 - Stable
http模块提供一些进行http请求的函数。

http.get(url[, options, callback])#
url 请求的URL地址，需要以"http://"或"https://"开头。如果url没有以"http://“开头，则默认为"http://”。
options 请求选项。参见[http.request()][]。
callback 回调函数，可选，其参数是一个[Response][]对象。如果不加回调函数，则该请求将阻塞、同步地执行。
对地址url进行一次HTTP GET 请求。如果没有回调函数，则在请求完成或失败时返回此次请求的响应(参见[Response][])。

最简单GET请求如下:

console.show();
var r = http.get(“www.baidu.com”);
log("code = " + r.statusCode);
log("html = " + r.body.string());
采用回调形式的GET请求如下：

console.show();
http.get(“www.baidu.com”, {}, function(res, err){
if(err){
console.error(err);
return;
}
log("code = " + res.statusCode);
log("html = " + res.body.string());
});
如果要增加HTTP头部信息，则在options参数中添加，例如：

console.show();
var r = http.get(“www.baidu.com”, {
headers: {
‘Accept-Language’: ‘zh-cn,zh;q=0.5’,
‘User-Agent’: ‘Mozilla/5.0(Macintosh;IntelMacOSX10_7_0)AppleWebKit/535.11(KHTML,likeGecko)Chrome/17.0.963.56Safari/535.11’
}
});
log("code = " + r.statusCode);
log("html = " + r.body.string());
一个请求天气并解析返回的天气JSON结果的例子如下：

var city = “广州”;
var res = http.get(“http://www.sojson.com/open/api/weather/json.shtml?city=” + city);
if(res.statusCode != 200){
toast("请求失败: " + res.statusCode + " " + res.statusMessage);
}else{
var weather = res.body.json();
log(weather);
toast(util.format(“温度: %s 湿度: %s 空气质量: %s”, weather.data.wendu,
weather.data.shidu, weather.quality));
}
http.post(url, data[, options, callback])#
url 请求的URL地址，需要以"http://"或"https://"开头。如果url没有以"http://“开头，则默认为"http://”。
data | POST数据。
options 请求选项。
callback 回调，其参数是一个[Response][]对象。如果不加回调参数，则该请求将阻塞、同步地执行。
对地址url进行一次HTTP POST 请求。如果没有回调函数，则在请求完成或失败时返回此次请求的响应(参见[Response][])。

其中POST数据可以是字符串或键值对。具体含义取决于options.contentType的值。默认为"application/x-www-form-urlencoded"(表单提交), 这种方式是JQuery的ajax函数的默认方式。

一个模拟表单提交登录淘宝的例子如下:

JSON格式指的是，将会调用JSON.stringify()把data对象转换为JSON字符串，并在HTTP头部信息中把"Content-Type"属性置为"application/json"。这种方式是AngularJS的ajax函数的默认方式。

一个调用图灵机器人接口的例子如下：

var url = “http://www.tuling123.com/openapi/api”;
r = http.postJson(url, {
key: “65458a5df537443b89b31f1c03202a80”,
info: “你好啊”,
userid: “1”,
});
toastLog(r.body.string());
http.postMultipart(url, files[, options, callback])#
url 请求的URL地址，需要以"http://"或"https://"开头。如果url没有以"http://“开头，则默认为"http://”。
files POST数据。
options 请求选项。
callback 回调，其参数是一个Response对象。如果不加回调参数，则该请求将阻塞、同步地执行。
向目标地址发起类型为multipart/form-data的请求（通常用于文件上传等), 其中files参数是<name1: value1, name2: value2, …>的键值对，value的格式可以是以下几种情况：

string
文件类型，即open()返回的类型
[fileName, filePath]
[fileName, mimeType, filePath]
其中1属于非文件参数，2、3、4为文件参数。举个例子，最简单的文件上传的请求为：

var res = http.postMultipart(url, {
file: open("/sdcard/1.txt")
});
log(res.body.string());
如果使用格式2，则代码为

var res = http.postMultipart(url, {
file: [“1.txt”, “/sdcard/1.txt”]
});
log(res.body.string());
如果使用格式3，则代码为

var res = http.postMultipart(url, {
file: [“1.txt”, “text/plain”, “/sdcard/1.txt”]
});
log(res.body.string());
如果使用格式2的同时要附带非文件参数"appId=abcdefghijk"，则为:

var res = http.postMultipart(url, {
appId: “adcdefghijk”,
file: open("/sdcard/1.txt")
});
log(res.body.string());
http.request(url[, options, callback])#
url 请求的URL地址，需要以"http://"或"https://"开头。如果url没有以"http://“开头，则默认为"http://”。
options 请求选项。参见[http.buildRequest()][]。
callback 回调，其参数是一个[Response][]对象。如果不加回调参数，则该请求将阻塞、同步地执行。
对目标地址url发起一次HTTP请求。如果没有回调函数，则在请求完成或失败时返回此次请求的响应(参见[Response][])。

选项options可以包含以下属性：

headers 键值对形式的HTTP头部信息。有关HTTP头部信息，参见菜鸟教程：HTTP响应头信息。
method HTTP请求方法。包括"GET", “POST”, “PUT”, “DELET”, “PATCH”。
contentType HTTP头部信息中的"Content-Type", 表示HTTP请求的内容类型。例如"text/plain", “application/json”。更多信息参见菜鸟教程：HTTP contentType。
body | | HTTP请求的内容。可以是一个字符串，也可以是一个字节数组；或者是一个以BufferedSink为参数的函数。
该函数是get, post, postJson等函数的基础函数。因此除非是PUT, DELET等请求，或者需要更高定制的HTTP请求，否则直接使用get, post, postJson等函数会更加方便。

Response#
HTTP请求的响应。

Response.statusCode#

当前响应的HTTP状态码。例如200(OK), 404(Not Found)等。

有关HTTP状态码的信息，参见菜鸟教程：HTTP状态码。

Response.statusMessage#

当前响应的HTTP状态信息。例如"OK", “Bad Request”, “Forbidden”。

有关HTTP状态码的信息，参见菜鸟教程：HTTP状态码。

例子：

当前响应的HTTP头部信息。该对象的键是响应头名称，值是各自的响应头值。所有响应头名称都是小写的(吗)。

有关HTTP头部信息，参见菜鸟教程：HTTP响应头信息。

例子:

console.show();
var res = http.get(“www.qq.com”);
console.log(“HTTP Headers:”)
for(var headerName in res.headers){
console.log("%s: %s", headerName, res.headers[headerName]);
}
Response.body#

当前响应的内容。他有以下属性和函数：

bytes() 以字节数组形式返回响应内容
string() 以字符串形式返回响应内容
json() 把响应内容作为JSON格式的数据并调用JSON.parse，返回解析后的对象
contentType 当前响应的内容类型
Response.request#
当前响应所对应的请求。参见[Request][]。
Response.url#
当前响应所对应的请求URL。
Response.method#
当前响应所对应的HTTP请求的方法。例如"GET", “POST”, "PUT"等。
colors#
Stability: 2 - Stable
在Auto.js有两种方式表示一个颜色。

一种是使用一个字符串"#AARRGGBB"或"#RRGGBB"，其中 AA 是Alpha通道(透明度)的值，RR 是R通道(红色)的值，GG 是G通道(绿色)的值，BB是B通道(蓝色)的值。例如"#ffffff"表示白色, "#7F000000"表示半透明的黑色。

另一种是使用一个16进制的"32位整数" 0xAARRGGBB 来表示一个颜色，例如 0xFF112233表示颜色"#112233", 0x11223344表示颜色"#11223344"。

可以通过colors.toString()把颜色整数转换为字符串，通过colors.parseColor()把颜色字符串解析为颜色整数。

colors.toString(color)#
color 整数RGB颜色值
返回
返回颜色值的字符串，格式为 “#AARRGGBB”。

colors.red(color)#
color | 颜色值
返回
返回颜色color的R通道的值，范围0~255.

colors.green(color)#
color | 颜色值
返回
返回颜色color的G通道的值，范围0~255.

colors.blue(color)#
color | 颜色值
返回
返回颜色color的B通道的值，范围0~255.

colors.alpha(color)#
color | 颜色值
返回
返回颜色color的Alpha通道的值，范围0~255.

colors.rgb(red, green, blue)#
red 颜色的R通道的值
blue 颜色的G通道的值
green 颜色的B通道的值
返回
返回这些颜色通道构成的整数颜色值。Alpha通道将是255（不透明）。

colors.argb(alpha, red, green, blue)#
alpha 颜色的Alpha通道的值
red 颜色的R通道的值
green 颜色的G通道的值
blue 颜色的B通道的值
返回
返回这些颜色通道构成的整数颜色值。

colors.parseColor(colorStr)#
colorStr 表示颜色的字符串，例如"#112233"
返回
返回颜色的整数值。

colors.isSimilar(color2, color2[, threshold, algorithm])#
color1 | 颜色值1
color1 | 颜色值2
threshold 颜色相似度临界值，默认为4。取值范围为0~255。这个值越大表示允许的相似程度越小，如果这个值为0，则两个颜色相等时该函数才会返回true。
algorithm 颜色匹配算法，默认为"diff", 包括:
“diff”: 差值匹配。与给定颜色的R、G、B差的绝对值之和小于threshold时匹配。
“rgb”: rgb欧拉距离相似度。与给定颜色color的rgb欧拉距离小于等于threshold时匹配。
“rgb+”: 加权rgb欧拉距离匹配(LAB Delta E)。
“hs”: hs欧拉距离匹配。hs为HSV空间的色调值。
返回
返回两个颜色是否相似。

colors.equals(color1, color2)#
color1 | 颜色值1
color1 | 颜色值2
返回
返回两个颜色是否相等。*注意该函数会忽略Alpha通道的值进行比较。

log(colors.equals("#112233", “#112234”));
log(colors.equals(0xFF112233, 0xFF223344));
colors.BLACK#
黑色，颜色值 #FF000000

colors.DKGRAY#
深灰色，颜色值 #FF444444

colors.GRAY#
灰色，颜色值 #FF888888

colors.LTGRAY#
亮灰色，颜色值 #FFCCCCCC

colors.WHITE#
白色，颜色值 #FFFFFFFF

colors.RED#
红色，颜色值 #FFFF0000

colors.GREEN#
绿色，颜色值 #FF00FF00

colors.BLUE#
蓝色，颜色值 #FF0000FF

colors.YELLOW#
黄色，颜色值 #FFFFFF00

colors.CYAN#
青色，颜色值 #FF00FFFF

colors.MAGENTA#
品红色，颜色值 #FFFF00FF

colors.TRANSPARENT#
透明，颜色值 #00000000

Images#
Stability: 2 - Stable
images模块提供了一些手机设备中常见的图片处理函数，包括截图、读写图片、图片剪裁、旋转、二值化、找色找图等。

该模块分为两个部分，找图找色部分和图片处理部分。

需要注意的是，image对象创建后尽量在不使用时进行回收，同时避免循环创建大量图片。因为图片是一种占用内存比较大的资源，尽管Auto.js通过各种方式（比如图片缓存机制、垃圾回收时回收图片、脚本结束时回收所有图片）尽量降低图片资源的泄漏和内存占用，但是糟糕的代码仍然可以占用大量内存。

Image对象通过调用recycle()函数来回收。例如：

// 读取图片
var img = images.read("./1.png");
//对图片进行操作
…
// 回收图片
img.recycle();
例外的是，caputerScreen()返回的图片不需要回收。

图片处理#
images.read(path)#
path 图片路径
读取在路径path的图片文件并返回一个Image对象。如果文件不存在或者文件无法解码则返回null。

images.load(url)#
url 图片URL地址
加载在地址URL的网络图片并返回一个Image对象。如果地址不存在或者图片无法解码则返回null。

images.copy(img)#
img 图片
返回
复制一张图片并返回新的副本。该函数会完全复制img对象的数据。

images.save(image, path[, format = “png”, quality = 100])#
image 图片
path 路径
format 图片格式，可选的值为:
png
jpeg/jpg
webp
quality 图片质量，为0~100的整数值
把图片image以PNG格式保存到path中。如果文件不存在会被创建；文件存在会被覆盖。

//把图片压缩为原来的一半质量并保存
var img = images.read("/sdcard/1.png");
images.save(img, “/sdcard/1.jpg”, “jpg”, 50);
app.viewFile("/sdcard/1.jpg");
images.fromBase64(base64)#
base64 图片的Base64数据
返回
解码Base64数据并返回解码后的图片Image对象。如果base64无法解码则返回null。

images.toBase64(img[, format = “png”, quality = 100])#
image 图片
format 图片格式，可选的值为:
png
jpeg/jpg
webp
quality 图片质量，为0~100的整数值
返回
把图片编码为base64数据并返回。

images.fromBytes(bytes)#
bytes <byte[]> 字节数组
解码字节数组bytes并返回解码后的图片Image对象。如果bytes无法解码则返回null。

images.toBytes(img[, format = “png”, quality = 100])#
image 图片
format 图片格式，可选的值为:
png
jpeg/jpg
webp
quality 图片质量，为0~100的整数值
返回 <byte[]>
把图片编码为字节数组并返回。

images.clip(img, x, y, w, h)#
img 图片
x 剪切区域的左上角横坐标
y 剪切区域的左上角纵坐标
w 剪切区域的宽度
h 剪切区域的高度
返回
从图片img的位置(x, y)处剪切大小为w * h的区域，并返回该剪切区域的新图片。

var src = images.read("/sdcard/1.png");
var clip = images.clip(src, 100, 100, 400, 400);
images.save(clip, “/sdcard/clip.png”);
images.resize(img, size[, interpolation])#
[v4.1.0新增]

img 图片
size 两个元素的数组[w, h]，分别表示宽度和高度；如果只有一个元素，则宽度和高度相等
interpolation 插值方法，可选，默认为"LINEAR"（线性插值），可选的值有：

NEAREST 最近邻插值
LINEAR 线性插值（默认）
AREA 区域插值
CUBIC 三次样条插值
LANCZOS4 Lanczos插值参见InterpolationFlags
返回

调整图片大小，并返回调整后的图片。例如把图片放缩为200*300：images.resize(img, [200, 300])。

参见Imgproc.resize。

images.scale(img, fx, fy[, interpolation])#
[v4.1.0新增]

img 图片
fx 宽度放缩倍数
fy 高度放缩倍数
interpolation 插值方法，可选，默认为"LINEAR"（线性插值），可选的值有：

NEAREST 最近邻插值
LINEAR 线性插值（默认）
AREA 区域插值
CUBIC 三次样条插值
LANCZOS4 Lanczos插值参见InterpolationFlags
返回

放缩图片，并返回放缩后的图片。例如把图片变成原来的一半：images.scale(img, 0.5, 0.5)。

参见Imgproc.resize。

images.rotate(img, degress[, x, y])#
[v4.1.0新增]

img 图片
degress 旋转角度。
x 旋转中心x坐标，默认为图片中点
y 旋转中心y坐标，默认为图片中点
返回
将图片逆时针旋转degress度，返回旋转后的图片对象。

例如逆时针旋转90度为images.rotate(img, 90)。

images.concat(img1, image2[, direction])#
[v4.1.0新增]

img1 图片1
img2 图片2
direction 连接方向，默认为"RIGHT"，可选的值有：
LEFT 将图片2接到图片1左边
RIGHT 将图片2接到图片1右边
TOP 将图片2接到图片1上边
BOTTOM 将图片2接到图片1下边
返回
连接两张图片，并返回连接后的图像。如果两张图片大小不一致，小的那张将适当居中。

images.grayscale(img)#
[v4.1.0新增]

img 图片
返回
灰度化图片，并返回灰度化后的图片。

image.threshold(img, threshold, maxVal[, type])#
[v4.1.0新增]

img 图片
threshold 阈值
maxVal 最大值
type 阈值化类型，默认为"BINARY"，参见ThresholdTypes, 可选的值:

BINARY
BINARY_INV
TRUNC
TOZERO
TOZERO_INV
OTSU
TRIANGLE
返回

将图片阈值化，并返回处理后的图像。可以用这个函数进行图片二值化。例如：images.threshold(img, 100, 255, “BINARY”)，这个代码将图片中大于100的值全部变成255，其余变成0，从而达到二值化的效果。如果img是一张灰度化图片，这个代码将会得到一张黑白图片。

可以参考有关博客（比如threshold函数的使用）或者OpenCV文档threshold。

images.adaptiveThreshold(img, maxValue, adaptiveMethod, thresholdType, blockSize, C)#
[v4.1.0新增]

img 图片
maxValue 最大值
adaptiveMethod 在一个邻域内计算阈值所采用的算法，可选的值有：
MEAN_C 计算出领域的平均值再减去参数C的值
GAUSSIAN_C 计算出领域的高斯均值再减去参数C的值
thresholdType 阈值化类型，可选的值有：
BINARY
BINARY_INV
blockSize 邻域块大小
C 偏移值调整量
返回
对图片进行自适应阈值化处理，并返回处理后的图像。

可以参考有关博客（比如threshold与adaptiveThreshold）或者OpenCV文档adaptiveThreshold。

images.cvtColor(img, code[, dstCn])#
[v4.1.0新增]

img 图片
code 颜色空间转换的类型，可选的值有一共有205个（参见ColorConversionCodes），这里只列出几个：
BGR2GRAY BGR转换为灰度
BGR2HSV BGR转换为HSV
dstCn 目标图像的颜色通道数量，如果不填写则根据其他参数自动决定。
返回
对图像进行颜色空间转换，并返回转换后的图像。

可以参考有关博客（比如颜色空间转换）或者OpenCV文档cvtColor。

images.inRange(img, lowerBound, upperBound)#
[v4.1.0新增]

img 图片
lowerBound | 颜色下界
upperBound | 颜色下界
返回
将图片二值化，在lowerBound~upperBound范围以外的颜色都变成0，在范围以内的颜色都变成255。

例如images.inRange(img, “#000000”, “#222222”)。

images.interval(img, color, interval)#
[v4.1.0新增]

img 图片
color | 颜色值
interval 每个通道的范围间隔
返回
将图片二值化，在color-interval ~ color+interval范围以外的颜色都变成0，在范围以内的颜色都变成255。这里对color的加减是对每个通道而言的。

例如images.interval(img, “#888888”, 16)，每个通道的颜色值均为0x88，加减16后的范围是[0x78, 0x98]，因此这个代码将把#787878~#989898的颜色变成#FFFFFF，而把这个范围以外的变成#000000。

images.blur(img, size[, anchor, type])#
[v4.1.0新增]

可以参考有关博客（比如实现图像平滑处理）或者OpenCV文档blur。

images.medianBlur(img, size)#
[v4.1.0新增]

img 图片
size 定义滤波器的大小，如[3, 3]
返回
对图像进行中值滤波，返回处理后的图像。

可以参考有关博客（比如实现图像平滑处理）或者OpenCV文档blur。

images.gaussianBlur(img, size[, sigmaX, sigmaY, type])#
[v4.1.0新增]

img 图片
size 定义滤波器的大小，如[3, 3]
sigmaX x方向的标准方差，不填写则自动计算
sigmaY y方向的标准方差，不填写则自动计算
type 推断边缘像素类型，默认为"DEFAULT"，参见images.blur
返回
对图像进行高斯模糊，返回处理后的图像。

可以参考有关博客（比如实现图像平滑处理）或者OpenCV文档GaussianBlur。

images.matToImage(mat)#
[v4.1.0新增]

mat OpenCV的Mat对象
返回
把Mat对象转换为Image对象。

找图找色#
images.requestScreenCapture([landscape])#
landscape 布尔值，表示将要执行的截屏是否为横屏。如果landscape为false, 则表示竖屏截图; true为横屏截图。
向系统申请屏幕截图权限，返回是否请求成功。

第一次使用该函数会弹出截图权限请求，建议选择“总是允许”。

这个函数只是申请截图权限，并不会真正执行截图，真正的截图函数是captureScreen()。

该函数在截图脚本中只需执行一次，而无需每次调用captureScreen()都调用一次。

如果不指定landscape值，则截图方向由当前设备屏幕方向决定，因此务必注意执行该函数时的屏幕方向。

建议在本软件界面运行该函数，在其他软件界面运行时容易出现一闪而过的黑屏现象。

示例:

//请求截图
if(!requestScreenCapture()){
toast(“请求截图失败”);
exit();
}
//连续截图10张图片(间隔1秒)并保存到存储卡目录
for(var i = 0; i < 10; i++){
captureScreen("/sdcard/screencapture" + i + “.png”);
sleep(1000);
}

该函数也可以作为全局函数使用。

images.captureScreen()#
截取当前屏幕并返回一个Image对象。

没有截图权限时执行该函数会抛出SecurityException。

该函数不会返回null，两次调用可能返回相同的Image对象。这是因为设备截图的更新需要一定的时间，短时间内（一般来说是16ms）连续调用则会返回同一张截图。

截图需要转换为Bitmap格式，从而该函数执行需要一定的时间(0~20ms)。

另外在requestScreenCapture()执行成功后需要一定时间后才有截图可用，因此如果立即调用captureScreen()，会等待一定时间后(一般为几百ms)才返回截图。

例子:

//请求横屏截图
requestScreenCapture(true);
//截图
var img = captureScreen();
//获取在点(100, 100)的颜色值
var color = images.pixel(img, 100, 100);
//显示该颜色值
toast(colors.toString(color));
该函数也可以作为全局函数使用。

images.captureScreen(path)#
path 截图保存路径
截取当前屏幕并以PNG格式保存到path中。如果文件不存在会被创建；文件存在会被覆盖。

该函数不会返回任何值。该函数也可以作为全局函数使用。

images.pixel(image, x, y)#
image 图片
x 要获取的像素的横坐标。
y 要获取的像素的纵坐标。
返回图片image在点(x, y)处的像素的ARGB值。

该值的格式为0xAARRGGBB，是一个"32位整数"(虽然JavaScript中并不区分整数类型和其他数值类型)。

坐标系以图片左上角为原点。以图片左侧边为y轴，上侧边为x轴。

images.findColor(image, color, options)#
image 图片
color | 要寻找的颜色的RGB值。如果是一个整数，则以0xRRGGBB的形式代表RGB值（A通道会被忽略）；如果是字符串，则以"#RRGGBB"代表其RGB值。
options 选项
在图片中寻找颜色color。找到时返回找到的点Point，找不到时返回null。

选项包括：

region 找色区域。是一个两个或四个元素的数组。(region[0], region[1])表示找色区域的左上角；region[2]*region[3]表示找色区域的宽高。如果只有region只有两个元素，则找色区域为(region[0], region[1])到屏幕右下角。如果不指定region选项，则找色区域为整张图片。
threshold 找色时颜色相似度的临界值，范围为0_{255（越小越相似，0为颜色相等，255为任何颜色都能匹配）。默认为4。threshold和浮点数相似度(0.0}1.0)的换算为 similarity = (255 - threshold) / 255.
该函数也可以作为全局函数使用。

一个循环找色的例子如下：

requestScreenCapture();

//循环找色，找到红色(#ff0000)时停止并报告坐标
while(true){
var img = captureScreen();
var point = findColor(img, “#ff0000”);
if(point){
toast(“找到红色，坐标为(” + point.x + ", " + point.y + “)”);
}
}

一个区域找色的例子如下：

//读取本地图片/sdcard/1.png
var img = images.read("/sdcard/1.png");
//判断图片是否加载成功
if(!img){
toast(“没有该图片”);
exit();
}
//在该图片中找色，指定找色区域为在位置(400, 500)的宽为300长为200的区域，指定找色临界值为4
var point = findColor(img, “#00ff00”, {
region: [400, 500, 300, 200],
threshold: 4
});
if(point){
toast(“找到啦:” + point);
}else{
toast(“没找到”);
}
images.findColorInRegion(img, color, x, y[, width, height, threshold])#
区域找色的简便方法。

相当于

images.findColor(img, color, {
region: [x, y, width, height],
threshold: threshold
});
该函数也可以作为全局函数使用。

images.findColorEquals(img, color[, x, y, width, height])#
img 图片
color | 要寻找的颜色
x 找色区域的左上角横坐标
y 找色区域的左上角纵坐标
width 找色区域的宽度
height 找色区域的高度
返回
在图片img指定区域中找到颜色和color完全相等的某个点，并返回该点的左边；如果没有找到，则返回null。

找色区域通过x, y, width, height指定，如果不指定找色区域，则在整张图片中寻找。

该函数也可以作为全局函数使用。

示例： (通过找QQ红点的颜色来判断是否有未读消息)

requestScreenCapture();
launchApp(“QQ”);
sleep(1200);
var p = findColorEquals(captureScreen(), “#f64d30”);
if§{
toast(“有未读消息”);
}else{
toast(“没有未读消息”);
}
images.findMultiColors(img, firstColor, colors[, options])#
img 要找色的图片
firstColor | 第一个点的颜色
colors 表示剩下的点相对于第一个点的位置和颜色的数组，数组的每个元素为[x, y, color]
options 选项，包括：
region 找色区域。是一个两个或四个元素的数组。(region[0], region[1])表示找色区域的左上角；region[2]*region[3]表示找色区域的宽高。如果只有region只有两个元素，则找色区域为(region[0], region[1])到屏幕右下角。如果不指定region选项，则找色区域为整张图片。
threshold 找色时颜色相似度的临界值，范围为0_{255（越小越相似，0为颜色相等，255为任何颜色都能匹配）。默认为4。threshold和浮点数相似度(0.0}1.0)的换算为 similarity = (255 - threshold) / 255.
多点找色，类似于按键精灵的多点找色，其过程如下：

在图片img中找到颜色firstColor的位置(x0, y0)
对于数组colors的每个元素[x, y, color]，检查图片img在位置(x + x0, y + y0)上的像素是否是颜色color，是的话返回(x0, y0)，否则继续寻找firstColor的位置，重新执行第1步
整张图片都找不到时返回null
例如，对于代码images.findMultiColors(img, “#123456”, [[10, 20, “#ffffff”], [30, 40, “#000000”]])，假设图片在(100, 200)的位置的颜色为#123456, 这时如果(110, 220)的位置的颜色为#fffff且(130, 240)的位置的颜色为#000000，则函数返回点(100, 200)。

如果要指定找色区域，则在options中指定，例如:

var p = images.findMultiColors(img, “#123456”, [[10, 20, “#ffffff”], [30, 40, “#000000”]], {
region: [0, 960, 1080, 960]
});
images.detectsColor(image, color, x, y[, threshold = 16, algorithm = “diff”])#
image 图片
color | 要检测的颜色
x 要检测的位置横坐标
y 要检测的位置纵坐标
threshold 颜色相似度临界值，默认为16。取值范围为0~255。
algorithm 颜色匹配算法，包括:

“equal”: 相等匹配，只有与给定颜色color完全相等时才匹配。
“diff”: 差值匹配。与给定颜色的R、G、B差的绝对值之和小于threshold时匹配。
“rgb”: rgb欧拉距离相似度。与给定颜色color的rgb欧拉距离小于等于threshold时匹配。

“rgb+”: 加权rgb欧拉距离匹配(LAB Delta E)。

“hs”: hs欧拉距离匹配。hs为HSV空间的色调值。
返回图片image在位置(x, y)处是否匹配到颜色color。用于检测图片中某个位置是否是特定颜色。

一个判断微博客户端的某个微博是否被点赞过的例子：

requestScreenCapture();
//找到点赞控件
var like = id(“ly_feed_like_icon”).findOne();
//获取该控件中点坐标
var x = like.bounds().centerX();
var y = like.bounds().centerY();
//截图
var img = captureScreen();
//判断在该坐标的颜色是否为橙红色
if(images.detectsColor(img, “#fed9a8”, x, y)){
//是的话则已经是点赞过的了，不做任何动作
}else{
//否则点击点赞按钮
like.click();
}
images.findImage(img, template[, options])#
img 大图片
template 小图片（模板）
options 找图选项
找图。在大图片img中查找小图片template的位置（模块匹配），找到时返回位置坐标(Point)，找不到时返回null。

选项包括：

threshold 图片相似度。取值范围为0~1的浮点数。默认值为0.9。
region 找图区域。参见findColor函数关于region的说明。
level 一般而言不必修改此参数。不加此参数时该参数会根据图片大小自动调整。找图算法是采用图像金字塔进行的, level参数表示金字塔的层次, level越大可能带来越高的找图效率，但也可能造成找图失败（图片因过度缩小而无法分辨）或返回错误位置。因此，除非您清楚该参数的意义并需要进行性能调优，否则不需要用到该参数。
该函数也可以作为全局函数使用。

一个最简单的找图例子如下：

var img = images.read("/sdcard/大图.png");
var templ = images.read("/sdcard/小图.png");
var p = findImage(img, templ);
if§{
toast(“找到啦:” + p);
}else{
toast(“没找到”);
}
稍微复杂点的区域找图例子如下：

auto();
requestScreenCapture();
var wx = images.read("/sdcard/微信图标.png");
//返回桌面
home();
//截图并找图
var p = findImage(captureScreen(), wx, {
region: [0, 50],
threshold: 0.8
});
if§{
toast("在桌面找到了微信图标啦: " + p);
}else{
toast(“在桌面没有找到微信图标”);
}
images.findImageInRegion(img, template, x, y[, width, height, threshold])#
区域找图的简便方法。相当于：

images.findImage(img, template, {
region: [x, y, width, height],
threshold: threshold
})
该函数也可以作为全局函数使用。

images.matchTemplate(img, template, options)#
[v4.1.0新增]

img 大图片
template 小图片（模板）
options 找图选项：
threshold 图片相似度。取值范围为0~1的浮点数。默认值为0.9。
region 找图区域。参见findColor函数关于region的说明。
max 找图结果最大数量，默认为5
level 一般而言不必修改此参数。不加此参数时该参数会根据图片大小自动调整。找图算法是采用图像金字塔进行的, level参数表示金字塔的层次, level越大可能带来越高的找图效率，但也可能造成找图失败（图片因过度缩小而无法分辨）或返回错误位置。因此，除非您清楚该参数的意义并需要进行性能调优，否则不需要用到该参数。
返回
在大图片中搜索小图片，并返回搜索结果MatchingResult。该函数可以用于找图时找出多个位置，可以通过max参数控制最大的结果数量。也可以对匹配结果进行排序、求最值等操作。

MatchingResult#
[v4.1.0新增]

matches#
匹配结果的数组。
数组的元素是一个Match对象：

point 匹配位置
similarity 相似度
例如:

var result = images.matchTemplate(img, template, {
max: 100
});
result.matches.forEach(match => {
log("point = " + match.point + ", similarity = " + match.similarity);
});
points#
匹配位置的数组。
first()#
返回
第一个匹配结果。如果没有任何匹配，则返回null。

last()#
返回
最后一个匹配结果。如果没有任何匹配，则返回null。

leftmost()#
返回
位于大图片最左边的匹配结果。如果没有任何匹配，则返回null。

topmost()#
返回
位于大图片最上边的匹配结果。如果没有任何匹配，则返回null。

rightmost()#
返回
位于大图片最右边的匹配结果。如果没有任何匹配，则返回null。

bottommost()#
返回
位于大图片最下边的匹配结果。如果没有任何匹配，则返回null。

best()#
返回
相似度最高的匹配结果。如果没有任何匹配，则返回null。

worst()#
返回
相似度最低的匹配结果。如果没有任何匹配，则返回null。

sortBy(cmp)#
cmp | 比较函数，或者是一个字符串表示排序方向。例如"left"表示将匹配结果按匹配位置从左往右排序、"top"表示将匹配结果按匹配位置从上往下排序，"left-top"表示将匹配结果按匹配位置从左往右、从上往下排序。方向包括left（左）, top （上）, right （右）, bottom（下）。

对匹配结果进行排序，并返回排序后的结果。

var result = images.matchTemplate(img, template, {
max: 100
});
log(result.sortBy(“top-right”));
Image#
表示一张图片，可以是截图的图片，或者本地读取的图片，或者从网络获取的图片。

Image.getWidth()#
返回以像素为单位图片宽度。

Image.getHeight()#
返回以像素为单位的图片高度。

Image.saveTo(path)#
path 路径
把图片保存到路径path。（如果文件存在则覆盖）

Image.pixel(x, y)#
x 横坐标
y 纵坐标
返回图片image在点(x, y)处的像素的ARGB值。

该值的格式为0xAARRGGBB，是一个"32位整数"(虽然JavaScript中并不区分整数类型和其他数值类型)。

坐标系以图片左上角为原点。以图片左侧边为y轴，上侧边为x轴。

Point#
findColor, findImage返回的对象。表示一个点（坐标）。

Point.x#
横坐标。

Point.y#
纵坐标。

Keys#
按键模拟部分提供了一些模拟物理按键的全局函数，包括Home、音量键、照相键等，有的函数依赖于无障碍服务，有的函数依赖于root权限。

一般来说，以大写字母开头的函数都依赖于root权限。执行此类函数时，如果没有root权限，则函数执行后没有效果，并会在控制台输出一个警告。

back()#
返回
模拟按下返回键。返回是否执行成功。此函数依赖于无障碍服务。

home()#
返回
模拟按下Home键。返回是否执行成功。此函数依赖于无障碍服务。

powerDialog()#
返回
弹出电源键菜单。返回是否执行成功。此函数依赖于无障碍服务。

notifications()#
返回
拉出通知栏。返回是否执行成功。此函数依赖于无障碍服务。

quickSettings()#
返回
显示快速设置(下拉通知栏到底)。返回是否执行成功。此函数依赖于无障碍服务。

recents()#
返回
显示最近任务。返回是否执行成功。此函数依赖于无障碍服务。

splitScreen()#
返回
分屏。返回是否执行成功。此函数依赖于无障碍服务, 并且需要系统自身功能的支持。

Home()#
模拟按下Home键。此函数依赖于root权限。

Back()#
模拟按下返回键。此函数依赖于root权限。

Power()#
模拟按下电源键。此函数依赖于root权限。

Menu()#
模拟按下菜单键。此函数依赖于root权限。

VolumeUp()#
按下音量上键。此函数依赖于root权限。

VolumeDown()#
按键音量上键。此函数依赖于root权限。

Camera()#
模拟按下照相键。

Up()#
模拟按下物理按键上。此函数依赖于root权限。

Down()#
模拟按下物理按键下。此函数依赖于root权限。

Left()#
模拟按下物理按键左。此函数依赖于root权限。

Right()#
模拟按下物理按键右。此函数依赖于root权限。

OK()#
模拟按下物理按键确定。此函数依赖于root权限。

Text(text)#
text 要输入的文字，只能为英文或英文符号输入文字text。例如Text(“aaa”);
KeyCode(code)#
code | 要按下的按键的数字代码或名称。参见下表。模拟物理按键。例如KeyCode(29)和KeyCode(“KEYCODE_A”)是按下A键。
附录: KeyCode对照表#
KeyCode KeyEvent Value

KEYCODE_MENU 1
KEYCODE_SOFT_RIGHT 2
KEYCODE_HOME 3
KEYCODE_BACK 4
KEYCODE_CALL 5
KEYCODE_ENDCALL 6
KEYCODE_0 7
KEYCODE_1 8
KEYCODE_2 9
KEYCODE_3 10
KEYCODE_4 11
KEYCODE_5 12
KEYCODE_6 13
KEYCODE_7 14
KEYCODE_8 15
KEYCODE_9 16
KEYCODE_STAR 17
KEYCODE_POUND 18
KEYCODE_DPAD_UP 19
KEYCODE_DPAD_DOWN 20
KEYCODE_DPAD_LEFT 21
KEYCODE_DPAD_RIGHT 22
KEYCODE_DPAD_CENTER 23
KEYCODE_VOLUME_UP 24
KEYCODE_VOLUME_DOWN 25
KEYCODE_POWER 26
KEYCODE_CAMERA 27
KEYCODE_CLEAR 28
KEYCODE_A 29
KEYCODE_B 30
KEYCODE_C 31
KEYCODE_D 32
KEYCODE_E 33
KEYCODE_F 34
KEYCODE_G 35
KEYCODE_H 36
KEYCODE_I 37
KEYCODE_J 38
KEYCODE_K 39
KEYCODE_L 40
KEYCODE_M 41
KEYCODE_N 42
KEYCODE_O 43
KEYCODE_P 44
KEYCODE_Q 45
KEYCODE_R 46
KEYCODE_S 47
KEYCODE_T 48
KEYCODE_U 49
KEYCODE_V 50
KEYCODE_W 51
KEYCODE_X 52
KEYCODE_Y 53
KEYCODE_Z 54
KEYCODE_COMMA 55
KEYCODE_PERIOD 56
KEYCODE_ALT_LEFT 57
KEYCODE_ALT_RIGHT 58
KEYCODE_SHIFT_LEFT 59
KEYCODE_SHIFT_RIGHT 60
KEYCODE_TAB 61
KEYCODE_SPACE 62
KEYCODE_SYM 63
KEYCODE_EXPLORER 64
KEYCODE_ENVELOPE 65
KEYCODE_ENTER 66
KEYCODE_DEL 67
KEYCODE_GRAVE 68
KEYCODE_MINUS 69
KEYCODE_EQUALS 70
KEYCODE_LEFT_BRACKET 71
KEYCODE_RIGHT_BRACKET 72
KEYCODE_BACKSLASH 73
KEYCODE_SEMICOLON 74
KEYCODE_APOSTROPHE 75
KEYCODE_SLASH 76
KEYCODE_AT 77
KEYCODE_NUM 78
KEYCODE_HEADSETHOOK 79
KEYCODE_FOCUS 80
KEYCODE_PLUS 81
KEYCODE_MENU 82
KEYCODE_NOTIFICATION 83
KEYCODE_SEARCH 84
TAG_LAST_ KEYCODE 85
Media#
Stability: 2 - Stable
media模块提供多媒体编程的支持。目前仅支持音乐播放和媒体文件扫描。后续会结合UI加入视频播放等功能。

需要注意是，使用该模块播放音乐时是在后台异步播放的，在脚本结束后会自动结束播放，因此可能需要插入诸如sleep()的语句来使脚本保持运行。例如：

//播放音乐
media.playMusic("/sdcard/1.mp3");
//让音乐播放完
sleep(media.getMusicDuration());
media.scanFile(path)#
path 媒体文件路径
扫描路径path的媒体文件，将它加入媒体库中；或者如果该文件以及被删除，则通知媒体库移除该文件。

媒体库包括相册、音乐库等，因此该函数可以用于把某个图片文件加入相册。

//请求截图
requestScreenCapture(false);
//截图
var im = captureScreen();
var path = “/sdcard/screenshot.png”;
//保存图片
im.saveTo(path);
//把图片加入相册
media.scanFile(path);
media.playMusic(path[, volume, looping])#
path 音乐文件路径
volume 播放音量，为0~1的浮点数，默认为1
looping 是否循环播放，如果looping为true则循环播放，默认为false
播放音乐文件path。该函数不会显示任何音乐播放界面。如果文件不存在或者文件不是受支持的音乐格式，则抛出UncheckedIOException异常。

//播放音乐
media.playMusic("/sdcard/1.mp3");
//让音乐播放完
sleep(media.getMusicDuration());
如果要循环播放音乐，则使用looping参数：

//传递第三个参数为true以循环播放音乐 media.playMusic("/sdcard/1.mp3", 1, true); //等待三次播放的时间 sleep(media.getMusicDuration() * 3);

如果要使用音乐播放器播放音乐，调用app.viewFile(path)函数。

media.musicSeekTo(msec)#
msec 毫秒数，表示音乐进度
把当前播放进度调整到时间msec的位置。如果当前没有在播放音乐，则调用函数没有任何效果。

例如，要把音乐调到1分钟的位置，为media.musicSeekTo(60 * 1000)。

//播放音乐
media.playMusic("/sdcard/1.mp3");
//调整到30秒的位置
media.musicSeekTo(30 * 1000);
//等待音乐播放完成
sleep(media.getMusicDuration() - 30 * 1000);
media.pauseMusic()#
暂停音乐播放。如果当前没有在播放音乐，则调用函数没有任何效果。

media.resumeMusic()#
继续音乐播放。如果当前没有播放过音乐，则调用该函数没有任何效果。

media.stopMusic()#
停止音乐播放。如果当前没有在播放音乐，则调用函数没有任何效果。

media.isMusicPlaying()#
返回
返回当前是否正在播放音乐。

media.getMusicDuration()#
返回
返回当前音乐的时长。单位毫秒。

media.getMusicCurrentPosition()#
返回
返回当前音乐的播放进度(已经播放的时间)，单位毫秒。
module (模块)#
Stability: 2 - Stable
Auto.js 有一个简单的模块加载系统。在 Auto.js 中，文件和模块是一一对应的（每个文件被视为一个独立的模块）。

例子，假设有一个名为 foo.js 的文件：

var circle = require(‘circle.js’);
console.log(“半径为 4 的圆的面积是 %d”, circle.area(4));
在第一行中，foo.js 加载了同一目录下的 circle.js 模块。

circle.js 文件的内容为：

const PI = Math.PI;

var circle = {};

circle.area = function ® {
return PI * r * r;
};

circle.circumference = ® => 2 * PI * r;

module.exports = circle;
circle.js 模块导出了 area() 和 circumference() 两个函数。通过在特殊的 exports 对象上指定额外的属性，函数和对象可以被添加到模块的根部。

模块内的本地变量是私有的。在这个例子中，变量 PI 是 circle.js 私有的，不会影响到加载他的脚本的变量环境。

module.exports属性可以被赋予一个新的值（例如函数或对象）。

如下，bar.js 会用到 square 模块，square 导出一个构造函数：

const square = require(‘square.js’);
const mySquare = square(2);
console.log(“正方形的面积是 %d”, mySquare.area());
square 模块定义在 square.js 中：

// 赋值给 exports 不会修改模块，必须使用 module.exports
module.exports = function(width) {
return {
area: () => width ** 2
};
};
基于控件的操作#
基于控件的操作指的是选择屏幕上的控件，获取其信息或对其进行操作。对于一般软件而言，基于控件的操作对不同机型有很好的兼容性；但是对于游戏而言，由于游戏界面并不是由控件构成，无法采用本章节的方法，也无法使用本章节的函数。有关游戏脚本的编写，请参考《基于坐标的操作》。

基于控件的操作依赖于无障碍服务，因此最好在脚本开头使用auto()函数来确保无障碍服务已经启用。如果运行到某个需要权限的语句无障碍服务并没启动，则会抛出异常并跳转到无障碍服务界面。这样的用户体验并不好，因为需要重新运行脚本，后续会加入等待无障碍服务启动并让脚本继续运行的函数。

您也可以在脚本开头使用"auto";表示这个脚本需要无障碍服务，但是不推荐这种做法，因为这个标记必须在脚本的最开头(前面不能有注释或其他语句、空格等)，我们推荐使用auto()函数来确保无障碍服务已启用。

auto([mode])#
mode 模式
检查无障碍服务是否已经启用，如果没有启用则抛出异常并跳转到无障碍服务启用界面；同时设置无障碍模式为mode。mode的可选值为：

fast 快速模式。该模式下会启用控件缓存，从而选择器获取屏幕控件更快。对于需要快速的控件操作的脚本可以使用该模式，一般脚本则没有必要使用该函数。
normal 正常模式，默认。
如果不加mode参数，则为正常模式。

建议使用auto.waitFor()和auto.setMode()代替该函数，因为auto()函数如果无障碍服务未启动会停止脚本；而auto.waitFor()则会在在无障碍服务启动后继续运行。

示例：

auto(“fast”);
示例2：

auto();
auto.waitFor()#
检查无障碍服务是否已经启用，如果没有启用则跳转到无障碍服务启用界面，并等待无障碍服务启动；当无障碍服务启动后脚本会继续运行。

因为该函数是阻塞的，因此除非是有协程特性，否则不能在ui模式下运行该函数，建议在ui模式下使用auto()函数。

auto.setMode(mode)#
mode 模式
设置无障碍模式为mode。mode的可选值为：

fast 快速模式。该模式下会启用控件缓存，从而选择器获取屏幕控件更快。对于需要快速的控件查看和操作的脚本可以使用该模式，一般脚本则没有必要使用该函数。
normal 正常模式，默认。
auto.setFlags(flags)#
[v4.1.0新增]

flags | 一些标志，来启用和禁用某些特性，包括：
findOnUiThread 使用该特性后，选择器搜索时会在主进程进行。该特性用于解决线程安全问题导致的次生问题，不过目前貌似已知问题并不是线程安全问题。
useUsageStats 使用该特性后，将会以"使用情况统计"服务的结果来检测当前正在运行的应用包名（需要授予"查看使用情况统计"权限)。如果觉得currentPackage()返回的结果不太准确，可以尝试该特性。
useShell 使用该特性后，将使用shell命令获取当前正在运行的应用的包名、活动名称，但是需要root权限。
启用有关automator的一些特性。例如：

auto.setFlags([“findOnUiThread”, “useShell”]);
auto.serivce#
[v4.1.0新增]

AccessibilityService
获取无障碍服务。如果无障碍服务没有启动，则返回null。

参见AccessibilityService。

auto.windows#
[v4.1.0新增]

当前所有窗口(AccessibilityWindowInfo)的数组，可能包括状态栏、输入法、当前应用窗口，弹出窗口、悬浮窗、分屏应用窗口等。可以分别获取每个窗口的布局信息。

该函数需要Android 5.0以上才能运行。

auto.root#
[v4.1.0新增]

当前窗口的布局根元素。如果无障碍服务未启动或者WindowFilter均返回false，则会返回null。

如果不设置windowFilter，则当前窗口即为活跃的窗口（获取到焦点、正在触摸的窗口）；如果设置了windowFilter，则获取的是过滤的窗口中的第一个窗口。

如果系统是Android5.0以下，则始终返回当前活跃的窗口的布局根元素。

auto.rootInActiveWindow#
[v4.1.0新增]

当前活跃的窗口（获取到焦点、正在触摸的窗口）的布局根元素。如果无障碍服务未启动则为null。

auto.setWindowFilter(filter)#
[v4.1.0新增]

filter 参数为窗口(AccessibilityWindowInfo)，返回值为Boolean的函数。
设置窗口过滤器。这个过滤器可以决定哪些窗口是目标窗口，并影响选择器的搜索。例如，如果想要选择器在所有窗口（包括状态栏、输入法等）中搜索，只需要使用以下代码：

auto.setWindowFilter(function(window){
//不管是如何窗口，都返回true，表示在该窗口中搜索
return true;
});
又例如，当前使用了分屏功能，屏幕上有Auto.js和QQ两个应用，但我们只想选择器对QQ界面进行搜索，则：

auto.setWindowFilter(function(window){
// 对于应用窗口，他的title属性就是应用的名称，因此可以通过title属性来判断一个应用
return window.title == “QQ”;
});
选择器默认是在当前活跃的窗口中搜索，不会搜索诸如悬浮窗、状态栏之类的，使用WindowFilter则可以控制搜索的窗口。

需要注意的是，如果WindowFilter返回的结果均为false，则选择器的搜索结果将为空。

另外setWindowFilter函数也会影响auto.windowRoots的结果。

该函数需要Android 5.0以上才有效。

auto.windowRoots#
[v4.1.0新增]

返回当前被WindowFilter过滤的窗口的布局根元素组成的数组。

如果系统是Android5.0以下，则始终返回当前活跃的窗口的布局根元素的数组。

SimpleActionAutomator#
Stability: 2 - Stable
SimpleActionAutomator提供了一些模拟简单操作的函数，例如点击文字、模拟按键等。这些函数可以直接作为全局函数使用。

click(text[, i])#
text 要点击的文本
i 如果相同的文本在屏幕中出现多次，则i表示要点击第几个文本, i从0开始计算
返回是否点击成功。当屏幕中并未包含该文本，或者该文本所在区域不能点击时返回false，否则返回true。

该函数可以点击大部分包含文字的按钮。例如微信主界面下方的"微信", “联系人”, “发现”, "我"的按钮。
通常与while同时使用以便点击按钮直至成功。例如:

while(!click(“扫一扫”));
当不指定参数i时则会尝试点击屏幕上出现的所有文字text并返回是否全部点击成功。

i是从0开始计算的, 也就是, click(“啦啦啦”, 0)表示点击屏幕上第一个"啦啦啦", click(“啦啦啦”, 1)表示点击屏幕上第二个"啦啦啦"。

文本所在区域指的是，从文本处向其父视图寻找，直至发现一个可点击的部件为止。

click(left, top, bottom, right)#
left 要点击的长方形区域左边与屏幕左边的像素距离
top 要点击的长方形区域上边与屏幕上边的像素距离
bottom 要点击的长方形区域下边与屏幕下边的像素距离
right 要点击的长方形区域右边与屏幕右边的像素距离
注意，该函数一般只用于录制的脚本中使用，在自己写的代码中使用该函数一般不要使用该函数。

点击在指定区域的控件。当屏幕中并未包含与该区域严格匹配的区域，或者该区域不能点击时返回false，否则返回true。

有些按钮或者部件是图标而不是文字（例如发送朋友圈的照相机图标以及QQ下方的消息、联系人、动态图标），这时不能通过click(text, i)来点击，可以通过描述图标所在的区域来点击。left, bottom, top, right描述的就是点击的区域。

至于要定位点击的区域，可以在悬浮窗使用布局分析工具查看控件的bounds属性。

通过无障碍服务录制脚本会生成该语句。

longClick(text[, i]))#
text 要长按的文本
i 如果相同的文本在屏幕中出现多次，则i表示要长按第几个文本, i从0开始计算
返回是否点击成功。当屏幕中并未包含该文本，或者该文本所在区域不能点击时返回false，否则返回true。

当不指定参数i时则会尝试点击屏幕上出现的所有文字text并返回是否全部长按成功。

scrollUp([i])#
i 要滑动的控件序号
找到第i+1个可滑动控件上滑或左滑。返回是否操作成功。屏幕上没有可滑动的控件时返回false。

另外不加参数时scrollUp()会寻找面积最大的可滑动的控件上滑或左滑，例如微信消息列表等。

参数为一个整数i时会找到第i + 1个可滑动控件滑动。例如scrollUp(0)为滑动第一个可滑动控件。

scrollDown([i])#
i 要滑动的控件序号
找到第i+1个可滑动控件下滑或右滑。返回是否操作成功。屏幕上没有可滑动的控件时返回false。

另外不加参数时scrollUp()会寻找面积最大的可滑动的控件下滑或右滑。

参数为一个整数i时会找到第i + 1个可滑动控件滑动。例如scrollUp(0)为滑动第一个可滑动控件。

setText([i, ]text)#
i 表示要输入的为第i + 1个输入框
text 要输入的文本
返回是否输入成功。当找不到对应的文本框时返回false。

不加参数i则会把所有输入框的文本都置为text。例如setText(“测试”)。

这里的输入文本的意思是，把输入框的文本置为text，而不是在原来的文本上追加。

input([i, ]text)#
i 表示要输入的为第i + 1个输入框
text 要输入的文本
返回是否输入成功。当找不到对应的文本框时返回false。

不加参数i则会把所有输入框的文本追加内容text。例如input(“测试”)。

UiSelector#
UiSelector即选择器，用于通过各种条件选取屏幕上的控件，再对这些控件进行点击、长按等动作。这里需要先简单介绍一下控件和界面的相关知识。

一般软件的界面是由一个个控件构成的，例如图片部分是一个图片控件(ImageView)，文字部分是一个文字控件(TextView)；同时，通过各种布局来决定各个控件的位置，例如，线性布局(LinearLayout)里面的控件都是按水平或垂直一次叠放的，列表布局(AbsListView)则是以列表的形式显示控件。

控件有各种属性，包括文本(text), 描述(desc), 类名(className), id等等。我们通常用一个控件的属性来找到这个控件，例如，想要点击QQ聊天窗口的"发送"按钮，我们就可以通过他的文本属性为"发送"来找到这个控件并点击他，具体代码为:

var sendButton = text(“发送”).findOne();
sendButton.click();
在这个例子中, text(“发送”)表示一个条件(文本属性为"发送")，findOne()表示基于这个条件找到一个符合条件的控件，从而我们可以得到发送按钮sendButton，再执行sendButton.click()即可点击"发送"按钮。

用文本属性来定位按钮控件、文本控件通常十分有效。但是，如果一个控件是图片控件，比如Auto.js主界面右上角的搜索图标，他没有文本属性，这时需要其他属性来定位他。我们如何查看他有什么属性呢？首先打开悬浮窗和无障碍服务，点击蓝色的图标(布局分析), 可以看到以下界面：

之后我们点击搜索图标，可以看到他有以下属性：

我们注意到这个图标的desc(描述)属性为"搜索"，那么我们就可以通过desc属性来定位这个控件，得到点击搜索图标的代码为:

desc(“搜索”).findOne().click();
可能心细的你可能注意到了，这个控件还有很多其他的属性，例如checked, className, clickable等等，为什么不用这些属性来定位搜索图标呢？答案是，其他控件也有这些值相同的属性、尝试一下你就可以发现很多其他控件的checked属性和搜索控件一样都是false，如果我们用checked(false)作为条件，将会找到很多控件，而无法确定哪一个是搜索图标。因此，要找到我们想要的那个控件，选择器的条件通常需要是可唯一确定控件的。我们通常用一个独一无二的属性来定位一个控件，例如这个例子中就没有其他控件的desc(描述)属性为"搜索"。

另外，对于这个搜索图标而言，id属性也是唯一的，我们也可以用id(“action_search”).findOne().click()来点击这个控件。如果一个控件有id属性，那么这个属性很可能是唯一的，除了以下几种情况：

QQ的控件的id属性很多都是"name"，也就是在QQ界面难以通过id来定位一个控件
列表中的控件，比如QQ联系人列表，微信联系人列表等
尽管id属性很方便，但也不总是最方便的，例如对于微信和网易云音乐，每次更新他的控件id都会变化，导致了相同代码对于不同版本的微信、网易云音乐并不兼容。

除了这些属性外，主要还有以下几种属性：

className 类名。类名表示一个控件的类型，例如文本控件为"android.widget.TextView", 图片控件为"android.widget.ImageView"等。
packageName 包名。包名表示控件所在的应用包名，例如QQ界面的控件的包名为"com.tencent.mobileqq"。
bounds 控件在屏幕上的范围。
drawingOrder 控件在父控件的绘制顺序。
indexInParent 控件在父控件的位置。
clickable 控件是否可点击。
longClickable 控件是否可长按。
checkable 控件是否可勾选。
checked 控件是否可已勾选。
scrollable 控件是否可滑动。
selected 控件是否已选择。
editable 控件是否可编辑。
visibleToUser 控件是否可见。
enabled 控件是否已启用。
depth 控件的布局深度。
有时候只靠一个属性并不能唯一确定一个控件，这时需要通过属性的组合来完成定位，例如className(“ImageView”).depth(10).findOne().click()，通过链式调用来组合条件。

通常用这些技巧便可以解决大部分问题，即使解决不了问题，也可以通过布局分析的"生成代码"功能来尝试生成一些选择器代码。接下来的问题便是对选取的控件进行操作，包括：

click() 点击。点击一个控件，前提是这个控件的clickable属性为true
longClick() 长按。长按一个控件，前提是这个控件的longClickable属性为true
setText() 设置文本，用于编辑框控件设置文本。
scrollForward(), scrollBackward() 滑动。滑动一个控件(列表等), 前提是这个控件的scrollable属性为true
exits() 判断控件是否存在
waitFor() 等待控件出现
这些操作包含了绝大部分控件操作。根据这些我们可以很容易写出一个"刷屏"脚本(代码仅为示例，请不要在别人的群里测试，否则容易被踢):

while(true){
className(“EditText”).findOne().setText(“刷屏…”);
text(“发送”).findOne().clicK();
}
上面这段代码也可以写成：

while(true){
className(“EditText”).setText(“刷屏…”);
text(“发送”).clicK();
}
如果不加findOne()而直接进行操作，则选择器会找出所有符合条件的控件并操作。

另外一个比较常用的操作的滑动。滑动操作的第一步是找到需要滑动的控件，例如要滑动QQ消息列表则在悬浮窗布局层次分析中找到AbsListView，这个控件就是消息列表控件，如下图：

长按可查看控件信息，注意到其scrollable属性为true，并找出其id为"recent_chat_list"，从而下滑QQ消息列表的代码为：

id(“recent_chat_list”).className(“AbsListView”).findOne().scrollForward();
scrollForward()为向前滑，包括下滑和右滑。

选择器的入门教程暂且要这里，更多信息可以查看下面的文档和选择器进阶。

selector()#
返回
创建一个新的选择器。但一般情况不需要使用该函数，因为可以直接用相应条件的语句创建选择器。

由于历史遗留原因，本不应该这样设计(不应该让id(), text()等作为全局函数，而是应该用By.id(), By.text())，但为了后向兼容性只能保留这个设计。

这样的API设计会污染全局变量，后续可能会支持"去掉这些全局函数而使用By.***"的选项。

UiSelector.algorithm(algorithm)#
[v4.1.0新增]

algorithm 搜索算法，可选的值有：
DFS 深度优先算法，选择器的默认算法
BFS 广度优先算法
指定选择器的搜索算法。例如：

log(selector().text(“文本”).algorithm(“BFS”).find());
广度优先在控件所在层次较低时，或者布局的层次不多时，通常能更快找到控件。

UiSelector.text(str)#
str 控件文本
返回返回选择器自身以便链式调用
为当前选择器附加控件"text等于字符串str"的筛选条件。

控件的text(文本)属性是文本控件上的显示的文字，例如微信左上角的"微信"文本。

UiSelector.textContains(str)#
str 要包含的字符串
为当前选择器附加控件"text需要包含字符串str"的筛选条件。

这是一个比较有用的条件，例如QQ动态页和微博发现页上方的"大家都在搜…"的控件可以用textContains(“大家都在搜”).findOne()来获取。

UiSelector.textStartsWith(prefix)#
prefix 前缀
为当前选择器附加控件"text需要以prefix开头"的筛选条件。

这也是一个比较有用的条件，例如要找出Auto.js脚本列表中名称以"QQ"开头的脚本的代码为textStartsWith(“QQ”).find()。

UiSelector.textEndsWith(suffix)#
suffix 后缀
为当前选择器附加控件"text需要以suffix结束"的筛选条件。

UiSelector.textMatches(reg)#
reg | 要满足的正则表达式。
为当前选择器附加控件"text需要满足正则表达式reg"的条件。

有关正则表达式，可以查看正则表达式 - 菜鸟教程。

需要注意的是，如果正则表达式是字符串，则需要使用\来表达(也即Java正则表达式的形式)，例如textMatches("\d+")匹配多位数字；但如果使用JavaScript语法的正则表达式则不需要，例如textMatches(/\d+/)。但如果使用字符串的正则表达式则该字符串不能以"/“同时以”/“结束，也即不能写诸如textMatches(”/\d+/")的表达式，否则会被开头的"/“和结尾的”/"会被忽略。

UiSelector.desc(str)#
str 控件文本
返回返回选择器自身以便链式调用
为当前选择器附加控件"desc等于字符串str"的筛选条件。

控件的desc(描述，全称为Content-Description)属性是对一个控件的描述，例如网易云音乐右上角的放大镜图标的描述为搜索。要查看一个控件的描述，同样地可以借助悬浮窗查看。

desc属性同样是定位控件的利器。

UiSelector.descContains(str)#
str 要包含的字符串
为当前选择器附加控件"desc需要包含字符串str"的筛选条件。

UiSelector.descStartsWith(prefix)#
prefix 前缀
为当前选择器附加控件"desc需要以prefix开头"的筛选条件。

UiSelector.descEndsWith(suffix)#
suffix 后缀
为当前选择器附加控件"desc需要以suffix结束"的筛选条件。

UiSelector.descMatches(reg)#
reg | 要满足的正则表达式。
为当前选择器附加控件"desc需要满足正则表达式reg"的条件。

有关正则表达式，可以查看正则表达式 - 菜鸟教程。

UiSelector.id(resId)#
resId 控件的id，以"包名:id/“开头，例如"com.tencent.mm:id/send_btn”。也可以不指定包名，这时会以当前正在运行的应用的包名来补全id。例如id(“send_btn”),在QQ界面想当于id(“com.tencent.mobileqq:id/send_btn”)。
为当前选择器附加"id等于resId"的筛选条件。

控件的id属性通常是可以用来确定控件的唯一标识，如果一个控件有id，那么使用id来找到他是最好的方法。要查看屏幕上的控件的id，可以开启悬浮窗并使用界面工具，点击相应控件即可查看。若查看到的控件id为null, 表示该控件没有id。另外，在列表中会出现多个控件的id相同的情况。例如微信的联系人列表，每个头像的id都是一样的。此时不能用id来唯一确定控件。

在QQ界面经常会出现多个id为"name"的控件，在微信上则每个版本的id都会变化。对于这些软件而言比较难用id定位控件。

UiSelector.idContains(str)#
str id要包含的字符串
为当前选择器附加控件"id包含字符串str"的筛选条件。比较少用。

UiSelector.idStartsWith(prefix)#
prefix id前缀
为当前选择器附加"id需要以prefix开头"的筛选条件。比较少用。

UiSelector.idEndsWith(suffix)#
suffix id后缀
为当前选择器附加"id需要以suffix结束"的筛选条件。比较少用。

UiSelector.idMatches(reg)#
reg | id要满足的正则表达式
附加id需要满足正则表达式。

idMatches("[a-zA-Z]+")
UiSelector.className(str)#
str 控件文本
返回返回选择器自身以便链式调用
为当前选择器附加控件"className等于字符串str"的筛选条件。

控件的className(类名)表示一个控件的类别，例如文本控件的类名为android.widget.TextView。

如果一个控件的类名以"android.widget."开头，则可以省略这部分，例如文本控件可以直接用className(“TextView”)的选择器。

常见控件的类名如下：

android.widget.TextView 文本控件
android.widget.ImageView 图片控件
android.widget.Button 按钮控件
android.widget.EditText 输入框控件
android.widget.AbsListView 列表控件
android.widget.LinearLayout 线性布局
android.widget.FrameLayout 帧布局
android.widget.RelativeLayout 相对布局
android.widget.RelativeLayout 相对布局
android.support.v7.widget.RecyclerView 通常也是列表控件
UiSelector.classNameContains(str)#
str 要包含的字符串
为当前选择器附加控件"className需要包含字符串str"的筛选条件。

UiSelector.classNameStartsWith(prefix)#
prefix 前缀
为当前选择器附加控件"className需要以prefix开头"的筛选条件。

UiSelector.classNameEndsWith(suffix)#
suffix 后缀
为当前选择器附加控件"className需要以suffix结束"的筛选条件。

UiSelector.classNameMatches(reg)#
reg | 要满足的正则表达式。
为当前选择器附加控件"className需要满足正则表达式reg"的条件。

有关正则表达式，可以查看正则表达式 - 菜鸟教程。

UiSelector.packageName(str)#
str 控件文本
返回返回选择器自身以便链式调用
为当前选择器附加控件"packageName等于字符串str"的筛选条件。

控件的packageName表示控件所属界面的应用包名。例如微信的包名为"com.tencent.mm", 那么微信界面的控件的packageName为"com.tencent.mm"。

要查看一个应用的包名，可以用函数app.getPackageName()获取，例如toast(app.getPackageName(“微信”))。

UiSelector.packageNameContains(str)#
str 要包含的字符串
为当前选择器附加控件"packageName需要包含字符串str"的筛选条件。

UiSelector.packageNameStartsWith(prefix)#
prefix 前缀
为当前选择器附加控件"packageName需要以prefix开头"的筛选条件。

UiSelector.packageNameEndsWith(suffix)#
suffix 后缀
为当前选择器附加控件"packageName需要以suffix结束"的筛选条件。

UiSelector.packageNameMatches(reg)#
reg | 要满足的正则表达式。
为当前选择器附加控件"packageName需要满足正则表达式reg"的条件。

有关正则表达式，可以查看正则表达式 - 菜鸟教程。

UiSelector.bounds(left, top, right, buttom)#
left 控件左边缘与屏幕左边的距离
top 控件上边缘与屏幕上边的距离
right 控件右边缘与屏幕左边的距离
bottom 控件下边缘与屏幕上边的距离
一个控件的bounds属性为这个控件在屏幕上显示的范围。我们可以用这个范围来定位这个控件。尽管用这个方法定位控件对于静态页面十分准确，却无法兼容不同分辨率的设备；同时对于列表页面等动态页面无法达到效果，因此使用不推荐该选择器。

注意参数的这四个数字不能随意填写，必须精确的填写控件的四个边界才能找到该控件。例如，要点击QQ主界面的右上角加号，我们用布局分析查看该控件的属性，如下图：

可以看到bounds属性为(951, 67, 1080, 196)，此时使用代码bounds(951, 67, 1080, 196).clickable().click()即可点击该控件。

UiSelector.boundsInside(left, top, right, buttom)#
left 范围左边缘与屏幕左边的距离
top 范围上边缘与屏幕上边的距离
right 范围右边缘与屏幕左边的距离
bottom 范围下边缘与屏幕上边的距离
为当前选择器附加控件"bounds需要在left, top, right, buttom构成的范围里面"的条件。

这个条件用于限制选择器在某一个区域选择控件。例如要在屏幕上半部分寻找文本控件TextView，代码为:

var w = className(“TextView”).boundsInside(0, 0, device.width, device.height / 2).findOne();
log(w.text());
其中我们使用了device.width来获取屏幕宽度，device.height来获取屏幕高度。

UiSelector.boundsContains(left, top, right, buttom)#
left 范围左边缘与屏幕左边的距离
top 范围上边缘与屏幕上边的距离
right 范围右边缘与屏幕左边的距离
bottom 范围下边缘与屏幕上边的距离
为当前选择器附加控件"bounds需要包含left, top, right, buttom构成的范围"的条件。

这个条件用于限制控件的范围必须包含所给定的范围。例如给定一个点(500, 300), 寻找在这个点上的可点击控件的代码为:

var w = boundsContains(500, 300, 500, 300).clickable().findOne();
w.click();
UiSelector.drawingOrder(order)#
order 控件在父视图中的绘制顺序
为当前选择器附加控件"drawingOrder等于order"的条件。

drawingOrder为一个控件在父控件中的绘制顺序，通常可以用于区分同一层次的控件。

但该属性在Android 7.0以上才能使用。

UiSelector.clickable([b = true])#
b 表示控件是否可点击
为当前选择器附加控件是否可点击的条件。但并非所有clickable为false的控件都真的不能点击，这取决于控件的实现。对于自定义控件(例如显示类名为android.view.View的控件)很多的clickable属性都为false都却能点击。

需要注意的是，可以省略参数b而表示选择那些可以点击的控件，例如className(“ImageView”).clickable()表示可以点击的图片控件的条件，className(“ImageView”).clickable(false)表示不可点击的图片控件的条件。

UiSelector.longClickable([b = true])#
b 表示控件是否可长按
为当前选择器附加控件是否可长按的条件。

UiSelector.checkable([b = true])#
b 表示控件是否可勾选
为当前选择器附加控件是否可勾选的条件。勾选通常是对于勾选框而言的，例如图片多选时左上角通常有一个勾选框。

UiSelector.selected([b = true])#
b 表示控件是否被选
为当前选择器附加控件是否已选中的条件。被选中指的是，例如QQ聊天界面点击下方的"表情按钮"时，会出现自己收藏的表情，这时"表情按钮"便处于选中状态，其selected属性为true。

UiSelector.enabled([b = true])#
b 表示控件是否已启用
为当前选择器附加控件是否已启用的条件。大多数控件都是启用的状态(enabled为true)，处于“禁用”状态通常是灰色并且不可点击。

UiSelector.scrollable([b = true])#
b 表示控件是否可滑动
为当前选择器附加控件是否可滑动的条件。滑动包括上下滑动和左右滑动。

可以用这个条件来寻找可滑动控件来滑动界面。例如滑动Auto.js的脚本列表的代码为:

className(“android.support.v7.widget.RecyclerView”).scrollable().findOne().scrollForward();
//或者classNameEndsWith(“RecyclerView”).scrollable().findOne().scrollForward();
UiSelector.editable([b = true])#
b 表示控件是否可编辑
为当前选择器附加控件是否可编辑的条件。一般来说可编辑的控件为输入框(EditText)，但不是所有的输入框(EditText)都可编辑。

UiSelector.multiLine([b = true])#
b 表示文本或输入框控件是否是多行显示的
为当前选择器附加控件是否文本或输入框控件是否是多行显示的条件。

UiSelector.findOne()#
返回 UiObject
根据当前的选择器所确定的筛选条件，对屏幕上的控件进行搜索，直到屏幕上出现满足条件的一个控件为止，并返回该控件。如果找不到控件，当屏幕内容发生变化时会重新寻找，直至找到。

需要注意的是，如果屏幕上一直没有出现所描述的控件，则该函数会阻塞，直至所描述的控件出现为止。因此此函数不会返回null。

该函数本来应该命名为untilFindOne()，但由于历史遗留原因已经无法修改。如果想要只在屏幕上搜索一次而不是一直搜索，请使用findOnce()。

另外，如果屏幕上有多个满足条件的控件，findOne()采用深度优先搜索(DFS)，会返回该搜索算法找到的第一个控件。注意控件找到的顺序有时会起到作用。

UiSelector.findOne(timeout)#
timeout 搜索的超时时间，单位毫秒
返回 UiObject
根据当前的选择器所确定的筛选条件，对屏幕上的控件进行搜索，直到屏幕上出现满足条件的一个控件为止，并返回该控件；如果在timeout毫秒的时间内没有找到符合条件的控件，则终止搜索并返回null。

该函数类似于不加参数的findOne()，只不过加上了时间限制。

示例：

//启动Auto.js
launchApp(“Auto.js”);
//在6秒内找出日志图标的控件
var w = id(“action_log”).findOne(6000);
//如果找到控件则点击
if(w != null){
w.click();
}else{
//否则提示没有找到
toast(“没有找到日志图标”);
}
UiSelector.findOnce()#
返回 UiObject
根据当前的选择器所确定的筛选条件，对屏幕上的控件进行搜索，如果找到符合条件的控件则返回该控件；否则返回null。

UiSelector.findOnce(i)#
i 索引
根据当前的选择器所确定的筛选条件，对屏幕上的控件进行搜索，并返回第 i + 1 个符合条件的控件；如果没有找到符合条件的控件，或者符合条件的控件个数 < i, 则返回null。

注意这里的控件次序，是搜索算法深度优先搜索(DSF)决定的。

UiSelector.find()#
返回 UiCollection
根据当前的选择器所确定的筛选条件，对屏幕上的控件进行搜索，找到所有满足条件的控件集合并返回。这个搜索只进行一次，并不保证一定会找到，因而会出现返回的控件集合为空的情况。

不同于findOne()或者findOnce()只找到一个控件并返回一个控件，find()函数会找出所有满足条件的控件并返回一个控件集合。之后可以对控件集合进行操作。

可以通过empty()函数判断找到的是否为空。例如：

var c = className(“AbsListView”).find();
if(c.empty()){
toast(“找到啦”);
}else{
toast(“没找到╭(╯^╰)╮”);
}
UiSelector.untilFind()#
返回 UiCollection
根据当前的选择器所确定的筛选条件，对屏幕上的控件进行搜索，直到找到至少一个满足条件的控件为止，并返回所有满足条件的控件集合。

该函数与find()函数的区别在于，该函数永远不会返回空集合；但是，如果屏幕上一直没有出现满足条件的控件，则该函数会保持阻塞。

UiSelector.exists()#
返回
判断屏幕上是否存在控件符合选择器所确定的条件。例如要判断某个文本出现就执行某个动作，可以用：

if(text(“某个文本”).exists()){
//要支持的动作
}
UiSelector.waitFor()#
等待屏幕上出现符合条件的控件；在满足该条件的控件出现之前，该函数会一直保持阻塞。

例如要等待包含"哈哈哈"的文本控件出现的代码为：

textContains(“哈哈哈”).waitFor();
UiSelector.filter(f)#
f 过滤函数，参数为UiObject，返回值为boolean
为当前选择器附加自定义的过滤条件。

例如，要找出屏幕上所有文本长度为10的文本控件的代码为：

var uc = className(“TextView”).filter(function(w){
return w.text().length == 10;
});
UiObject#
UiObject表示一个控件，可以通过这个对象获取到控件的属性，也可以对控件进行点击、长按等操作。

获取一个UiObject通常通过选择器的findOne(), findOnce()等函数，也可以通过UiCollection来获取，或者通过UiObject.child(), UiObject.parent()等函数来获取一个控件的子控件或父控件。

UiObject.click()#
返回
点击该控件，并返回是否点击成功。

如果该函数返回false，可能是该控件不可点击(clickable为false)，当前界面无法响应该点击等。

UiObject.longClick()#
返回
长按该控件，并返回是否点击成功。

如果该函数返回false，可能是该控件不可点击(longClickable为false)，当前界面无法响应该点击等。

UiObject.setText(text)#
text 文本
返回
设置输入框控件的文本内容，并返回是否设置成功。

该函数只对可编辑的输入框(editable为true)有效。

UiObject.copy()#
返回
对输入框文本的选中内容进行复制，并返回是否操作成功。

该函数只能用于输入框控件，并且当前输入框控件有选中的文本。可以通过setSelection()函数来设置输入框选中的内容。

var et = className(“EditText”).findOne();
//选中前两个字
et.setSelection(0, 2);
//对选中内容进行复制
if(et.copy()){
toast(“复制成功”);
}else{
toast(“复制失败”);
}
UiObject.cut()#
对输入框文本的选中内容进行剪切，并返回是否操作成功。

该函数只能用于输入框控件，并且当前输入框控件有选中的文本。可以通过setSelection()函数来设置输入框选中的内容。

UiObject.paste()#
返回
对输入框控件进行粘贴操作，把剪贴板内容粘贴到输入框中，并返回是否操作成功。

//设置剪贴板内容为“你好”
setClip(“你好”);
var et = className(“EditText”).findOne();
et.paste();
UiObject.setSelection(start, end)#
start 选中内容起始位置
end 选中内容结束位置(不包括)
返回
对输入框控件设置选中的文字内容，并返回是否操作成功。

索引是从0开始计算的；并且，选中内容不包含end位置的字符。例如，如果一个输入框内容为"123456789"，要选中"4567"的文字的代码为et.setSelection(3, 7)。

该函数也可以用来设置光标位置，只要参数的end等于start，即可把输入框光标设置在start的位置。例如et.setSelection(1, 1)会把光标设置在第一个字符的后面。

UiObject.scrollForward()#
返回
对控件执行向前滑动的操作，并返回是否操作成功。

向前滑动包括了向右和向下滑动。如果一个控件既可以向右滑动和向下滑动，那么执行scrollForward()的行为是未知的(这是因为Android文档没有指出这一点，同时也没有充分的测试可供参考)。

UiObject.scrollBackward()#
返回
对控件执行向后滑动的操作，并返回是否操作成功。

向后滑动包括了向右和向下滑动。如果一个控件既可以向右滑动和向下滑动，那么执行scrollForward()的行为是未知的(这是因为Android文档没有指出这一点，同时也没有充分的测试可供参考)。

UiObject.select()#
返回
对控件执行"选中"操作，并返回是否操作成功。"选中"和isSelected()的属性相关，但该操作十分少用。

UiObject.collapse()#
返回
对控件执行折叠操作，并返回是否操作成功。

UiObject.expand()#
返回
对控件执行操作，并返回是否操作成功。

UiObject.show()#
对集合中所有控件执行显示操作，并返回是否全部操作成功。

UiObject.scrollUp()#
对集合中所有控件执行向上滑的操作，并返回是否全部操作成功。

UiObject.scrollDown()#
对集合中所有控件执行向下滑的操作，并返回是否全部操作成功。

UiObject.scrollLeft()#
对集合中所有控件执行向左滑的操作，并返回是否全部操作成功。

UiObject.scrollRight()#
children()#
返回 UiCollection
返回该控件的所有子控件组成的控件集合。可以用于遍历一个控件的子控件，例如：

className(“AbsListView”).findOne().children()
.forEach(function(child){
log(child.className());
});
childCount()#
返回
返回子控件数目。

child(i)#
i 子控件索引
返回
返回第i+1个子控件。如果i>=控件数目或者小于0，则抛出异常。

需要注意的是，由于布局捕捉的问题，该函数可能返回null，也就是可能获取不到某个子控件。

遍历子控件的示例：

var list = className(“AbsListView”).findOne();
for(var i = 0; i < list.childCount(); i++){
var child = list.child(i);
log(child.className());
}
parent()#
返回
返回该控件的父控件。如果该控件没有父控件，返回null。

bounds()#
返回 Rect
返回控件在屏幕上的范围，其值是一个Rect对象。

示例：

var b = text(“Auto.js”).findOne().bounds();
toast(“控件在屏幕上的范围为” + b);
如果一个控件本身无法通过click()点击，那么我们可以利用bounds()函数获取其坐标，再利用坐标点击。例如：

var b = desc(“打开侧拉菜单”).findOne().bounds();
click(b.centerX(), b.centerY());
//如果使用root权限，则用 Tap(b.centerX(), b.centerY());
boundsInParent()#
返回 Rect
返回控件在父控件中的范围，其值是一个Rect对象。

drawingOrder()#
返回
返回控件在父控件中的绘制次序。该函数在安卓7.0及以上才有效，7.0以下版本调用会返回0。

id()#
返回
获取控件的id，如果一个控件没有id，则返回null。

text()#
返回
获取控件的文本，如果控件没有文本，返回""。

findByText(str)#
str 文本
返回 UiCollection
根据文本text在子控件中递归地寻找并返回文本或描述(desc)包含这段文本str的控件，返回它们组成的集合。

该函数会在当前控件的子控件，孙控件，曾孙控件…中搜索text或desc包含str的控件，并返回它们组合的集合。

findOne(selector)#
selector UiSelector
返回 UiOobject
根据选择器selector在该控件的子控件、孙控件…中搜索符合该选择器条件的控件，并返回找到的第一个控件；如果没有找到符合条件的控件则返回null。

例如，对于酷安动态列表，我们可以遍历他的子控件(每个动态列表项)，并在每个子控件中依次寻找点赞数量和图标，对于点赞数量小于10的点赞：

//找出动态列表
var list = id(“recycler_view”).findOne();
//遍历动态
list.children().forEach(function(child){
//找出点赞图标
var like = child.findOne(id(“feed_action_view_like”));
//找出点赞数量
var likeCount = child.findOne(id(“text_view”));
//如果这两个控件没有找到就不继续了
if(like == null || likeCount == null){
return;
}
//判断点赞数量是否小于10
if(parseInt(likeCount.text()) < 10){
//点赞
like.click();
}
});
find(selector)#
selector UiSelector
返回 UiCollection
根据选择器selector在该控件的子控件、孙控件…中搜索符合该选择器条件的控件，并返回它们组合的集合。

UiCollection#
UiCollection, 控件集合, 通过选择器的find(), untilFind()方法返回的对象。

UiCollection"继承"于数组，实际上是一个UiObject的数组，因此可以使用数组的函数和属性，例如使用length属性获取UiCollection的大小，使用forEach函数来遍历UiCollection。

例如，采用forEach遍历屏幕上所有的文本控件并打印出文本内容的代码为：

console.show();
className(“TextView”).find().forEach(function(tv){
if(tv.text() != “”){
log(tv.text());
}
});
也可以使用传统的数组遍历方式：

console.show();
var uc = className(“TextView”).find();
for(var i = 0; i < uc.length; i++){
var tv = uc[i];
if(tv.text() != “”){
log(tv.text());
}
}
UiCollection的每一个元素都是UiObject，我们可以取出他的元素进行操作，例如取出第一个UiObject并点击的代码为ui[0].click()。如果想要对该集合的所有元素进行操作，可以直接在集合上调用相应的函数，例如uc.click()，该代码会对集合上所有UiObject执行点击操作并返回是否全部点击成功。

因此，UiCollection具有所有UiObject对控件操作的函数，包括click(), longClick(), scrollForward()等等，不再赘述。

UiCollection.size()#
返回
返回集合中的控件数。

历史遗留函数，相当于属性length。

UiCollection.get(i)#
i 索引
返回 UiObject
返回集合中第i+1个控件(UiObject)。

历史遗留函数，建议直接使用数组下标的方式访问元素。

UiCollection.each(func)#
func 遍历函数，参数为UiObject。
遍历集合。

历史遗留函数，相当于forEach。参考forEach。

empty()#
返回
返回控件集合是否为空。

nonEmpty()#
返回
返回控件集合是否非空。

UiCollection.find(selector)#
selector UiSelector
返回 UiCollection
根据selector所确定的条件在该控件集合的控件、子控件、孙控件…中找到所有符合条件的控件并返回找到的控件集合。

注意这会递归地遍历控件集合里所有的控件以及他们的子控件。和数组的filter函数不同。

例如：

var names = id(“name”).find();
//在集合
var clickableNames = names.find(clickable());
UiCollection.findOne(selector)#
selector UiSelector
返回 UiOobject
根据选择器selector在该控件集合的控件的子控件、孙控件…中搜索符合该选择器条件的控件，并返回找到的第一个控件；如果没有找到符合条件的控件则返回null。

Rect#
UiObject.bounds(), UiObject.boundsInParent()返回的对象。表示一个长方形(范围)。

Rect.left#

长方形左边界的x坐标、

Rect.right#

长方形右边界的x坐标、

Rect.top#

长方形上边界的y坐标、

Rect.bottom#

长方形下边界的y坐标、

Rect.centerX()#
返回
长方形中点x坐标。

Rect.centerY()#
返回
长方形中点y坐标。

Rect.width()#
返回
长方形宽度。通常可以作为控件宽度。

Rect.height()#
返回
长方形高度。通常可以作为控件高度。

Rect.contains®#
r Rect
返回是否包含另一个长方形r。包含指的是，长方形r在该长方形的里面(包含边界重叠的情况)。

Rect.intersect®#
r Rect
返回是否和另一个长方形相交。

UiSelector进阶#
未完待续。
Sensors#
Stability: 2 - Stable
sensors模块提供了获取手机上的传感器的信息的支持，这些传感器包括距离传感器、光线光感器、重力传感器、方向传感器等。需要指出的是，脚本只能获取传感器的数据，不能模拟或伪造传感器的数据和事件，因此诸如模拟摇一摇的功能是无法实现的。

要监听一个传感器时，需要使用sensors.register()注册监听器，之后才能开始监听；不需要监听时则调用sensors.unregister()注销监听器。在脚本结束时会自动注销所有的监听器。同时，这种监听会使脚本保持运行状态，如果不注销监听器，脚本会一直保持运行状态。

例如，监听光线传感器的代码为：

//光线传感器监听
sensors.register(“light”).on(“change”, (event, light)=>{
log(“当前光强度为”, light);
});
要注意的是，每个传感器的数据并不相同，所以对他们调用on()监听事件时的回调函数参数也不是相同，例如光线传感器参数为(event, light)，加速度传感器参数为(event, ax, ay, az)。甚至在某些设备上的传感器参数有所增加，例如华为手机的距离传感器为三个参数，一般手机只有一个参数。

常用的传感器及其事件参数如下表：

accelerometer 加速度传感器，参数(event, ax, ay, az):

event SensorEvent 传感器事件，用于获取传感器数据变化时的所有信息
ax x轴上的加速度，单位m/s^2
ay y轴上的加速度，单位m/s^2
az z轴上的加速度，单位m/s^2 这里的x轴，y轴，z轴所属的坐标系统如下图(其中z轴垂直于设备屏幕表面):

!axis_device

orientation 方向传感器，参数(event, azimuth, pitch, roll):

event SensorEvent 传感器事件，用于获取传感器数据变化时的所有信息
azimuth 方位角，从地磁指北方向线起，依顺时针方向到y轴之间的水平夹角，单位角度，范围0~359
pitch 绕x轴旋转的角度，当设备水平放置时该值为0，当设备顶部翘起时该值为正数，当设备尾部翘起时该值为负数，单位角度，范围-180~180
roll 绕y轴顺时针旋转的角度，单位角度，范围-90~90
gyroscope 陀螺仪传感器，参数(event, wx, wy, wz):

event SensorEvent 传感器事件，用于获取传感器数据变化时的所有信息
wx 绕x轴的角速度，单位弧度/s
wy 绕y轴的角速度，单位弧度/s
wz 绕z轴的角速度，单位弧度/s
magnetic_field 磁场传感器，参数(event, bx, by, bz):

event SensorEvent 传感器事件，用于获取传感器数据变化时的所有信息
bx x轴上的磁场强度，单位uT
by y轴上的磁场强度，单位uT
bz z轴上的磁场强度，单位uT
gravity 重力传感器，参数(event, gx, gy, gz):

event SensorEvent 传感器事件，用于获取传感器数据变化时的所有信息
gx x轴上的重力加速度，单位m/s^2
gy y轴上的重力加速度，单位m/s^2
gz z轴上的重力加速度，单位m/s^2
linear_acceleration 线性加速度传感器，参数(event, ax, ay, az):

event SensorEvent 传感器事件，用于获取传感器数据变化时的所有信息
ax x轴上的线性加速度，单位m/s^2
ay y轴上的线性加速度，单位m/s^2
az z轴上的线性加速度，单位m/s^2
ambient_temperature 环境温度传感器，大部分设备并不支持，参数(event, t):

event SensorEvent 传感器事件，用于获取传感器数据变化时的所有信息
t 环境温度，单位摄氏度。
light 光线传感器，参数(event, light):

event SensorEvent 传感器事件，用于获取传感器数据变化时的所有信息
light 环境光强度，单位lux
pressure 压力传感器，参数(event, p):

event SensorEvent 传感器事件，用于获取传感器数据变化时的所有信息
p 大气压，单位hPa
proximity 距离传感器，参数(event, distance):

event SensorEvent 传感器事件，用于获取传感器数据变化时的所有信息
distance 一般指设备前置摄像头旁边的距离传感器到前方障碍物的距离，并且很多设备上这个值只有两种情况：当障碍物较近时该值为0，当障碍物较远或在范围内没有障碍物时该值为5
relative_humidity 湿度传感器，大部分设备并不支持，参数(event, rh):

event SensorEvent 传感器事件，用于获取传感器数据变化时的所有信息
rh 相对湿度，范围为0~100（百分比）
sensors.register(sensorName[, delay])#
sensorName 传感器名称，常用的传感器名称如上面所述
delay 传感器数据更新频率，可选，默认为sensors.delay.normal。可用的值如下：
sensors.delay.normal 正常频率
sensors.delay.ui 适合于用户界面的更新频率
sensors.delay.game 适合于游戏的更新频率
sensors.delay.fastest 最快的更新频率】
返回 SensorEventEmiiter
注册一个传感器监听并返回SensorEventEmitter。

例如:

console.show();
//注册传感器监听
var sensor = sensors.register(“gravity”);
if(sensor == null){
toast(“不支持重力传感器”);
exit();
}
//监听数据
sensor.on(“change”, (gx, gy, gz)=>{
log(“重力加速度: %d, %d, %d”, gx, gy, gz);
});
可以通过delay参数来指定传感器数据的更新频率，例如：

var sensor = sensors.register(“gravity”, sensors.delay.game);
另外，如果不支持sensorName所指定的传感器，那么该函数将返回null；但如果sensors.ignoresUnsupportedSensor的值被设置为true, 则该函数会返回一个不会分发任何传感器事件的SensorEventEmitter。

例如:

sensors.ignoresUnsupportedSensor = true;
//无需null判断
sensors.register(“gravity”).on(“change”, (gx, gy, gz)=>{
log(“重力加速度: %d, %d, %d”, gx, gy, gz);
});
更多信息，参见SensorEventEmitter和sensors.ignoresUnsupportedSensor。

sensors.unregister(emitter)#
emiiter SensorEventEmitter
注销该传感器监听器。被注销的监听器将不再能监听传感器数据。

//注册一个传感器监听器
var sensor = sensors.register(“gravity”);
if(sensor == null){
exit();
}
//2秒后注销该监听器
setTimeout(()=> {
sensors.unregister(sensor);
}, 2000);
sensors.unregisterAll()#
注销所有传感器监听器。

sensors.ignoresUnsupportedSensor#

表示是否忽略不支持的传感器。如果该值被设置为true，则函数sensors.register()即使对不支持的传感器也会返回一个无任何数据的虚拟传感器监听，也就是sensors.register()不会返回null从而避免非空判断，并且此时会触发sensors的"unsupported_sensor"事件。

//忽略不支持的传感器
sensors.ignoresUnsupportedSensor = true;
//监听有不支持的传感器时的事件
sensors.on(“unsupported_sensor”, function(sensorName){
toastLog("不支持的传感器: " + sensorName);
});
//随便注册一个不存在的传感器。
log(sensors.register(“aaabbb”));
事件: ‘unsupported_sensor’#
sensorName 不支持的传感器名称
当sensors.ignoresUnsupportedSensor被设置为true并且有不支持的传感器被注册时触发该事件。事件参数的传感器名称。

SensorEventEmitter#
注册传感器返回的对象，其本身是一个EventEmmiter，用于监听传感器事件。

事件: ‘change’#
…args 传感器参数
当传感器数据改变时触发该事件；该事件触发的最高频繁由sensors.register()指定的delay参数决定。

事件参数根据传感器类型不同而不同，具体参见本章最前面的列表。

一个监听光线传感器和加速度传感器并且每0.5秒获取一个数据并最终写入一个csv表格文件的例子如下：

//csv文件路径
cosnt csvPath = “/sdcard/sensors_data.csv”;
//记录光线传感器的数据
var light = 0;
//记录加速度传感器的数据
var ax = 0;
var ay = 0;
var az = 0;
//监听光线传感器
sensors.register(“light”, sensors.delay.fastest)
.on(“change”, l => {
light = l;
});
//监听加速度传感器
sensors.register(“accelerometer”, sensors.delay.fastest)
.on(“change”, (ax0, ay0, az0) => {
ax = ax0;
ay = ay0;
az = az0;
});

var file = open(csvPath, “w”);
//写csv表格头
file.writeline(“light,ax,ay,az”)
//每0.5秒获取一次数据并写入文件
setInterval(()=>{
file.writeline(util.format("%d,%d,%d,%d", light, ax, ay, az));
}, 500);
//10秒后退出并打开文件
setTimeout(()=>{
file.close();
sensors.unregsiterAll();
app.viewFile(csvPath);
}, 10 * 1000);

事件: ‘accuracy_change’#
accuracy 表示传感器精度。为以下值之一:
-1 传感器未连接
0 传感器不可读
1 低精度
2 中精度
3 高精度
当传感器精度改变时会触发的事件。比较少用。

shell即Unix Shell，在类Unix系统提供与操作系统交互的一系列命令。

很多程序可以用来执行shell命令，例如终端模拟器。

在Auto.js大致等同于用adb执行命令"adb shell"。其实现包括两种方式：

通过java.lang.Runtime.exec执行(shell, Tap, Home等函数)
通过内嵌终端模拟器执行(RootAutomator, Shell等对象)
shell函数#
Stability: 2 - Stable
shell(cmd[, root])#
cmd 要执行的命令
root 是否以root权限运行，默认为false。
一次性执行命令cmd, 并返回命令的执行结果。返回对象的其属性如下:

code 返回码。执行成功时为0，失败时为非0的数字。
result 运行结果(stdout输出结果)
error 运行的错误信息(stderr输出结果)。例如执行需要root权限的命令但没有授予root权限会返回错误信息"Permission denied"。
示例(强制停止微信) ：

var result = shell(“am force-stop com.tencent.mm”, true);
log(result);
console.show();
if(result.code == 0){
toast(“执行成功”);
}else{
toast(“执行失败！请到控制台查看错误信息”);
}
Shell#
Stability: 2 - Stable
shell函数通过用来一次性执行单条命令并获取结果。如果有多条命令需要执行，用Shell对象的效率更高。这是因为，每次运行shell函数都会打开一个单独的shell进程并在运行结束后关闭他，这个过程需要一定的时间；而Shell对象自始至终使用同一个shell进程。

new Shell(root)#
root 是否以root权限运行一个shell进程，默认为false。这将会影响其后使用该Shell对象执行的命令的权限
Shell对象的"构造函数"。

var sh = new Shell(true);
//强制停止微信
sh.exec(“am force-stop com.tencent.mm”);
sh.exit();
Shell.exec(cmd)#
cmd 要执行的命令
执行命令cmd。该函数不会返回任何值。

注意，命令执行是"异步"的、非阻塞的。也就是不会等待命令完成后才继续向下执行。

尽管这样的设计使用起来有很多不便之处，但受限于终端模拟器，暂时没有解决方式；如果后续能找到解决方案，则将提供Shell.execAndWaitFor函数。

Shell.exit()#
直接退出shell。正在执行的命令会被强制退出。

Shell.exitAndWaitFor()#
执行"exit"命令并等待执行命令执行完成、退出shell。

此函数会执行exit命令来正常退出shell。

Shell.setCallback(callback)#
callback 回调函数
设置该Shell的回调函数，以便监听Shell的输出。可以包括以下属性：

onOutput 每当shell有新的输出时便会调用该函数。其参数是一个字符串。
onNewLine 每当shell有新的一行输出时便会调用该函数。其参数是一个字符串(不包括最后的换行符)。
例如:

am命令#
am命令即Activity Manager命令，用于管理应用程序活动、服务等。

以下命令均以"am "开头，例如shell(‘am start -p com.tencent.mm’);(启动微信)

start [options] intent#
启动 intent 指定的 Activity(应用程序活动)。
请参阅 intent 参数的规范。

选项包括：

-D：启用调试。
-W：等待启动完成。
–start-profiler file：启动分析器并将结果发送到 file。
-P file：类似于 --start-profiler，但当应用进入空闲状态时分析停止。
-R count：重复 Activity 启动 count 次数。在每次重复前，将完成顶部 Activity。
-S：启动 Activity 前强行停止目标应用。
–opengl-trace：启用 OpenGL 函数的跟踪。
–user user_id | current：指定要作为哪个用户运行；如果未指定，则作为当前用户运行。
startservice [options] intent#
启动 intent 指定的 Service(服务)。
请参阅 intent 参数的规范。
选项包括：

–user user_id | current：指定要作为哪个用户运行；如果未指定，则作为当前用户运行。
force-stop package#
强行停止与 package（应用包名）关联的所有应用。

kill [options] package#
终止与 package（应用包名）关联的所有进程。此命令仅终止可安全终止且不会影响用户体验的进程。
选项包括：

–user user_id | all | current：指定将终止其进程的用户；如果未指定，则终止所有用户的进程。
kill-all#
终止所有后台进程。

broadcast [options] intent#
发出广播 intent。请参阅 intent 参数的规范。

选项包括：

[–user user_id | all | current]：指定要发送到的用户；如果未指定，则发送到所有用户。
instrument [options] component#
使用 Instrumentation 实例启动监控。通常，目标 component 是表单 test_package/runner_class。
选项包括：

-r：输出原始结果（否则对 report_key_streamresult 进行解码）。与 [-e perf true] 结合使用以生成性能测量的原始输出。
-e name value：将参数 name 设为 value。对于测试运行器，通用表单为 -e testrunner_flag value[,value…]。
-p file：将分析数据写入 file。
-w：先等待仪器完成，然后再返回。测试运行器需要使用此选项。
–no-window-animation：运行时关闭窗口动画。
–user user_id | current：指定仪器在哪个用户中运行；如果未指定，则在当前用户中运行。
profile start process file 启动 process 的分析器，将结果写入 file。
profile stop process 停止 process 的分析器。
dumpheap [options] process file#
转储 process 的堆，写入 file。

选项包括：

–user [user_id|current]：提供进程名称时，指定要转储的进程用户；如果未指定，则使用当前用户。
-n：转储原生堆，而非托管堆。
set-debug-app [options] package 将应用 package 设为调试。
选项包括：

-w：应用启动时等待调试程序。
–persistent：保留此值。
clear-debug-app 使用 set-debug-app 清除以前针对调试用途设置的软件包。
monitor [options] 启动对崩溃或 ANR 的监控。#
选项包括：

–gdb：在崩溃/ANR 时在给定端口上启动 gdbserv。
screen-compat | package#
控制 package 的屏幕兼容性模式。
display-size [reset|widthxheight]#
替换模拟器/设备显示尺寸。此命令对于在不同尺寸的屏幕上测试您的应用非常有用，它支持使用大屏设备模仿小屏幕分辨率（反之亦然）。
示例：

shell(“am display-size 1280x800”, true);

display-density dpi#
替换模拟器/设备显示密度。此命令对于在不同密度的屏幕上测试您的应用非常有用，它支持使用低密度屏幕在高密度环境环境上进行测试（反之亦然）。
示例：

shell(“am display-density 480”, true);
to-uri intent#
将给定的 intent 规范以 URI 的形式输出。请参阅 intent 参数的规范。

to-intent-uri intent#
将给定的 intent 规范以 intent:URI 的形式输出。请参阅 intent 参数的规范。

intent参数的规范#
对于采用 intent 参数的 am 命令，您可以使用以下选项指定 intent：

-a action
指定 intent 操作，如“android.intent.action.VIEW”。此指定只能声明一次。
-d data_uri
指定 intent 数据 URI，如“content://contacts/people/1”。此指定只能声明一次。
-t mime_type
指定 intent MIME 类型，如“image/png”。此指定只能声明一次。
-c category
指定 intent 类别，如“android.intent.category.APP_CONTACTS”。
-n component
指定带有软件包名称前缀的组件名称以创建显式 intent，如“com.example.app/.ExampleActivity”。
-f flags
将标志添加到 setFlags() 支持的 intent。
–esn extra_key
添加一个 null extra。URI intent 不支持此选项。
-e|–es extra_key extra_string_value
添加字符串数据作为键值对。
–ez extra_key extra_boolean_value
添加布尔型数据作为键值对。
–ei extra_key extra_int_value
添加整数型数据作为键值对。
–el extra_key extra_long_value
添加长整型数据作为键值对。
–ef extra_key extra_float_value
添加浮点型数据作为键值对。
–eu extra_key extra_uri_value
添加 URI 数据作为键值对。
–ecn extra_key extra_component_name_value
添加组件名称，将其作为 ComponentName 对象进行转换和传递。
–eia extra_key extra_int_value[,extra_int_value…]
添加整数数组。
–ela extra_key extra_long_value[,extra_long_value…]
添加长整型数组。
–efa extra_key extra_float_value[,extra_float_value…]
添加浮点型数组。
–grant-read-uri-permission
包含标志 FLAG_GRANT_READ_URI_PERMISSION。
–grant-write-uri-permission
包含标志 FLAG_GRANT_WRITE_URI_PERMISSION。
–debug-log-resolution
包含标志 FLAG_DEBUG_LOG_RESOLUTION。
–exclude-stopped-packages
包含标志 FLAG_EXCLUDE_STOPPED_PACKAGES。
–include-stopped-packages
包含标志 FLAG_INCLUDE_STOPPED_PACKAGES。
–activity-brought-to-front
包含标志 FLAG_ACTIVITY_BROUGHT_TO_FRONT。
–activity-clear-top
包含标志 FLAG_ACTIVITY_CLEAR_TOP。
–activity-clear-when-task-reset
包含标志 FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET。
–activity-exclude-from-recents
包含标志 FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS。
–activity-launched-from-history
包含标志 FLAG_ACTIVITY_LAUNCHED_FROM_HISTORY。
–activity-multiple-task
包含标志 FLAG_ACTIVITY_MULTIPLE_TASK。
–activity-no-animation
包含标志 FLAG_ACTIVITY_NO_ANIMATION。
–activity-no-history
包含标志 FLAG_ACTIVITY_NO_HISTORY。
–activity-no-user-action
包含标志 FLAG_ACTIVITY_NO_USER_ACTION。
–activity-previous-is-top
包含标志 FLAG_ACTIVITY_PREVIOUS_IS_TOP。
–activity-reorder-to-front
包含标志 FLAG_ACTIVITY_REORDER_TO_FRONT。
–activity-reset-task-if-needed
包含标志 FLAG_ACTIVITY_RESET_TASK_IF_NEEDED。
–activity-single-top
包含标志 FLAG_ACTIVITY_SINGLE_TOP。
–activity-clear-task
包含标志 FLAG_ACTIVITY_CLEAR_TASK。
–activity-task-on-home
包含标志 FLAG_ACTIVITY_TASK_ON_HOME。
–receiver-registered-only
包含标志 FLAG_RECEIVER_REGISTERED_ONLY。
–receiver-replace-pending
包含标志 FLAG_RECEIVER_REPLACE_PENDING。
–selector
需要使用 -d 和 -t 选项以设置 intent 数据和类型。
URI component package#
如果不受上述某一选项的限制，您可以直接指定 URI、软件包名称和组件名称。当参数不受限制时，如果参数包含一个“:”（冒号），则此工具假定参数是一个 URI；如果参数包含一个“/”（正斜杠），则此工具假定参数是一个组件名称；否则，此工具假定参数是一个软件包名称。
应用包名#
所谓应用包名，是唯一确定应用的标识。例如微信的包名是"com.tencent.mm", QQ的包名是"com.tencent.mobileqq"。
要获取一个应用的包名，可以通过函数getPackageName(appName)获取。参见帮助->其他一般函数。

pm命令#
pm命令用于管理应用程序，例如卸载应用、冻结应用等。
以下命令均以"pm “开头，例如"shell(“pm disable com.tencent.mm”);”(冻结微信)

list packages [options] filter#
输出所有软件包，或者，仅输出包名称包含 filter 中的文本的软件包。
选项：

-f：查看它们的关联文件。
-d：进行过滤以仅显示已停用的软件包。
-e：进行过滤以仅显示已启用的软件包。
-s：进行过滤以仅显示系统软件包。
-3：进行过滤以仅显示第三方软件包。
-i：查看软件包的安装程序。
-u：也包括卸载的软件包。
–user user_id：要查询的用户空间。
list permission-groups#
输出所有已知的权限组。

list permissions [options] group#
输出所有已知权限，或者，仅输出 group 中的权限。
选项：

-g：按组加以组织。
-f：输出所有信息。
-s：简短摘要。
-d：仅列出危险权限。
-u：仅列出用户将看到的权限。
list instrumentation [options]#
列出所有测试软件包。
选项：

-f：列出用于测试软件包的 APK 文件。
target_package：列出仅用于此应用的测试软件包。
list features#
输出系统的所有功能。

list libraries#
输出当前设备支持的所有库。

list users#
输出系统上的所有用户。

path package#
输出给定 package 的 APK 的路径。

install [options] path#
将软件包（通过 path 指定）安装到系统。
选项：

-l：安装具有转发锁定功能的软件包。
-r：重新安装现有应用，保留其数据。
-t：允许安装测试 APK。
-i installer_package_name：指定安装程序软件包名称。
-s：在共享的大容量存储（如 sdcard）上安装软件包。
-f：在内部系统内存上安装软件包。
-d：允许版本代码降级。
-g：授予应用清单文件中列出的所有权限。
uninstall [options] package#
从系统中卸载软件包。
选项：

-k：移除软件包后保留数据和缓存目录。
clear package#
删除与软件包关联的所有数据。
enable package_or_component#
启用给定软件包或组件（作为“package/class”写入）。

disable package_or_component#
停用给定软件包或组件（作为“package/class”写入）。

disable-user [options] package_or_component#
选项：

–user user_id：要停用的用户。
grant package_name permission#
向应用授予权限。在运行 Android 6.0（API 级别 23）及更高版本的设备上，可以是应用清单中声明的任何权限。在运行 Android 5.1（API 级别 22）和更低版本的设备上，必须是应用定义的可选权限。
revoke package_name permission#
从应用中撤销权限。在运行 Android 6.0（API 级别 23）及更高版本的设备上，可以是应用清单中声明的任何权限。在运行 Android 5.1（API 级别 22）和更低版本的设备上，必须是应用定义的可选权限。

set-install-location location#
更改默认安装位置。位置值：

0：自动—让系统决定最佳位置。
1：内部—安装在内部设备存储上。
2：外部—安装在外部介质上。
注：此命令仅用于调试目的；使用此命令会导致应用中断和其他意外行为。

get-install-location#
返回当前安装位置。返回值：

0 [auto]：让系统决定最佳位置。
1 [internal]：安装在内部设备存储上
2 [external]：安装在外部介质上
set-permission-enforced permission [true|false]#
指定是否应强制执行给定的权限。

trim-caches desired_free_space#
减少缓存文件以达到给定的可用空间。

create-user user_name#
使用给定的 user_name 创建新用户，输出新用户的标识符。

remove-user user_id#
移除具有给定的 user_id 的用户，删除与该用户关联的所有数据。

get-max-users#
输出设备支持的最大用户数。

其他命令#
进行屏幕截图#
screencap 命令是一个用于对设备显示屏进行屏幕截图的 shell 实用程序。在 shell 中，此语法为：

screencap filename
例如：

$ shell(“screencap /sdcard/screen.png”);
列表文件#
ls filepath
例如:

log(shell(“ls /system/bin”).result);
Storages#
Stability: 2 - Stable
storages模块提供了保存简单数据、用户配置等的支持。保存的数据除非应用被卸载或者被主动删除，否则会一直保留。

storages支持number, boolean, string等数据类型以及把Object, Array用JSON.stringify序列化存取。

storages保存的数据在脚本之间是共享的，任何脚本只要知道storage名称便可以获取到相应的数据，因此它不能用于敏感数据的储存。 storages无法像Web开发中LocalStorage一样提供根据域名独立的存储，因为脚本的路径随时可能改变。

storages.create(name)#
name 本地存储名称
创建一个本地存储并返回一个Storage对象。不同名称的本地存储的数据是隔开的，而相同名称的本地存储的数据是共享的。

例如在一个脚本中，创建名称为ABC的存储并存入a=123:

var storage = storages.create(“ABC”);
storage.put(“a”, 123);
而在另一个脚本中是可以获取到ABC以及a的值的：

var storage = storages.create(“ABC”);
log("a = " + storage.get(“a”));
因此，本地存储的名称比较重要，尽量使用含有域名、作者邮箱等唯一信息的名称来避免冲突，例如：

var storage = storages.create(“2732014414@qq.com:ABC”);
storages.remove(name)#
name 本地存储名称
删除一个本地存储以及他的全部数据。如果该存储不存在，返回false；否则返回true。

Storages#
Storage.get(key[, defaultValue])#
key 键值
defaultValue 可选，默认值
从本地存储中取出键值为key的数据并返回。

如果该存储中不包含该数据，这时若指定了默认值参数则返回默认值，否则返回undefined。

返回的数据可能是任意数据类型，这取决于使用Storage.put保存该键值的数据时的数据类型。

Storage.put(key, value)#
key 键值
value 值
把值value保存到本地存储中。value可以是undefined以外的任意数据类型。如果value为undefined则抛出TypeError。

存储的过程实际上是使用JSON.stringify把value转换为字符串再保存，因此value必须是可JSON化的才能被接受。

Storage.remove(key)#
key 键值
移除键值为key的数据。不返回任何值。

Storage.contains(key)#
key 键值
返回该本地存储是否包含键值为key的数据。是则返回true，否则返回false。

Storage.clear()#
移除该本地存储的所有数据。不返回任何值。
Threads#
Stability: 1 - Experiment
threads模块提供了多线程支持，可以启动新线程来运行脚本。

脚本主线程会等待所有子线程执行完成后才停止执行，因此如果子线程中有死循环，请在必要的时候调用exit()来直接停止脚本或threads.shutDownAll()来停止所有子线程。

通过threads.start()启动的所有线程会在脚本被强制停止时自动停止。

由于JavaScript自身没有多线程的支持，因此您可能会遇到意料之外的问题。

threads.start(action)#
action 要在新线程执行的函数
返回 Thread
启动一个新线程并执行action。

例如:

threads.start(function(){
//在新线程执行的代码
while(true){
log(“子线程”);
}
});
while(true){
log(“脚本主线程”);
}
通过该函数返回的Thread对象可以获取该线程的状态，控制该线程的运行中。例如:

var thread = threads.start(function(){
while(true){
log(“子线程”);
}
});
//停止线程执行
thread.interrupt();
更多信息参见Thread。

threads.shutDownAll()#
停止所有通过threads.start()启动的子线程。

threads.currentThread()#
返回 Thread
返回当前线程。

threads.disposable()#
返回 Disposable
新建一个Disposable对象，用于等待另一个线程的某个一次性结果。更多信息参见线程通信以及Disposable。

threads.atomic([initialValue])#
initialValue 初始整数值，默认为0
返回AtomicLong
新建一个整数原子变量。更多信息参见线程安全以及AtomicLong。

threads.lock()#
返回ReentrantLock
新建一个可重入锁。更多信息参见线程安全以及ReentrantLock。

Thread#
线程对象，threads.start()返回的对象，用于获取和控制线程的状态，与其他线程交互等。

Thread对象提供了和timers模块一样的API，例如setTimeout(), setInterval()等，用于在该线程执行相应的定时回调，从而使线程之间可以直接交互。例如：

var thread = threads.start(function(){
//在子线程执行的定时器
setInterval(function(){
log(“子线程:” + threads.currentThread());
}, 1000);
});

log(“当前线程为主线程:” + threads.currentThread());

//等待子线程启动
thread.waitFor();
//在子线程执行的定时器
thread.setTimeout(function(){
//这段代码会在子线程执行
log(“当前线程为子线程:” + threads.currentThread());
}, 2000);

sleep(30 * 1000);
thread.interrupt();
Thread.interrupt()#
中断线程运行。

Thread.join([timeout])#
timeout 等待时间，单位毫秒
等待线程执行完成。如果timeout为0，则会一直等待直至该线程执行完成；否则最多等待timeout毫秒的时间。

例如:

var sum = 0;
//启动子线程计算1加到10000
var thread = threads.start(function(){
for(var i = 0; i < 10000; i++){
sum += i;
}
});
//等待该线程完成
thread.join();
toast("sum = " + sum);
isAlive()#
返回
返回线程是否存活。如果线程仍未开始或已经结束，返回false; 如果线程已经开始或者正在运行中，返回true。

waitFor()#
等待线程开始执行。调用threads.start()以后线程仍然需要一定时间才能开始执行，因此调用此函数会等待线程开始执行；如果线程已经处于执行状态则立即返回。

var thread = threads.start(function(){
//do something
});
thread.waitFor();
thread.setTimeout(function(){
//do something
}, 1000);
Thread.setTimeout(callback, delay[, …args])#
参见timers.setTimeout()。