如何为Android写一个PhoneGap插件

在此教程中，你将学会如何为Android写一个自定义的插件，然后再PhoneGap应用中使用，此教程包含如下：
   •如果写一个自定义PhoneGap插件来添加一个到自己Android设备的本地日历接口
   •如何用Javascript和原生Java实现插件的功能
   •如何使用新的PhoneGap CLI来创建一个相同基类的应用并运行它
   •如何配置和测试有相同插件的案例应用
   可以在我的github账号里得到最终的工作项目，链接在这里：
   https://github.com/hollyschinsky/CalendarPluginSample
   幻灯片里的第一部分跟此指引和代码都能提供额外的细节。
概述
   PhoneGap通过开放源代码来允许你添加自己定制的功能来扩展当前PhoneGap的功能。插件可以通过JS和本地源码的桥接进行通信。对Android来说，需要使
用Java编写自己的本地插件代码，对iOS来说则需要使用Object-C来编写。PhoneGap的全部API都是用相同的模式创建的。此教程集中将为Android开发插件。
   在容器里，调用JS的cordova.exec()方法来直接映射本地插件Java类里的execute()方法，当然需要传入包括成功和错误的回调函数。
Android和iOS的桥接实现还是有所差距的。在Java里，对象对WebView是可访问的，而在iOS里，则需要通过一个带自定义模式的由本地Object-C翻译的
源://xyz的URL来实现。虽然跟你的插件开发没关系，但是值得一提。
第一部分：编写本地Java接口
   首先我们编写本地代码来添加日历入口到Android设备上，这样我们就能准确控制JS接口边需要的参数了。
   1.打开你熟悉的编辑器，定义一个CalenderPlugin.java的类，此类继承CordovaPlugin类.

1. public class CalendarPlugin extends CordovaPlugin { }

复制代码

   然后定义一个静态变量来定义插件类的addCalenderyEntry动作。这是我们从JS端传入用来添加日历入口的动作执行。可想而知，多个插件会有多个动作来
执行类似的操作。例如你可以为了以后需要，再添加编辑和删除日历的入口。添加下面的静态变量到CalendarPlugin类。结果如下：

1. public class CalendarPlugin extends CordovaPlugin { public static final String ACTION_ADD_CALENDAR_ENTRY = "addCalendarEntry"; }

复制代码

   还是在CalendarPlugin.java里，添加下面的execute函数。此方法是从CordovaPlugin类继承得到，因此我们需要添加override标记：

1. @Overridepublic boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException { }

复制代码

   之后需要添加必须的导入类，再为CalenderPlugin.java添加一个包名。需要注意的是，除了CordovaPlugin类外我们还需要导入cordova的CallbackContext来发送成功或者错误信息，也需要JSON类来处理传入的参数。在CalenderPlug.java类的顶部添加如下代码：

1. package com.example.myplugin; import org.apache.cordova.api.CallbackContext; import org.apache.cordova.api.CordovaPlugin; import org.json.JSONObject; import org.json.JSONArray; import org.json.JSONException;

复制代码

   在execute()函数里，添加代码来检测传入的动作，然后使用本地Android代码提供的的Intent和Activity类来添加日历的入口。Intent将建立活动的类型以及其他数据，然后获得Activity对象来开始基于Intent数据的新获得。参考Activity和Intent类段落里的链接来查看详细内容。

1. try { 
   
2.     if (ACTION_ADD_CALENDAR_ENTRY.equals(action)) {  
   
3.     JSONObject arg_object = args.getJSONObject(0); 
   
4.     Intent calIntent = new Intent(Intent.ACTION_EDIT) 
   
5.         .setType("vnd.android.cursor.item/event") 
   
6.         .putExtra("beginTime", arg_object.getLong("startTimeMillis")) 
   
7.         .putExtra("endTime", arg_object.getLong("endTimeMillis")) 
   
8.         .putExtra("title", arg_object.getString("title")) 
   
9.         .putExtra("description", arg_object.getString("description")) 
   
10.         .putExtra("eventLocation", arg_object.getString("eventLocation")); 
    
11.   
    
12.        this.cordova.getActivity().startActivity(calIntent); 
    
13.        callbackContext.success(); 
    
14.        return true; 
    
15.     } 
    
16.     callbackContext.error("Invalid action"); 
    
17.     return false; 
    
18. } catch(Exception e) { 
    
19.     System.err.println("Exception: " + e.getMessage()); 
    
20.     callbackContext.error(e.getMessage()); 
    
21.     return false; 
    
22. }

复制代码

  需要注意的是Activity引用是来自cordova接口的。

1. import android.app.Activity; import android.content.Intent;

复制代码

   一般来说会检测action参数和调用实现必须动作的一个独立私有函数。为了简化，它放在了execute函数里。
   最后，添加Activity和Intent的Android所需类，添加本地日历入口到CalenderPlugin.java类上，在下面导入org.json.JSonException。 
  2.现在保存文件，然后来第二部分吧。
第二部分 编写JS接口
   下一步我们将编写插件的JS接口。这里是应用跟外边JS和本地桥梁之家的跨越，以便执行本地代码。

1. var calendarPlugin = { createEvent: function(title, location, notes, startDate, endDate, successCallback, errorCallback) { } }

复制代码

   打开编辑器，创建一个叫calender.js的文件。可以放到CalenderPlugin.java文件所在地。 
   在calender.js里，编写一个叫createEvent的函数，里面有一个new的calenderPlugin变量，这个函数用来获取自定义参数，和用来在本地代码上创建日历入口的回调函数。

1. var calendarPlugin = { 
   
2.     createEvent: function(title, location, notes, startDate, endDate, successCallback, errorCallback) { 
   
3.         cordova.exec( 
   
4.             successCallback, // success callback function 
   
5.             errorCallback, // error callback function 
   
6.             'CalendarPlugin', // mapped to our native Java class called "CalendarPlugin" 
   
7.             'addCalendarEntry', // with this action name 
   
8.             [{                  // and this array of custom arguments to create our entry 
   
9.                 "title": title, 
   
10.                 "description": notes, 
    
11.                 "eventLocation": location, 
    
12.                 "startTimeMillis": startDate.getTime(), 
    
13.                 "endTimeMillis": endDate.getTime() 
    
14.             }] 
    
15.         );  
    
16.      } 
    
17. }

复制代码

   然后将代码添加到createEvent函数里，调用cordova.exec()，传入下述参数。
   •成功时的回调函数
   •出错时的回调函数
   •服务名
   •动作名
   •参数数组
   添加好cordov.exec()后，calender.js文件如下: 
   参数需要映射到本地java类，具体如下：
   •服务名映射到本地插件类名
   •动作名作为execute()函数的首个参数
   •参数数组作为JSON数组传入execute()函数作为第二个参数
   •成功或者出错回调函数作为CallbackContext对象的一部分作为execute()函数的第三个参数
   现在保持JS文件，然后进行下一步。
第三部分：实现
   以一个基本的PhoneGap项目作为开始。使用PhoneGap或则Cordova CLI创建，或者只是用命令行工具，然后为Android创建一个项目。
   警告：如果使用命令行工具的话，你需要确认你的环境变量建立时候包括了你的Android工具文件夹的位置以及平台工具文件夹的位置。
   我推荐使用新的PhoneGap CLI。可以快速的建立项目，之后除了Android外还可以在更多的平台添加项目，同时也提供方便的方法来将项目从命令行上传到PhoneGap Build。
   通过npm安装好PhoneGap CLI之后，运行下面的命令来创建一个基本的PhoneGap 项目，为Android添加和构建并自动部署连接到Android设备或者模拟器。

1. phonegap create ~/MyPhoneGapApp
   
2. cd ~/MyPhoneGapApp
   
3. phonegap run android

复制代码

   注意：指明你喜欢的项目路径，我为了方便，使用用户根目录作为项目路径。如果有错误的话，可能是你的路径设置有问题。参考上面警告中关于添加
android sdk工具以及平台工具的文件夹。
   如果Android设备或者模拟器上有一个基本的PhoneGap应用运行的话，你会在环境配置成功的情况下，看到下述信息：
   phonegap 检测到Android SDK环境...
   phonegap 使用本地环境
   phonegap 添加Android平台...
   phonegap 编译Android...
   phonegap 成功编译Android应用
   phonegap 安装应用到Android设备，回到模拟器上。
   如果你从来没使用Android设备做过开发，你需要到设置里将开发者模式开启。此设置根据设备不同而不同，可以查看下开发者选项。你也可以将USB调试模
式打开。
   配置基本应用来使用插件
   •用你喜欢的编辑器打开最新创建的项目
   •在项目的www/js文件夹下添加calender.js文件
   •将在上步中创建CalenderPlugin.java文件添加到myPhoneGapApp/platforms/android/src/com/example/myplugin文件夹下
需要记住你的包名，因为下一步需要用到哦。
   平台的config.xml文件包含所有应用使用的插件的映射。我们需要添加我们新的插件映射到此文件。文件在项目里的路径是project-root/android/res/xml/config.xml。将下面的映射添加到你config.xml文件的功能列表后。

1. <feature name="CalendarPlugin"> <param name="android-package" value="com.example.myplugin.CalendarPlugin" /> </feature>

复制代码

   注意：在默认PhoneGap项目的www文件夹下也有一个config.xml文件。不要讲此文件添加到文件里。需要保证是将其添加到之前标注的指明平台的res/xml/config.xml
   •打开www/index.html，在index.js脚本标签前添加我们插件中的calend.js文件的引用。

1. <script type="text/javascript" src="js/calendar.js"></script>

复制代码

   •打开www/js/index.js文件，在receiveEvent函数下添加下面的函数

1. addToCal: function() { 
   
2.         var startDate = new Date("July 19, 2013 8:00:00"); 
   
3.         var endDate = new Date("July 19, 2013 18:00:00"); 
   
4.         var notes = "Arrive on time, don't want to miss out (from Android)"; 
   
5.         var title = "PhoneGap Day"; 
   
6.         var location = "Portland, OR"; 
   
7.         var notes = "Arrive on time, don't want to miss out!"; 
   
8.         var success = function() { alert("Success"); }; 
   
9.         var error = function(message) { alert("Oopsie! " + message); }; 
   
10.         calendarPlugin.createEvent(title, location, notes, startDate, endDate, success, error); 
    
11. }

复制代码

   •然后添加下面代码，在onDeviceReady函数里调用它

1. app.addToCal();

复制代码

   •另外：在应用里添加一个按钮，这样你就可以使用新功能来重复增加日历入口了。
第五部分：运行
   回到命令行，并到项目根目录下，运行下面的命令：
   Phonegap run android
   应用打开的时候，就会在设备上看到打开根据代码里指明的标题，日期，备注，位置等信息的本地日历。下面是在Nexus7上的一个运行截屏：

   测试和调试提示：
   1. 输入 phonegap help来获取PhoneGap CLI命令提示
   2. 输入adb logcat来显示android控制台调试 
*** 第六部分：选看-实现多线程
   在Android WebView里的JS运行在主线程上，这也是Java运行函数的地方，当然这可能导致线程的阻塞问题。可以选择让它运行一个单独的线程。你可以根
据你的本地代码来选择下述两者之一的选项。
   如果你的本地代码是需要跟用户界面交互，那么在CalenderPlugin.java里，你可能想指明它来直接在本地用户界面线程里运行，如下动作检测后：

1. cordova.getThreadPool().execute(new Runnable() { 
   
2.     public void run() { 
   
3.         // Main Code goes here 
   
4.         callbackContext.success();  
   
5.     } 
   
6. });

复制代码

*** 第七部分：选看：最后整理
   1.创建一个readme文件来说明插件的使用方式
   2.同时考虑将代码贡献给开源插件库
   3.如果你考虑提交给PhoneGap Build支持中心，确信你为新插件创建了plugin.xml
   帮助链接：
   • PhoneGap Plugin Development Guide
   • 查看Simon McDonald的博文，来学习如何写PhoneGap插件的详细内容。他会告诉你如何使用少量的先进方式来开发JS端代码，类似PhoneGap 的API-http://simonmacdonald.blogspot.c ... ap-200-android.html  
• PhoneGap Command Line Interface 
   • iOS Calendar Plugin Option
   • Android Calendar Plugin Option
   • Another Android Calendar Plugin Option

原文链接：http://devgirl.org/2013/07/17/tutorial-how-to-write-a-phonegap-plugin-for-android/