原文:《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 οnclick="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 οnclick="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)