手把手教你 cordova plugin 环境搭建和开发

本文主要讲解在 Ionic 环境下搭建一个 cordova plugin 的开发环境，以开发一个最简单的Echo插件为例：

创建一个 ionic 新项目

ionic start echo blank

添加插件目录结构

cd echo/plugins

mkdir com.citicbzh.echo

cd com.citicbzh.echo

mkdir -p src/android

mkdir www

添加 Java 类

在 echo/plugins/com.citicbzh.echo/src/android 下建立 Echo.java 文件，内容如下：

	package com.citicbzh.echo;

	import org.apache.cordova.CallbackContext;
	import org.apache.cordova.CordovaPlugin;
	import org.json.JSONArray;
	import org.json.JSONException;

	import java.lang.Override;

	public class Echo extends CordovaPlugin {

		@Override
		public boolean execute(String action, JSONArray args, CallbackContext cc) throws JSONException {
    		if ("greetAction".equals(action)) {
        		String name = args.getString(0);
        		cc.success("Hello, " + name);
        		return true;
    		} else {
        		return false;
    		}
		}

	}

要点：

插件需要继承 CordovaPlugin 类
覆写 execute 方法，通过回调函数 cc 传回返回值

添加插件 web 接口

在 echo/plugins/com.citicbzh.echo/www 下建立 echo.js 文件，内容如下：

	module.exports = {

		greet: function(name, cb, error) {
    		cordova.exec(cb, error, 'Echo', 'greetAction', [name]);
		}

	};

要点：

包管理方法 module / exports 等由 cordova 提供，无需自行定义
调用 cordova 插件的 Java 方法，统一使用 cordova.exec 方法，五个参数分别是：成功回调函数、失败回调函数、插件名称、动作名称、调用参数数组。

配置 plugin.xml

在 echo/plugins/com.citicbzh.echo 下建立 plugin.xml 文件，内容如下：

    <?xml version="1.0" encoding="UTF-8"?>
    
    <plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
        id="com.citicbzh.echo"
        version="1.0.0">
        <name>Echo</name>
        <description>Echo and Greeting</description>
        <license>Apache 2.0</license>
        <keywords>Echo</keywords>
    
        <js-module src="www/echo.js" name="Echo">
            <clobbers target="echo" />
        </js-module>
    
        <!-- android -->
        <platform name="android">
            <config-file target="res/xml/config.xml" parent="/*">
                <feature name="Echo">
                    <param name="android-package" value="com.citicbzh.echo.Echo" />
                </feature>
            </config-file>
            <source-file src="src/android/Echo.java" target-dir="src/com/citicbzh/echo" />
        </platform>
    
    </plugin>

要点：

js-module 中的 clobbers 指定 cordova 插件通过什么接口曝露给 JavaScript，令 target 为 echo，则 JavaScript 可通过 window.echo 调用插件。
config-file 中的 feature 节点会被拷贝到 config.xml 中去，实际不是 plugin.xml 的一部分。
plugin.xml 配置实际远不止这些，详细文档见：https://cordova.apache.org/docs/en/3.4.0/plugin_ref_spec.md.html#Plugin%20Specification

添加 web 页面调用

在 echo/www/index.html 文件中添加对 cordova 插件的引用

	<script src="cordova.js"></script>
	<!-- 注意放的位置 -->
	<script src="cordova_plugins.js"></script>

在 echo/www/js/app.js 文件中调用 echo 插件（注意放在 $ionicPlatform.ready 函数中）

	window.echo.greet('LAIKUN', function(reply) {
        alert(reply);
    });

添加 cordova platform & 编译 & 运行

	cordova platform add android
	ionic build android
	ionic run android

本文只是粗略介绍，详细内容请参考 cordova 官方文档：

Android Plugins https://cordova.apache.org/docs/en/3.4.0/guide_platforms_android_plugin.md.html#Android%20Plugins

Plugin Development Guide https://cordova.apache.org/docs/en/3.4.0/guide_hybrid_plugins_index.md.html#Plugin%20Development%20Guide

caseylai/手把手教你cordova环境搭建和开发.md