插件 - Plugins

# 插件 Auto.js提供了加载插件的机制,允许用户编写带有Activity, Service, C/C++库等的apk,安装到Android设备上,并用Auto.js加载和调用。 一个插件是一个可独立安装的apk文件,用户安装后,再通过`$plugins`模块加载插件和调用其中的API。 ## $plugins.load(packageName) * `packageName` {string} 加载的插件包名 加载一个插件,并返回插件模块中module.exports导出的对象。 如果插件未安装,则抛出`PluginLoadException`异常。 以下为一个OCR插件的使用例子:(插件下载地址参见[OCR插件](#ocr插件)) ```javascript requestScreenCapture(); let OCR = $plugins.load('org.autojs.plugin.ocr'); let ocr = new OCR(); // 截取屏幕并对屏幕文字进行识别,返回识别结果 console.log(ocr.ocrScreen()); ``` ## 如何开发一个插件 > 以下示例代码可在这里找到完整项目:[插件SDK](https://github.com/hyb1996/Auto.js-Plugin-SDK) 本示例中的包名均为`org.autojs.plugin.sdk.demo`,在实际项目中插件包名可能有所不同。 ### 插件SDK集成 新建一个Android项目,在项目的build.gradle文件中添加: ```groovy allprojects { repositories { // ... maven { url 'https://jitpack.io' } } } ``` 在具体模块(比如app)的build.gradle文件中添加: ```groovy dependencies { // ... implementation 'com.github.hyb1996:Auto.js-Plugin-SDK:0.2' } ``` 更多信息参见[Jitpack.io](https://jitpack.io/#hyb1996/Auto.js-Plugin-SDK/0.2)。 ### 插件配置 #### 1. 新建`PluginHelloWorld`文件,继承于Plugin. ```java public class PluginHelloWorld extends Plugin { public PluginHelloWorld(Context context, Context selfContext, Object runtime, Object topLevelScope) { super(context, selfContext, runtime, topLevelScope); } // 返回插件的JavaScript胶水层代码的assets目录路径 @Override public String getAssetsScriptDir() { return "plugin-helloworld"; } // 插件public API,可被JavaScript代码调用 public String getStringFromJava() { return "Hello, Auto.js!"; } // 插件public API,可被JavaScript代码调用 public void say(String message) { getSelfContext().startActivity(new Intent(getSelfContext(), HelloWorldActivity.class) .putExtra("message", message) .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)); } } ``` #### 2. 新增`MyPluginRegistry`文件,继承于PluginRegistry: ```java public class MyPluginRegistry extends PluginRegistry { static { // 注册默认插件 registerDefaultPlugin(new PluginLoader() { @Override public Plugin load(Context context, Context selfContext, Object runtime, Object topLevelScope) { return new PluginHelloWorld(context, selfContext, runtime, topLevelScope); } }); } } ``` 在AndroidManifest.xml中配置以下meta-data, `name`为`"org.autojs.plugin.sdk.registry"`,`value`为MyPluginRegistry的包名。 ```xml ``` #### 3. 编写JavaScript胶水层 在assets的相应目录(由Plugin.getAssetsScriptDir返回)中添加`index.js`文件,用于作为胶水层导出插件API。 ```javascript module.exports = function (plugin) { let runtime = plugin.runtime; let scope = plugin.topLevelScope; function helloworld() { } helloworld.stringFromJava = plugin.getStringFromJava(); helloworld.say = function (message) { plugin.say(message); } return helloworld; } ``` #### 4. 在Auto.js Pro中调用 编译插件为apk(assembleDebug/assembleRelease),安装到设备上。在Auto.js Pro中使用以下代码调用: ```javascript let helloworld = $plugins.load("org.autojs.plugin.sdk.demo"); console.log(helloworld.stringFromJava); helloworld.say("Hello, Auto.js Pro Plugin"); ``` #### 5. 独立服务AIDL方式调用 可以在插件中编写一个`Service`,由Auto.js Pro唤起和绑定,并可在js中通过aidl调用Service的接口。 在Plugin中重写方法`getService`。 ```java // 插件服务类,可选,用于AIDL方式和Auto.js Pro本体通信。可返回null @Override public ComponentName getService() { return new ComponentName(getSelfContext().getPackageName(), HelloworldPluginService.class.getName()); } ``` 新建一个Service组件(**注意在AndroidManifest中注册时需要是exported="true"**),继承于`PluginService`。 ```java public class HelloworldPluginService extends PluginService { private static final String ACTION_ADD = "add"; @Override protected Result onRemoteCall(@NonNull String action, @NonNull Map args, @Nullable RemoteCallback callback) throws RuntimeException { switch (action) { case ACTION_ADD: return invokeAdd(args); } return Result.notImplemented(action); } private Result invokeAdd(Map args) { Number a = PluginUtils.getNotNull(args, "a"); Number b = PluginUtils.getNotNull(args, "b"); double sum = a.doubleValue() + b.doubleValue(); return new Result(Collections.singletonMap("sum", sum)); } } ``` 在index.js中添加胶水层代码: ```javascript helloworld.remoteAdd = function (a, b) { return plugin.waitForConnection().call('add', { a: a, b: b }, null).get('sum'); } ``` 然后可以在Auto.js Pro中调用: ```javascript let helloworld = $plugins.load("org.autojs.plugin.sdk.demo"); console.log(helloworld.remoteAdd(1, 2)); ``` ## OCR插件 目前Auto.js官方仅提供一个简单的OCR插件作为示例,其效率相对较慢,仅为参考。 [OCR插件下载](https://wws.lanzoux.com/iOfyWlpz7jc)(**密码: 4fw3**) ### new OCR([dataFile, lang]) * `dataFile` {string} 数据路径 * `lang` {string} 语言 创建一个新的OCR对象。OCR插件使用Tesseract为引擎。构造函数的dataFile和lang参数用于使用指定的语言模型初始化Tesseract引擎。 数据路径`dataFile`必须是tessdata的父目录的路径,并且必须以/结尾。最后一个/之后的任何路径都将被忽略。 要加载多种语言,例如,`hin + eng`将加载北印度语和英语。 更多信息参见[TessBaseAPI](https://github.com/rmtheis/tess-two/blob/master/tess-two/src/com/googlecode/tesseract/android/TessBaseAPI.java)。 使用自带的中文字库数据初始化OCR: ```javascript let OCR = $plugins.load('org.autojs.plugin.ocr'); let ocr = new OCR(); ``` 使用自己的数据初始化OCR: ```javascript let OCR = $plugins.load('org.autojs.plugin.ocr'); let ocr = new OCR("/sdcard/tessdata/", "chi_sim"); ``` ### OCR.ocrFile(path) * `path` {string} 文件路径 * 返回 [OcrResult](#ocrresult) 对图片文件path进行OCR识别,返回识别后的结果。 ```javascript let OCR = $plugins.load('org.autojs.plugin.ocr'); let ocr = new OCR(); $events.on('exit', () => { ocr.end(); }); let result = ocr.ocrFile($file.path('./image.png')); console.log(result); ``` ### OCR.ocrImage(img) * `img` {Image} Auto.js的图片对象,通过·$images·模块截图或者读取文件返回的对象 * 返回 [OcrResult](#ocrresult) 对图片img进行OCR识别,返回识别后的结果。 ```javascript requestScreenCapture(); let OCR = $plugins.load('org.autojs.plugin.ocr'); let ocr = new OCR(); $events.on('exit', () => { ocr.end(); }); let result = ocr.ocrImage(captureScreen()); console.log(result); ``` ### OCR.ocrScreen() * 返回 [OcrResult](#ocrresult) 截取当前屏幕进行OCR识别,返回识别后的结果。需要先申请截图权限。 ### OCR.ocrBitmap(bitmap) * `bitmap` {Bitmap} android.graphics.Bitmap对象 * 返回 [OcrResult](#ocrresult) 对图片bitmap进行OCR识别,返回识别后的结果。 ### OCR.end() 结束OCR识别,回收相应的OCR对象。 ### OcrResult OCR识别返回的结果,有以下只读属性: * `success` {boolean} 是否识别成功 * `text` {string} 识别文本信息 * `words` {[OcrWord](#ocrword)} 识别文本的列表(java.util.List对象) * `timeRequired` {number} 识别耗时 ### OcrWord OCR识别中的文本。有以下只读属性: * `text` {string} 识别的文本 * `bounds` {Rect} [android.graphics.Rect](https://developer.android.google.cn/reference/android/graphics/Rect)对象,表示文本在图片中的位置和范围 * `confidences` {number} 0~1之间的浮点数,表示结果的可信度,数值越大结果越可靠 ## 第三方插件 参见章节[第三方插件](/zh-cn/thirdPartyPlugins)。