Question

如何开发Ionic插件

Answer 1

1. Cordova Plugin基础

1.1. 目录结构层次

IONIC下的插件都是遵循CORDOVA插件([BIBAPACHECORDOVA])规范，同时提供与CORDOVA类似的PLUGIN子命令来管理插件(IONIC PLUGIN XXX)。
下面是插件管理命令中的添加、删除及列举等基本使用方法：

$ ionic plugin list

cordova-plugin-camera 1.2.0 "Camera"

cordova-plugin-console 1.0.1 "Console"

cordova-plugin-device 1.0.1 "Device"

cordova-plugin-splashscreen 2.1.0 "Splashscreen"

cordova-plugin-statusbar 1.0.1 "StatusBar"

cordova-plugin-whitelist 1.0.0 "Whitelist"

ionic-plugin-keyboard 1.0.7 "Keyboard"

plugin-mydemo 1.0.0 "MyDemo"

添加(add)一个插件的时候，若指定的是本地的路径，则是将本地路径下的目录文件copy到plugins/下。若是插件名，则会自动连接到网上下载对应的插件。

由于插件是遵循Cordova插件规范，所以每个插件的代码目录层次结构都是高度类似的。每一个插件都是plugins/的一个子目录，Figure-1描述了插件共同的基本目录结构框架。

Figure 1. 插件的目录结构

从图中可以看出，插件框架中将不同平台的实现代码都放在各自不同的目录下(android/ios)，通过ionic统一生成各自对应平台的应用程序。

为了方便管理plugins/下多个插件，通常在plugins/下会有一个总的管理文件，比如编译android平台的时候，会有一个android.json文件，里面放着当前插件的简单信息。

当用户使用ionic plugin add/remove命令来添加、删除插件的时候，android.json也会自动的把相应插件定义条目添加或者删除掉。

1.2. 插件工作原理分析

上一节我们已经清楚了一个插件的代码目录结构，那么一个插件是如何正确地在IONIC框架下运行的呢? 前台的HTML/JS代码又是如何与后面具体平台做数据交互的呢?
这个就需要对插件的工作原理及各个模块之间的流程关系有一个基本的了解[1]

为了让插件能够访问具体平台系统的代码，Cordova提供了对应的标准封装API来完成，下面的图简单地示意了Android平台情况下的封装过程：

Figure 2. 插件封装调用图

当用户ionic
build
android进行第一次编译的时候，会自动将插件下的Java文件copy到platform/android/目录下面，同时将JS也copy到platform/android/目录下，最终使用Android的编译工具(aapt/aidl/dx/apkbuilder等)生成.APK应用程序。

这里需要注意的是，插件中的Java文件默认下只会在第一次编译的时候自动放到platform/android/，之后即使用户修改了插件目录下面的Java文件，编译的时候仍然是使用platform/android/下的Java文件。

解决的方法可以是在编写自己插件调试的时候，在platform/android/下建立一个symbol link, 指向插件中的Java文件。

这样可以保证修改的Java文件会参加编译。

1.3. 数据的交互

从\REF{SECIONICPLUGINFLOW}节我们已经清楚JS和ANDROID平台之间分别通过JS的CORDOVA.EXEC()和JAVA的CORDOVAPLUGIN.EXECUTE()函数来对接。
这两个接口的参数对应关系如下所示：

由于JS发送到Java的数据已经作为函数的参数传入, 所以函数中的回调参数，主要是帮助Java侧反馈数据给JS侧所用。

Cordova使用了org.apache.cordova.PluginResult来完成，当中的PluginResult.Staus代表JS调用插件成功与否的状态。

通常代码中判断状态值是否为PluginResult.Staus.OK，来确认调用结果成果或者失败

2. 制作插件
实际工作中，我们往往需要自己编写满足自己项目需求的插件。这里将逐步介绍编写插件的步骤和注意事项。

2.1. PLUGMAN

也许IONIC的框架编写者觉得JS开发人员只要会怎么调用和删除插件就足够了。
所以默认下，ionic的plugin子命令，只是给JS开发者来add/remove编写好的插件。它并没有, 也不提供start/create等类似的生成插件代码框架的功能选项。

若我们需要自己编写自己的插件，则可以使用额外的一个叫做plugman的工具[2], 该工具可直接通过npm来安装。

安装成功后，就可以使用plugman命令来自动生成插件代码框架，避免手工建立和输入代码文件的工作：

$ sudo npm install -g plugman

$ plugman create --name plugin-myspeech --plugin_version 0.1 --plugin_id org.foo

$ cd plugin-myspeech

$ plugman platform add --platform_name android

上述命令将会生成一个plugin-myspeech的目录，同时会自动生成plugin.xml、src以及www目录。

当使用platform add添加完android支持后，对应的Android Java代码框架也会自动生成。

同理，plugman platform add --platform_name ios添加iOS支持后，和iOS相关的代码框架也自动生成。

2.2. 编写插件

这里介绍一个自己写的ANDROID平台下的简单PLUGIN，演示前台到后面具体平台实现的流程。
插件本身逻辑非常简单: 得到JS请求后，把当前手机的Android系统的版本信息，并发送回前端。

通过plugman命令生成基本插件代码框架：

$ plugman create --name MyDemo --plugin_version 0.1 --plugin_id org.ioniconline

$ cd MyDemo

$ plugman platform add --platform_name android

自动生成的代码框架中，定义了coolMethod方法，我们可以在Java代码中处理该请求

public class MyDemo extends CordovaPlugin {

public boolean execute() {

if (action.equals("coolMethod")) {

Log.e("MyDemo", "process the req");

String str = android.os.Build.VERSION.RELEASE;

PluginResult r = new PluginResult(PluginResult.Status.OK, str);

r.setKeepCallback(true);

callbackContext.sendPluginResult(r);

return true;

}

return false;

}

}

至此，一个插件的功能已经完成。

接下来我们在自己的ionic应用中添加该插件。用户可以指定自己刚刚编写的控件文件目录位置。该示例插件已经存放在github上，所以可以从github上直接添加：

$ ionic plugin add https://github.com/yangsongx/MyDemo
这样会在当前应用的plugins目录下生成org.ioniconline目录，里面放的就是前面编写的插件代码。

在需要调用Android接口的地方加上JS代码：

function getVersion() {

cordova.plugins.MyDemo.coolMethod('useless',

function(okData) {

alert(okData);

},

function(failData) {

alert(failData);

});

}

成功情况下，会弹出包含Android系统版本号数据的对话框。比如在我华为P7上返回的是4.4.2

Figure-\ref{figIOnicMyDemo}演示了整个代码在各个模块间的调用关系。完整的MyDemo的插件代码可以从github[3]上得到。

Figure 3. MyDemo插件逻辑流程

每个Plugin需要输出(export)的接口都需要使用module.exports的命令来完成。

var myApis = {};

myApis.foo1 = function(a,b) {

cordova.exec(...);

};

myApis.foo2 = function(a,b,c) {

cordova.exec(...);

};

MODULE.EXPORTS = MYAPIS;
2.3. 注意事项

不要直接修改Plugin中的Java代码，这个代码不参与编译。

原因： 第一次编译目标应用时，ionic会将Plugin中的Java代码copy到platform/下编译。但下次再进行编译的时候不会在copyrJava代码，所以参加编译的实际上只是platform/下的Java代码。

plugin中的js可以直接修改，而且每次重新编译都参加编译。

原因： ionic下的JS是在Cordova上封装了一层，所以每次编译，需要将ionic下的JS转换成Cordova JS才能正确工作

使用exec()中的service参数必需和插件plugin.xml中的featur定义的一致，否则会有class not found错误

报method not found异常, 插件中的js脚本未正确地使用module.exports声明

Further Reading