Cordova 3.x 基础（12） -- Plugin开发

Cordova提供的功能能够满足一般应用，但是对于复杂的应用或者对性能要求比较严格的应用来说，并不是很理想的。所以就需要在某些场景下自己写代码来弥补这些不足，类似Titanium Module一样，Cordova也提供了Plugin功能。Cordova本身访问Native接口都是通过Plugin的方式提供的，可以参考官方Plugin代码，而且GitHub上也存在不少开源的Cordova Plugin，所以这些都是最好的教程。

[b]Plugin的分类大概有两种：[/b]
[list]
[*]JavaScript-only Plugin：不需要写Native代码，不依赖平台的共通的JS代码
[*]Native Plugin：弥补Cordova提供的功能以外的Native调用，依赖各个平台写不同的Native代码
[/list]

[b]（1）Plugin构成[/b]
[quote]|- plugin.xml
|- www
| +- hello_world.js
+- src
|- android
| +- com/rensanning/cordova/plugin/HelloWorldPlugin.java
+- ios
|- HelloWorldPlugin.h
+- HelloWorldPlugin.m[/quote]

[b]plugin.xml[/b] ： 必须。通知CLI哪个平台应该从什么地方Copy哪些文件到什么地方，以及CLI在生成config.xml时应该根据平台加入什么样的特殊设置。
[b]JavaScript文件[/b] : 必须。一个Plugin至少应该有一个JS文件，也可以引入其他的lib（比如：handlebars.js），定义为js-module，会被cordova.js会自动读入。
[b]原生代码[/b] ：可选。
[b]静态文件[/b] ： 可选。HTML、图像等

其中plugin.xml文件配置如下：

<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
    xmlns:rim="http://www.blackberry.com/ns/widgets"
    xmlns:android="http://schemas.android.com/apk/res/android"
    id="org.apache.cordova.device"
    version="0.2.8">
    <name>Device</name>
    <description>Cordova Device Plugin</description>
    <license>Apache 2.0</license>
    <keywords>cordova,device</keywords>
    <repo>https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git</repo>
    <issue>https://issues.apache.org/jira/browse/CB/component/12320648</issue>

    <js-module src="www/device.js" name="device">
        <clobbers target="device" />
    </js-module>

    <!-- android -->
    <platform name="android">
        <config-file target="res/xml/config.xml" parent="/*">
            <feature name="Device" >
                <param name="android-package" value="org.apache.cordova.device.Device"/>
            </feature>
        </config-file>

        <source-file src="src/android/Device.java" target-dir="src/org/apache/cordova/device" />
    </platform>

    <!-- 其他平台的代码 -->
</plugin>

plugin -- 命名空间、ID、版本
name -- 名称
description -- 描述
keywords -- 关键字
engines -- Cordova版本
js-module -- js文件地址，会被默认加载到首页面（index.html），通过clobbers元素的定义把就是的module.exports自定赋给window对象。
platform -- 各个平台设置

[b]（2）创建JS Plugin[/b]
文件夹结构：
[quote]sample
│ plugin.xml
│
└─www
hello_world.js[/quote]

plugin.xml：

<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
    id="com.rensanning.cordova.helloworld"
    version="0.0.1">
    <name>HelloWorldPlugin</name>
    <description>HelloWorldPlugin Description</description>
    <author>rensanning</author>
    <license>Apache 2.0 License</license>
    <engines>
        <engine name="cordova" version=">=3.0.0" />
    </engines>
    <js-module src="www/hello_world.js" name="helloworld">
        <clobbers target="HelloWorld" />
    </js-module>
</plugin>

hello_world.js：

var HelloWorld = function() {};

HelloWorld.prototype.say = function() {
    alert("Hello World");
};

var helloWorld = new HelloWorld();
module.exports = helloWorld;

创建工程测试Plugin：
[quote]cordova create simplePlugin com.rensanning.cordova.simplePlugin SimplePlugin
cd simplePlugin
cordova platform add android
cordova plugin add E:\plugins\sample[/quote]

修改index.html后启动测试即可。

<button onclick="test();">Click me!</button>
<script type="text/javascript">
  function test() {
      HelloWorld.say();
  }
</script>

[img]http://dl2.iteye.com/upload/attachment/0094/7163/23916c43-a9ff-39d8-badf-00e0d80e5059.png[/img]

[b]（3）创建Native Plugin[/b]
以Android下获取Carrier Code为例。
文件夹结构：
[quote]carrier
│ plugin.xml
│
├─src
│ └─android
│ CarrierPlugin.java
│
└─www
carrier.js[/quote]

plugin.xml：

<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
    id="com.rensanning.cordova.carrier"
    version="0.0.1">
    <name>CarrierPlugin</name>
    <description>CarrierPlugin Description</description>
    <author>rensanning</author>
    <license>Apache 2.0 License</license>
    <engines>
        <engine name="cordova" version=">=3.0.0" />
    </engines>
    <js-module src="www/carrier.js" name="carrier">
        <clobbers target="Carrier" />
    </js-module>
    <platform name="android">
        <source-file src="src/android/CarrierPlugin.java" target-dir="src/com/rensanning/cordova/carrier" />
        <config-file target="res/xml/config.xml" parent="/*">
            <feature name="CarrierPlugin">
                <param name="android-package" value="com.rensanning.cordova.carrier.CarrierPlugin"/>
            </feature>
        </config-file>
        <config-file target="AndroidManifest.xml" parent="/*">
            <uses-permission android:name="android.permission.READ_PHONE_STATE" />
        </config-file>
    </platform>
</plugin>

CarrierPlugin.java：

public class CarrierPlugin extends CordovaPlugin {
	public static final String TAG = "CarrierPlugin";
	public static final String ACTION_GET_CARRIER_CODE = "getCarrierCode";
	public TelephonyManager tm;

	public void initialize(CordovaInterface cordova, CordovaWebView webView) {
		super.initialize(cordova, webView);
		Context context = this.cordova.getActivity().getApplicationContext();
		tm = (TelephonyManager) context.getSystemService(Context.TELEPHONY_SERVICE);
	}

	@Override
	public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {
		if (ACTION_GET_CARRIER_CODE.equals(action)) {
			String carrier = tm.getSimCountryIso();
			Log.d(TAG, carrier);
			callbackContext.success(carrier);
			return true;
		}
		return true;
	}
}

carrier.js：

var cordova = require('cordova');

var Carrier = function() {};

Carrier.prototype.getCarrierCode = function(success, error) {
    cordova.exec(success, error, 'CarrierPlugin', 'getCarrierCode', []);
};

var carrier = new Carrier();
module.exports = carrier;

修改index.html后启动测试即可。

<button onclick="test2();">Carrier Code!</button>
<script type="text/javascript">
  function test2() {
    Carrier.getCarrierCode(onSuccess, onFailure);
  }
  function onSuccess(result) {
    alert("Result: " + result);
  }
  function onFailure(err) {
    alert("Failure: " + err);
  }
</script>

[img]http://dl2.iteye.com/upload/attachment/0094/7165/0e52bf08-91bb-3030-a065-e3a4e799f5d8.png[/img]

[color=red]***Cordova device APIs从Cordova 3.0开始全Plugin的机制稍有变化，默认都不可用，需要什么添加什么：[/color]
[img]http://dl2.iteye.com/upload/attachment/0094/7169/6a2a0477-1855-3746-9c77-be289789caad.png[/img]
Plugin的添加和删除也同时提供两种方式： Cordova CLI、Plugman。
但是不同的是Plugman一次只能为一个platform添加Plugin，而Cordova CLI是为所有平台都添加Plugin。
Cordova CLI内部实际上也是调用的Plugman。

安装plugman
[quote]npm install plugman -g
plugman -v
plugman help[/quote]
添加Plugin
[quote]plugman --platform android --project <directory> --plugin <name|url|path> [--plugins_dir <directory>] [--www <directory>] [--variable <name>=<value>][/quote]
删除Plugin
[quote]plugman --uninstall --platform android --project <directory> --plugin <id> [--www <directory>] [--plugins_dir <directory>][/quote]

详细参考：[url=https://github.com/apache/cordova-plugman/]https://github.com/apache/cordova-plugman/[/url]
Cordova Plugin Registry有以下两个：[url=http://plugins.cordova.io/]http://plugins.cordova.io/[/url]、[url=http://plugreg.com/plugins]http://plugreg.com/plugins[/url]

[color=red]***Plugin的js中直接写代码即可，CLI会包装你的代码：[/color]
比如：

cordova.define("com.rensanning.cordova.helloworld.helloworld", function(require, exports, module) { var HelloWorld = function() {};

HelloWorld.prototype.say = function() {
    alert("Hello World");
};

var helloWorld = new HelloWorld();
module.exports = helloWorld;
});

参考：
[url=http://cordova.apache.org/docs/en/3.4.0/guide_hybrid_plugins_index.md.html#Plugin%20Development%20Guide]Plugin Development Guide[/url]
[url=http://cordova.apache.org/docs/en/3.4.0/plugin_ref_spec.md.html#Plugin%20Specification]Plugin Specification（plugin.xml）[/url]