在上一篇文章 cordova 初识之命令行工具 中,我们讲到了如何使用命令行快速地创建我们的 app 应用,并添加和运行各种平台。

在实际的项目开发中,需要用到 cordova 的插件,进行各个不同平台的辅助开发,我们可以通过 plugins.cordova.io 对现有插件的搜索,以及安装。

插件的安装和使用,详细可以通过查阅 Cordova 的官网文档 The Command-Line Interface 以及某前端大大张鑫旭的文章:PhoneGap/Cordova控制iOS7状态栏的显隐/颜色

但是更多的时候,我们需要开发属于我们自己的插件。通过查看官方文档 Plugin Development Guide,你会发现,坑爹啊,这文档怎么还是以前 2.x 的开发文档??自己在编写插件的过程中,花了不少时间,在这里讲一下如何开发属于自己的插件。

通过命令行创建 app 应用之后,你会发现目录结构是这样子的:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
├── platforms
|    ├── android
|    ├── ios
|    ├── wp7
|    └── ...
├── plugins
|    ├── org.apache.cordova.device
|    └── ...
├── config.xml
└── www

这里的 platforms 是我们应用支持的平台目录,plugins 是我们安装的插件目录,config.xml 是应用的配置信息(应用名称、描述等),www 是我们的 web 工程目录。

我们知道,Cordova 3.x 的插件机制改变了,只需要通过简单的命令行即可安装和删除所需要的插件,而我们自己开发的插件,最终是要添加到 plugins 目录中的。

那么,就让一起开始,制作属于我们自己的插件 吧,这里以 ExtraInfo(获取 app 额外信息) 为例子,我们在当前目录下(当然可以放在别的目录下)创建 ExtraInfo 文件夹,先看下具体的目录结构:

1
2
3
4
5
6
7
8
9
ExtraInfo
├── src
|    ├── android
|    |    └── ExtraInfo.java
|    ├── ios
|    └── ...
├── www
|    └── ExtraInfo.js
└── plugin.xml

这里的 src 对应不同的平台,www 放我们的 javascript 文件,plugin.xml 是插件的配置文件。

先来看看 plugin.xml 的内容:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
<?xml version="1.0" encoding="utf-8"?>
<plugin id="cn.net.wenzhixin.cordova" version="0.0.1"
        xmlns="http://apache.org/cordova/ns/plugins/1.0"
        xmlns:android="http://schemas.android.com/apk/res/android">
    <name>ExtraInfo</name>
    <description>Description</description>
    <js-module name="ExtraInfo" src="www/ExtraInfo.js">
        <clobbers target="cordova.plugins.ExtraInfo"/>
    </js-module>
    <platform name="android">
        <config-file parent="/*" target="res/xml/config.xml">
            <feature name="ExtraInfo">
                <param name="android-package" value="cn.net.wenzhixin.cordova.ExtraInfo"/>
            </feature>
        </config-file>
        <source-file src="src/android/ExtraInfo.java" target-dir="src/cn/net/wenzhixin/cordova"/>
    </platform>
</plugin>

有几个关键的字段需要解释下:

  • id: 插件的标识,即发布到 plugins.cordova.io 的 ID
  • name:插件的名称
  • description:描述信息
  • js-module:对应我们的 javascript 文件,src 属性指向 www/ExtraInfo.js
  • platform:支持的平台,这里仅仅用到了 android

    1
    2
    3
    4
    5
    6
    
    <config-file parent="/*" target="res/xml/config.xml">
    <feature name="ExtraInfo">
        <param name="android-package" value="cn.net.wenzhixin.cordova.ExtraInfo"/>
    </feature>
    </config-file>
    <source-file src="src/android/ExtraInfo.java" target-dir="src/cn/net/wenzhixin/cordova"/>

这里是插件的配置信息,最后会添加到 res/xml/config.xml 文件中,并且将我们的 src/android/ExtraInfo.java,复制到 android 的 package 包中。

接下来,ExtraInfo.js 的内容很简单:

1
2
3
4
5
var exec = require('cordova/exec');

exports.getExtra = function(success, error) {
    exec(success, error, "ExtraInfo", "getExtra", []);
};

用过 Nodejs 或者了解过 AMD、CMD 的话(当然,没了解过也没关系),一定会觉得很熟悉。简单的说,require 用于引入我们的类,exports 用于导出我们的方法。这里对外公开了 getExtra 方法,以便我们在 app 中可以用到。

最后看 ExtraInfo.java 的内容:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
public class ExtraInfo extends CordovaPlugin {

    public boolean execute(String action, JSONArray args, CallbackContext callbackContext)
            throws JSONException {
        Activity activity = this.cordova.getActivity();
        if (action.equals("getExtra")) {
            Intent i = activity.getIntent();
            if (i.hasExtra(Intent.EXTRA_TEXT)) {
                callbackContext.success(i.getStringExtra(Intent.EXTRA_TEXT));
            } else {
                callbackContext.error("");
            }
            return true;
        }
        return false;
    }
}

继承了 CordovaPlugin 类,并重写 execute 方法,使用 action 来判断我们在 javascript 中调用的方法名,成功的话调用 callbackContext.success(message),失败调用 callbackContext.error(message) 方法,分别对应 javascript 文件中的 successerror 回调函数。

当然,这里只用到 android 平台,其他的平台也是一样的,ios 使用 object-c、wp7 使用 c# 语言,例子见Plugin Development Guide

到了这里,我们的插件就编写完成了。可以通过下面的命令添加插件:

1
cordova plugin add ExtraInfo #目录名称,也可以是 git 的地址

查看我们的 plugins 目录,会发现在该目录下已经华丽丽地生成我们自己的插件 cn.net.wenzhixin.cordova 了。

对了,好像把最关键的事情给忘记了,这里貌似还没提到我们应该如何在 app 中使用自己的插件呢。前面提到说按照文档来坑爹了,是因为使用 window.getExtra,会报 getExtra is not defined 的错误。

通过查看生成的文件信息,可以知道,应该这样使用我们的插件:

1
2
3
4
5
6
7
8
9
document.addEventListener('deviceready', function() {
    var extraInfo = cordova.require('cn.net.wenzhixin.cordova.ExtraInfo');

    extraInfo.getExtra(function(message) {
        // alert(message);
    }, function(message) {
        // alert(message);
    });
});

最后,像平时的开发,觉得及时更新文档还是比较重要的,虽然自己花了不少时间,不过至少更加明白了 Cordova 插件的原理,同时也希望本文可以帮到你。