[Phonegap+Sencha Touch] 移动开发64 Phonegap/Cordova 插件开发

原文：《Cordova 3.x 基础（12） -- Plugin开发》

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

Plugin的分类大概有两种：

JavaScript-only Plugin：不需要写Native代码，不依赖平台的共通的JS代码
Native Plugin：弥补Cordova提供的功能以外的Native调用，依赖各个平台写不同的Native代码

（1）Plugin构成

文件夹结构：

├ plugin.xml 
├ www 
│    hello_world.js 
└ src 
    ├ android 
    │   com/rensanning/cordova/plugin/HelloWorldPlugin.java 
    └ ios 
         HelloWorldPlugin.h 
         HelloWorldPlugin.m

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

（2）创建JS Plugin

文件夹结构：

sample 
│  plugin.xml 
│ 
└─www 
        hello_world.js

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：

cordova create simplePlugin com.rensanning.cordova.simplePlugin SimplePlugin 
cd simplePlugin 
cordova platform add android 
cordova plugin add E:\plugins\sample

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

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

（3）创建Native Plugin

以Android下获取Carrier Code为例。

文件夹结构：

carrier 
│  plugin.xml 
│ 
├─src 
│  └─android 
│          CarrierPlugin.java 
│ 
└─www 
        carrier.js

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>

***Plugin的js中直接写代码即可，CLI会包装你的代码：

比如：

var HelloWorld = function() {};  
  
HelloWorld.prototype.say = function() {  
    alert("Hello World");  
};  
  
var helloWorld = new HelloWorld();  
module.exports = helloWorld;  

会自动包装为：

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;  
});

参考：

Plugin Development Guide

Plugin Specification（plugin.xml）