[Cordova] Plugin开发入门

Overview

Cordova的设计概念，是在APP上透过Web控件来呈现Web页面，让Web开发人员可以操作熟悉的语言、工具来开发APP。使用Web页面来呈现功能内容，的确可以满足大部分的功能需求，但是因为APP的使用情景毕竟有别于Web，某些APP的功能需求像是：拨打电话、扫描条形码...等等，无法单纯使用Web开发技术就能实现。

为了让Web页面能够满足更多的APP功能需求，Cordova提供了Plugin机制，让Web页面能够挂载并调用Native开发技术所开发的功能模块。当开发人员遇到Web开发技术无法实现的功能需求时，可以到Cordova官网(https://cordova.apache.org/plugins/)，下载并使用官方提供的各种通用Plugin功能模块。而就算遇到了特殊的功能需求，Cordova也提供了方法，让开发人员可以自行开发专属于自己的客制Plugin功能模块。

本篇文章介绍如何建立一个Cordova Plugin功能模块，让开发人员能够使用Native开发技术，在Cordova里开发Plugin功能模块给Web页面使用，让Web页面能够满足更多的APP功能需求。主要是为自己留个纪录，也希望能帮助到有需要的开发人员。

Cordova Plugin Metadata

Cordova Plugin功能模块会以文件夹的形式，存放于本机文件系统或是远程Git服务器。使用Visual Studio开发Cordova项目的时候，只要输入档案路径或是服务器路径，就可以自动完成挂载Plugin功能模块的动作。

挂载Plugin功能模块的时候，Visual Studio会读取文件夹下的「plugin.xml」。这个XML档案中定义了Plugin功能模块的相关设定项目，这些设定项目里用于描述Plugin功能模块的，主要项目为：

id : Plugin标识符
version : Plugin版本
name : Plugin名称
description : Plugin描述
license : Plugin授权模式
js-module : 各个JavaScript模块的设定项目
platform : 各个执行平台的设定项目

<?xml version="1.0" encoding="UTF-8"?>
<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
        id="clk-cordova-sample"
        version="1.0.0">
    <!-- metadata -->
    <name>CLK Cordova Sample</name>
    <description>CLK Cordova Sample的说明</description>
    <license>Apache 2.0</license>
    <!-- javascript -->
    <js-module>...</js-module>
    <js-module>...</js-module>
    <!-- android -->
    <platform name="android">...</platform>
    <!-- ios -->
    <platform name="ios">...</platform>
</plugin>

Android Platform Plugin

platform metadata

Cordova在编译Android Platform Plugin的时候，会先建立编译用的Android项目，并且读取plugin.xml里被标注为android的platform设定区块，做为编译时期的编译参数。

<!-- android -->
<platform name="android">
    <!-- config -->
    <config-file target="res/xml/config.xml" parent="/*">
        <feature name="NotificationService">
            <param name="android-package" value="com.clk.cordova.sample.NotificationService"/>
        </feature>
    </config-file>
    <!-- source -->
    <source-file src="src/android/NotificationService.java" target-dir="src/com/clk/cordova/sample/" />
</platform>

source-file

当Cordova读取到Android platform的设定区块的source-file设定区块时，会将每一个source-file设定区块里src所指定的档案，复制到Android项目里target-dir所指定文件夹，用以进行后续的编译工作。在本篇的范例里，source-file设定区块所代表的意义是：将Plugin里src/android/NotificationService.java的这个档案，复制到Android项目的src/com/clk/cordova/sample/文件夹里面来进行编译。

<!-- source -->
<source-file src="src/android/NotificationService.java" target-dir="src/com/clk/cordova/sample/" />

config-file

Android platform的设定区块的config-file设定区块比较特别，这个设定区块是用来，定义提供给Web页面调用的类别。在这其中feature name代表的是这个Plugin提供给Web页面使用的类别别名，而param value里定义的则是实际提供服务的Native类别名称，剩余其他设定参数则是编译所需的固定参数。在本篇范例里，config-file设定区块所代表的意义是：Web页面可以使用NotificationService这个类别别名，来调用Android项目里面的com.clk.cordova.sample.NotificationService这个Native类别。

<!-- config -->
<config-file target="res/xml/config.xml" parent="/*">
    <feature name="NotificationService">
        <param name="android-package" value="com.clk.cordova.sample.NotificationService"/>
    </feature>
</config-file>

native code

Android platform plugin里，使用Native技术所开发的Native类别，必须先继承org.apache.cordova.CordovaPlugin这个类别，再经由source-file设定加入项目编译，后续才可以透过config-file的定义提供Web页面调用。而Web页面调用Native类别时，Cordova会执行Native类别的execute方法，并且提供下列内容：

action : 方法名称。
- 因为只有execute一个进入点，所以使用action来分发方法，让一个Class能够提供更多方法。
args : 方法参数。
- 对应方法名称的参数内容、为JSONArray格式。
callbackContext : 方法回呼。
- 方法成功时呼叫callbackContext.success回传成功结果、方法失败时呼叫callbackContext.error回传错误讯息。
return : 是否接受调用。
- 方法成功时回传true、方法失败时回传false。

package com.clk.cordova.sample;
import org.apache.cordova.*;
import org.json.*;
import android.widget.Toast; 
public class NotificationService extends CordovaPlugin {
    // methods
    public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException {
        // show
        if(action.equals("show")) {
            // arguments
            String message = args.getString(0); 
            // execute
            Toast.makeText(this.cordova.getActivity(), message, Toast.LENGTH_LONG).show();
            // return
            return true;
        }
        // default
        return false;
    }
}

cordova.exec

完成上述Android Platform Plugin的相关开发工作之后，在挂载这个Cordova Plugin的Android执行平台里，Web页面就可以使用统一的cordova.exec方法，来调用Native开发的类别。这个cordova.exec接口会执行Native类别的execute方法，并且带入下列内容：

success : 方法成功时的Callback函式。
error：方法失败时的Callback函式。
feature：config-file设定区块所定义的类别别名。
action：Native类别提供的方法名称。
args：Native类别提供的方法参数。

cordova.exec(success, error, feature, action, args);

iOS Platform Plugin

platform metadata

Cordova在编译iOS Platform Plugin的时候，会先建立编译用的iOS项目，并且读取plugin.xml里被标注为ios的platform设定区块，做为编译时期的编译参数。

<!-- ios -->
<platform name="ios">
    <!-- config -->
    <config-file target="config.xml" parent="/*">
        <feature name="NotificationService">
            <param name="ios-package" value="CLKNotificationService"/>
        </feature>
    </config-file>
    <!-- source -->
    <header-file src="src/ios/CLKNotificationService.h" />
    <source-file src="src/ios/CLKNotificationService.m" />
</platform>

source-file

当Cordova读取到iOS platform的设定区块的source-file设定区块时，会将每一个source-file设定区块里src所指定的档案，复制到iOS项目的Plugin文件夹，用以进行后续的编译工作。在本篇的范例里，source-file设定区块所代表的意义是：将Plugin里src/ios/CLKNotificationService.h跟CLKNotificationService.m的这两个档案，复制到iOS项目的Plugin文件夹里面来进行编译。

<!-- source -->
<header-file src="src/ios/CLKNotificationService.h" />
<source-file src="src/ios/CLKNotificationService.m" />

config-file

iOS platform的设定区块的config-file设定区块比较特别，这个设定区块是用来，定义提供给Web页面调用的类别。在这其中feature name代表的是这个Plugin提供给Web页面使用的类别别名，而param value里定义的则是实际提供服务的Native类别名称，剩余其他设定参数则是编译所需的固定参数。在本篇范例里，config-file设定区块所代表的意义是：Web页面可以使用NotificationService这个类别别名，来调用iOS项目里面的CLKNotificationService这个Native类别。

<!-- config -->
<config-file target="config.xml" parent="/*">
    <feature name="NotificationService">
        <param name="ios-package" value="CLKNotificationService"/>
    </feature>
</config-file>

native code

iOS platform plugin里，使用Native技术所开发的Native类别，必须先继承CDVPlugin这个类别，再经由source-file设定加入项目编译，后续才可以透过config-file的定义提供Web页面调用。而Web页面调用Native类别时，Cordova会依照Web页面所提供的action参数，来执行Native类别里同名的方法，并且提供下列内容：

CDVInvokedUrlCommand : 执行指令
- @property (nonatomic, readonly) NSString* callbackId; : 回呼编号
- (id)argumentAtIndex:(NSUInteger)index; : 取得输入参数
CDVPluginResult : 执行结果
- @property (nonatomic, strong, readonly) NSNumber* status; : 执行结果(Ex:成功、失败...)
- @property (nonatomic, strong, readonly) id message; : 回传参数(Ex:String、Bool...)
CDVPlugin(self) : 继承的CDVPlugin
- @property (nonatomic, weak) id commandDelegate; : 回传执行结果物及回呼编号

// CLKNotificationService.h
#import <Foundation/Foundation.h>
#import <Cordova/CDVPlugin.h>
@interface CLKNotificationService : CDVPlugin
// methods
-(void)show:(CDVInvokedUrlCommand*)command;
@end

// CLKNotificationService.m
#import "CLKNotificationService.h"
@implementation CLKNotificationService
// methods
- (void)show:(CDVInvokedUrlCommand*)command
{
    // arguments
    NSString* message = [command argumentAtIndex:0];
    // execute
    [[[UIAlertView alloc] initWithTitle:nil message:message delegate:nil cancelButtonTitle:@"OK" otherButtonTitles:nil] show];
}
@end

cordova.exec

完成上述iOS Platform Plugin的相关开发工作之后，在挂载这个Cordova Plugin的iOS执行平台里，Web页面就可以使用统一的cordova.exec方法，来调用Native开发的类别。这个cordova.exec接口会提供action参数，来执行Native类别里同名的方法，并且带入下列内容：

success : 方法成功时的Callback函式。
error：方法失败时的Callback函式。
feature：config-file设定区块所定义的类别别名。
action：Native类别提供的方法名称。
args：Native类别提供的方法参数。

cordova.exec(success, error, feature, action, args);

JavaScript Module Plugin

Cordova提供统一的cordova.exec方法，让Web页面调用Native开发的Plugin功能。但是，cordova.exec方法需要带入的五个输入参数、加上success、error这两个Callback函式所隐含的回传参数、再加上多参数需要包装成JSON格式...这些琐碎的工作，会大量增加Web开发人员使用Plugin功能模块的负担。

为了减少Web开发人员使用Plugin功能模块的负担，Plugin功能模块的开发人员，可以使用Cordova提供的JavaScript Module挂载机制，在Plugin功能模块里面加入JavaScript程序代码来封装cordova.exec方法，用以提供更简洁、更易懂的使用接口让Web开发人员使用。

Before

cordova.exec(null, null, "NotificationService", "show", [message]);

After

clk.cordova.sample.NotificationService.show("Clark");

js-module metadata

Cordova在编译每个执行平台的时候，会读取plugin.xml里所有的js-module设定区块，并且将每一个js-module设定区块里src所指定的js-module原始码打包备用。当应用程序执行的时候，Cordova核心会将这些js-module加载来提供Web页面使用。

name : js-module标识符
src : js-module原始码

<!-- javascript -->
<js-module name="NotificationService" src="www/clk.cordova.sample.NotificationService.js" >
    ...
</js-module>

js-module code

在每个js-module原始码的内部，可以透过Cordova所提供的exports对象，来附加使用JavaScript所撰写的功能函式，这个exports对象是用来封装js-module功能的对象。在本篇的范例里，js-module原始码在exports对象上，附加了一个show函式用来简化cordova.exec的使用方式，提供给Web页面使用。

clk.cordova.sample.NotificationService.js

// methods
exports.show = function (message) {
    cordova.exec(null, null, "NotificationService", "show", [message]);
};

cordova.require

Web页面需要使用js-module的时候，可以使用cordova.require方法来取得js-module。这个cordova.require方法，使用js-module设定区块里name所设定的名称、加上Plugin metadata里所定的id标识符做为索引，来识别并取得Cordova核心中的js-module。在本篇的范例里，Web页面使用cordova.require取得Plugin id：clk-cordova-sample、js-module name：NotificationService，封装js-module的exports对象，并且调用这个exports对象所附加的show函式。

index.html

var notificationService = cordova.require("clk-cordova-sample.NotificationService");
notificationService.show("Clark");

clobbers

为了更进一步简化取得js-module的方式，Cordova另外在plugin.xml的js-module设定区块上，提供了clobbers设定项目。当应用程序执行、Cordova核心加载js-module提供Web页面使用的时候，如果定义了clobbers所提供的target设定参数，Cordova核心会自动将封装js-module的exports对象，存放到target所定义的对象上，让Web页面可以直接调用。

在本篇的范例里，js-module定义了一个clobbers的target，Cordova核心会在载入clk.cordova.sample.NotificationService.js之后，将封装js-module的exports对象，存放到clk.cordova.sample.NotificationService这个物件上。后续Web页面，只要直接使用clk.cordova.sample.NotificationService.show就可以调用这个exports对象所附加的show函式。

clobbers

<!-- javascript -->
<js-module name="NotificationService" src="www/clk.cordova.sample.NotificationService.js" >
    <clobbers target="clk.cordova.sample.NotificationService" />
</js-module>

index.html

clk.cordova.sample.NotificationService.show("Clark");

范例下载

范例程序代码：下载地址