码迷,mamicode.com
首页 > 其他好文 > 详细

[Cordova] Plugin开发入门

时间:2015-10-24 07:52:14      阅读:128      评论:0      收藏:0      [点我收藏+]

标签:

[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方法,并且带入下列内容:

  1. success : 方法成功时的Callback函式。
  2. error:方法失败时的Callback函式。
  3. feature:config-file设定区块所定义的类别别名。
  4. action:Native类别提供的方法名称。
  5. 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");
    

范例下载

范例程序代码:下载地址

[Cordova] Plugin开发入门

标签:

原文地址:http://www.cnblogs.com/clark159/p/4906112.html

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!