如何建立Cordova外掛

Nicker2013發表於2020-12-07

如何建立Cordova外掛

官方資料

注意：本文資料相對官網要更加新一些，官網是針對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" 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.實際使用

在程式碼中，確認能夠獲取到cordova時，呼叫如下語句即可實際呼叫java對應函式。

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

推薦參考文件

Cordova外掛開發(iOS/Android)–看這篇就夠了

相關文章