如何创建Cordova插件

如何创建Cordova插件

时间：2020-12-07

官方资料

注意：本文资料相对官网要更加新一些，官网是针对6.x版本写的。
如果英文够好，可以直接看官网：Create a plugin
也可以查看繁体中文：外掛程式開發指南

制作步骤

这里主要讲述如何创建一个独立的cordova插件，之后再引入到项目中去。

1.下载制作工具

通过npm安装。

npm install -g plugman

2.通过plugman创建插件

假设插件名称为test_plugin，运行如下代码则可以创建插件。

plugman create --name test_plugin --plugin_id test_plugin --plugin_version 1.0.0

其中：

--name test_plugin --> 插件名
--plugin_id test_plugin  --> 插件ID
--plugin_version 1.0.0 -->插件版本

这样你会得到一个插件的基本结构，包括一个src文件夹，一个www文件夹(内含test_plugin.js)，一个plugin.xml文件

你也可以手动创建这几个文件夹和文件。
然后通过下载已有的插件项目作为参考来进行后续开发。例如cordova-plugin-device。

cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git

3.调整plugin.xml文件

plugin.xml文件是整个插件的主要配置文件，声明了插件的相关信息。
刚刚创建出来的xml文件如下：

<?xml version='1.0' encoding='utf-8'?>
<plugin id="test_plugin" version="1.0.0" xmlns="http://apache.org/cordova/ns/plugins/1.0" xmlns:android="http://schemas.android.com/apk/res/android">
    <name>test_plugin</name>
    <js-module name="test_plugin" src="www/test_plugin.js">
        <clobbers target="cordova.plugins.test_plugin" />
    </js-module>
</plugin>

其中包含了插件名称，插件的js文件所在位置www/test_plugin.js，插件的目标对象cordova.plugins.test_plugin，
目标对象，也就是在js中如何能拿到/调用这个插件。

接下来，在插件里添加所需平台，以android为例。添加在</js-module>之后。

    <!-- android -->
    <platform name="android">
        <config-file target="config.xml" parent="/*">
            <feature name="test_plugin">
                <param name="android-package" value="com.cordova.plugin.test_plugin.test_plugin" onload="true" />
            </feature>
        </config-file>

        <source-file src="src/android/test_plugin.java" target-dir="src/com/cordova/plugin/test_plugin" />
    </platform>

这里将指示java文件在本项目中的位置，插件安装时文件将拷贝到的目标位置，java包名。

4.修改js文件

此时修改js文件，改成具有多个函数可以调用的形式

let test_plugin= {
  test_func_A(arg0, success, error){
    exec(success, error, 'test_plugin', 'test_func_A', [arg0]);
  },
  test_func_B(arg0, success, error){
    exec(success, error, 'test_plugin', 'test_func_A', [arg0]);
  },
}
module.exports = test_plugin;

此文件，最终将成为插件的目标对象cordova.plugins.test_plugin，可以调用其中定义的函数test_func_A或者test_func_B。

5.创建java文件

例子中，可以看到，
如何调用不同的java函数，并且推荐使用try...catch语句，真实开发中，android的调用很容易引起崩溃，所以务必加上try...catch。
如何传递参数，使用语句args.getInt(0);除了int，还可以传递其他JSON支持的类型。
返回值的类型可以查看callbackContext.success的定义，支持int型，string类型作为返回值，同时支持JSONArray和JSONObject，但实际上仍然是转为string返回。

这时候，你就可以将这些函数当做桥梁，去网上找android开发的原生代码/库，然后进行调用。

同时，要注意，这个类继承自CordovaPlugin，并不是Activity，所以Context也无法通过自身直接获取，所以需要使用函数this.cordova.getContext();
网上很多android开发的例子都是直接使用activity的context，这里一定要注意context来源，否则容易出错。

package com.cordova.plugin.test_plugin;

import android.app.Activity;
import android.content.Context;

import org.apache.cordova.CordovaPlugin;
import org.apache.cordova.CallbackContext;

import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;

public class test_plugin extends CordovaPlugin {
    @Override
    public boolean execute(String action, JSONArray args, CallbackContext   callbackContext) throws JSONException {
        Activity activity = this.cordova.getActivity();//获取项目activity的方法
        Context context = this.cordova.getContext();//获取项目context的方法
        
        if (action.equals("test_func_A")) {
            int index = args.getInt(0);//如何获取传入的参数
            int vcode = test_func_A(context, index);
            callbackContext.success(vcode);
            return true;
        }else if (action.equals("test_func_B")) {
            string vstr = test_func_B(context);
            callbackContext.success(vstr);
            return true;
        }
        return false;
    }
    
    private static int test_func_A(Context ctx, int index) {
    	try{
    		return index + 1;
    	}catch(Exception e){
            e.printStackTrace();
            return -1;
    	}
    }
    private static String test_func_B(Context context) {
    	try{
    		return "hello world!";
    	}catch(Exception e){
            e.printStackTrace();
            return -1;
    	}
    }
}

6.插件项目package信息完整化

在插件所在文件夹（config.xml那一层）
运行命令：

plugman createpackagejson ./

之后按照提示，挨个确认即可。此后，这个包将有了package.json文件，包含了这个软件包的相关信息。
要注意，没有这个package.json的相关信息，最后添加插件的时候会失败。

7.如何添加到任意项目

开发插件，很多时候都不仅仅是为了某一个项目而使用，因此，推荐用上传git，然后添加插件的方式来使用。
首先可以在github或者gitee，或者code.aliyun上开一个项目。
将之前的插件项目上传。

然后前往cordova项目所在文件夹。
先运行命令，查看一下现有的插件

cordova plugin list

然后运行命令添加插件

cordova plugin add <your git http url>

8.实际使用

在项目代码中，确认能够获取到cordova时，调用如下语句即可实际调用java对应函数。

cordova.plugins.test_plugin.test_func_A(0, function(back_int){
	console.log("test_func_A back_int=", back_int);
});

9.如何更新插件

说实话，感觉cordova的插件管理设计得并不是特别好用，或者可能我用得并不熟练吧。
一般情况下，自己的插件更新了，相应项目更新的话，
先删除插件，然后再重新安装这个插件就好了

cordova plugin remove test_plugin
cordova plugin add <your git http url>

10.常见错误处理

找不到class

例如，

java.lang.ClassNotFoundException: com.cordova.plugin.test_plugin

那么就是此前config.xml文件中java类名配置错了。
需要仔细查看并修改这一条中的value值

<param name="android-package" value="com.cordova.plugin.test_plugin.test_plugin" onload="true" />

其他相关文章

Cordova使用入门简介
如何创建一个引入Module的Cordova插件

推荐参考文档

Cordova插件开发(iOS/Android)–看这篇就够了