10、Android 插件开发（基础知识）

Android 插件开发

原文地址

Android Plugins

本节提供了如何实现Android平台上的本机插件代码的详细信息。阅读此之前，请参阅应用程序插件的结构及其JavaScript接口的概述。webview与原生平台和后台的交互。另外也可以在CordovaPlugin.java（链接）中获得更多信息。

Android插件基于由android的webview来联系的Cordova-Android系统。插件被config.xml文件中的类映射来表示。插件包括一个继承自CordovaPlugin类，并重写其execute方法的java类。作为最佳实践，该插件还应该处理[暂停]（../../../cordova/events/events.pause.html）和[恢复]（../../../cordova/events/events.resume.html）事件，在插件之间传递任何消息一起。长时间运行的请求，后台活动，如媒体播放功能，监听器，或读取内部状态的插件应该同时实现onReset()方法。它会在WebView打开新页面或刷新，即重新加载的JavaScript时执行。

插件类映射

插件的JavaScript方法使用cordova.exec方法的示例如下：

exec(<successFunction>, <failFunction>, <service>, <action>, [<args>]);

这个方法可以从WebView中发起一个请求到Android原生端，然后有效的调用service类中的方法，同时可以传递一个名字如上例的args的数组参数。
无论您是否将插件如Java文件或作为自身的一个jar文件分发，该插件必须Cordova-Android应用程序的res/xml/ config.xml文件中指定。请参阅应用插件如何使用plugin.xml文件注入此功能元素的详细信息：

<featurename="<service_name>"><paramname="android-package"value="<full_name_including_namespace>" /></feature>

上面的service_name是JavaScript exec方法调用的service名。其中的参数值是Java类的命名空间标识。否则，插件可能编译，但仍然无法在Cordova中使用。

插件初始化和生命周期

插件对象的生命周期和对应的WebView相同。但是插件只有在第一次被JavaScript调用应用的时候才会实例化，另外我们也可以在config.xml中设置onload元素为true来实例化。例如：

<featurename="Echo"><paramname="android-package"value="<full_name_including_namespace>" /><paramname="onload"value="true" /></feature>

当设置onload为true时，插件应该使用自己的启动逻辑initialize方法。

@Overridepublic void initialize(CordovaInterface cordova, CordovaWebView webView) {       super.initialize(cordova, webView);       // your init code here   }

写一个Android的Java插件

一个JavaScript方法完成一个到原生端的插件请求，并且对应的java插件类在config.xml文件中正确映射，但是真正的Android Java Plugin类长啥样呢。最终的JavaScript的exec方法执行后都会传递到插件类中的execute方法。大部分的execute方法的实现就像下面的样子：

@Overridepublic boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {      if ("beep".equals(action)) {            this.beep(args.getLong(0));            callbackContext.success();            returntrue;      }      returnfalse;  // Returning false results in a "MethodNotFound" error.   }

JavaScript的执行函数action参数对应一个类的私有方法。当捕捉异常并返回错误，这是为清楚起见重要的错误恢复到比赛的JavaScript Java的异常名称尽可能。
当捕获到异常并且返回错误，很重要的一点是尽可能的保证错误返回到与JavaScript匹配的java错误名的类。

Threading

插件的JavaScript不在webview界面的主线程中运行，而是在WebCore线程中调用execute方法。如果需要与用户交互，你应该使用以下方式：

@Overridepublic boolean execute(String action, JSONArray args, final CallbackContext callbackContext) throws JSONException {        if ("beep".equals(action)) {            finallong duration = args.getLong(0);            cordova.getActivity().runOnUiThread(new Runnable() {                publicvoidrun() {                    ...                    callbackContext.success(); // Thread-safe.                }            });            returntrue;        }        returnfalse;    }

如果你不需要在主界面线程运行，但使用WebCore线程，使用下面的方式：

@Overridepublic boolean execute(String action, JSONArray args, final CallbackContext callbackContext) throws JSONException {        if ("beep".equals(action)) {            finallong duration = args.getLong(0);            cordova.getThreadPool().execute(new Runnable() {                publicvoidrun() {                    ...                    callbackContext.success(); // Thread-safe.                }            });            returntrue;        }        returnfalse;    }

添加依赖库

如果一个插件需要额外的库工作，您可以使用以下方法之一通过config.xml中添加它们：
方案A：通过gradle引用，例如：

<frameworksrc="com.android.support:support-v4:+" />

这是推荐的方法，因为它允许多个插件来指代相同的依赖库，如gson，android-support-V4，google-play-services等，并且这样的话gradle将利用其依赖管理逻辑解决重复的依赖关系。
方案B：作为放置一些plugins文件夹的JAR文件，并使用LIB文件，例如：

<lib-filesrc="src/android/libs/gcm.jar"/>

我们建议仅当您确定相关性JAR插件是具体的，不会被其他插件使用时使用此方法，否则，就会出现平台的构建问题。

名为Echo的Android插件列子

要匹配的JavaScript接口的echo插件在应用中描述的功能，使用plugin.xml中注入一个功能规范本地平台的config.xml文件中：

<platform name="android">        <config-file target="config.xml" parent="/*">            <feature name="Echo">                <param name="android-package" value="org.apache.cordova.plugin.Echo"/>            </feature>        </config-file>    </platform>

然后添加以下内容到src/org/apache/cordova/plugin/Echo.java文件中：

package org.apache.cordova.plugin;    import org.apache.cordova.CordovaPlugin;    import org.apache.cordova.CallbackContext;    import org.json.JSONArray;    import org.json.JSONException;    import org.json.JSONObject;    public class EchoextendsCordovaPlugin {   @Override    public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {            if (action.equals("echo")) {                String message = args.getString(0);                this.echo(message, callbackContext);                returntrue;            }            returnfalse;        }        private void echo(String message, CallbackContext callbackContext) {            if (message != null && message.length() > 0) {                callbackContext.success(message);            } else {                callbackContext.error("Expected one non-empty string argument.");            }        }    }

很必要的部分是在继承自CordovaPlugin类的java类中重写execute()方法来接收来自exec()的消息。execute()方法首先会检测action的值，然后根据action的值来判断调用那个方法（上面例子中是传递的echo，就会调用到echo方法）。任何不存在的方法都会返回false并且导致一个INVALID_ACTION的错误，此时就会调用到JavaScript端的error callback方法。
接下来，方法检索传递的参数，使用的是args对象的getString方法，指定第一个传递到方法的参数。当参数值传递到私有的echo方法之后，有一个参数检测方法来判断是否是空指针或者空字符串，如果出现空指针或者空字符串就会进到else中调用callbackContext.error()方法激活JavaScript的error callback方法。如果参数验证通过，则会调用callbackContext.success()方法将原来的message参数的值作为参数传递到JavaScript的success callback中

android的整合

android有个可以允许线程间通信的Intent系统。插件有权访问可以访问运行该应用程序在Android活动的CordovaInterface对象。这是推出一个新的Android Intent所需的上下文。所述CordovaInterface允许插件启动一个Activity，并为Intent返回到应用程序设置回调插件。
在Cordova 2.0中，插件不再允许直接访问Context,并且传统的ctx成员也被反对。所有的ctx方法存在在Context中，所以
getContext()和getActivity方法可以返回所需对象。

Android权限

Android权限直到最近仍被处理为安装时授权而不是运行时。要使用权限需要在应用中声明使用的权限，并且权限声明要被加入到Android Manifest文件中。这里我们可以通过使用config.xml中注入在AndroidManifest.xml文件中这些权限来完成。例子如下（读取联系人权限声明）：

<config-filetarget="AndroidManifest.xml"parent="/*"><uses-permissionandroid:name="android.permission.READ_CONTACTS" /></config-file>

Android权限（针对Cordova-Android-5.0.x以及更高版本）

Android 6.0 “Marshmallow”退出了新的权限模型，使得用户可以在必要时打开和关闭权限。因此Cordova-Android 5.0的重点就是用面向未来的方式来处理权限。
需要在运行时处理的权限可以在Android开发者文档中找到。
至于插件而言，权限可以通过调用权限的方法，它的签名如下要求：

   cordova.requestPermission(CordovaPlugin plugin, int requestCode, String permission);

为了减少冗长，其标准的做法，这种分配到本地静态变量方式：

public static final String READ = Manifest.permission.READ_CONTACTS;

这也是标准的定义请求代码的做法，如下：

public static final int SEARCH_REQ_CODE = 0;

然后，在exec方法，应该检查权限：

if(cordova.hasPermission(READ)) {        search(executeArgs);   } else {     getReadPermission(SEARCH_REQ_CODE);   }

在这种情况下，我们只需要如下方式获取请求许可：

protected void getReadPermission(int requestCode)   {       cordova.requestPermission(this, requestCode, READ);   }

这将调用activity，并导致一个提示出现要求的权限。一旦用户允许使用权限，结果必须用每一个插件应该重写的onRequestPermissionsResult方法处理。这方面的例子如下：

public void onRequestPermissionResult(int requestCode, String[] permissions,int[] grantResults) throws JSONException   {       for(int r:grantResults)       {           if(r == PackageManager.PERMISSION_DENIED)           {               this.callbackContext.sendPluginResult(new PluginResult(PluginResult.Status.ERROR, PERMISSION_DENIED_ERROR));               return;           }       }       switch(requestCode)       {           case SEARCH_REQ_CODE:               search(executeArgs);               break;           case SAVE_REQ_CODE:               save(executeArgs);               break;           case REMOVE_REQ_CODE:               remove(executeArgs);               break;       }   }

switch语句将根据提示返回的requestCode判断，然后调用case中的方法。应当指出的是如果执行不正确的处理请求权限的提示可堆叠，这一点应被避免。
除了要求用于单个权限许可，但也可以通过定义权限数组，就像下面这个地理位置插件完成请求权限的整个组的例子：

   String [] permissions = { Manifest.permission.ACCESS_COARSE_LOCATION, Manifest.permission.ACCESS_FINE_LOCATION };

然后请求许可时，所有需要做的是以下方式：

 cordova.requestPermissions(this, 0, permissions);

这就要求数组中指定所需的权限。这是一个提供可公开访问的权限的数组的好主意，因为这可以使插件作为依赖插件使用，虽然这不是必需的。

调试Android插件

Android的调试可以使用Eclipse或Android Studio来完成，虽然推荐使用Android Studio。由于Cordova-Android是目前作为一个开源项目和插件都支持源代码预览，就可以像调试一个原生的Android应用程序一样调试Cordova应用程序内的Java代码。

启动外部Activity

在你得插件想要将Cordova放到后台然后启动新的Activity时，你需要一些特殊的考虑。当Android系统的内存过低时，就会将后台的Activity杀死。这种情况下，Cordova插件的实例也会被销毁。如果你的插件正在等待他打开的活动的结果，随着Cordova Activity被以前台方式调起，一个插件的新实例将会被创建，结果也会被获取到。然而，插件的状态不会自动保存和恢复,这样该插件的CallbackContext将会丢失。所以这里为你的Cordova插件提供了两种方式来处理这两种情况：

/**    * Called when the Activity is being destroyed (e.g. if a plugin calls out to an    * external Activity and the OS kills the CordovaActivity in the background).    * The plugin should save its state in this method only if it is awaiting the    * result of an external Activity and needs to preserve some information so as    * to handle that result; onRestoreStateForActivityResult() will only be called    * if the plugin is the recipient of an Activity result    *    * @return  Bundle containing the state of the plugin or null if state does not    *          need to be saved    */public Bundle onSaveInstanceState() {}   /**    * Called when a plugin is the recipient of an Activity result after the    * CordovaActivity has been destroyed. The Bundle will be the same as the one    * the plugin returned in onSaveInstanceState()    *    * @param state             Bundle containing the state of the plugin    * @param callbackContext   Replacement Context to return the plugin result to    */publicvoidonRestoreStateForActivityResult(Bundle state, CallbackContext callbackContext) {}

需要注意的是，如果你的插件启动了一个Activity，这样的话存储必要的状态来处理Activity结果是很重要的。如果Cordova Activity被系统后台杀死，插件的状态也不会保存，除非在你的插件使用CordovaInterface的startActivityForResult（）方法。
作为onRestoreStateForActivityResult（）的一部分，你的插件将被传递一个替换的CallbackContext。要判断出这个CallbackContext是不是与Activity被破坏的时候是同一个非常重要。原始回调已经丢失，并且将不会在JavaScript应用被除去。相对的，这种替换的CallbackContext将随着应用程序的恢复而作为resume的一部分恢复并返回结果。恢复事件的负载遵循以下结构：

{       action: "resume",       pendingResult: {           pluginServiceName: string,           pluginStatus: string,           result: any       }   }

pluginServiceName:将从您的plugin.xml匹配的name属性
pluginStatus:将描述传递给CallbackContext的PluginResult状态的字符串。见PluginResult.java的对应插件状态的字符串值
result:将是插件传递什么结果给CallbackContext（例如字符串，数字，JSON对象等）
这个resume的有效参数将被传递到了JavaScript应用已经注册了resume事件的任何回调。这意味着该结果被直接到Cordova应用申请;你的插件将没有机会应用程序接收之前用JavaScript来处理结果。因此，你应该努力使由原生代码尽可能在开启activity时不依赖于任何JavaScript回调返回的结果。
一定要明确Cordova应用程序应该如何理解他们在resume事件接受的结果。它是为了Cordova应用程序保持自己的状态，并记住他们要做什么，如果有必要的话还有他们提供什么样的参数。不过，你还是应该清楚地传达pluginStatus值的含义，并明确被返回的作为你的插件API的一部分的结果集的数据的顺序。
启动一个活动的事件的完整序列如下：
1、Cordova应用对你的插件发起一个请求
2、你的插件启动了一个新的Activity。
3、Adnroid系统销毁Cordova Activity，然后你插件的onSaveInstanceState()方法被调用
4、用户与Activity互动的Activity结束
5、Crodova Activity被重新创建，然后活动结果被接收onRestoreStateForActivityResult()方法被调用。
6、onActivityResult()被调用，并且你的插件传递了一个结果到新的CallbackContext
7、resume事件被触发，并且被Cordova application接收。
Android为开发者提供了调试Activity被破坏的低内存调试模式。启用您的设备或模拟器上的开发人员选项菜单中的“不保留活动”设置模拟内存不足的情况。如果你的插件需要启动的外部Activity，你应该总是做一些测试与启用此设置，以确保你正确地处理内存不足的情况。