想替 Ionic2 專案寫一個自己的 Cordova 外掛時,我搜了一圈,發現網路上的文章幾乎千篇一律,細節也不夠。於是自己搗鼓了一整個下午,踩了不少坑,這裡把完整流程記錄下來。
需求設定很簡單:寫一個日誌外掛,把 log 寫進手機的 sdcard。
npm install -g plugman
plugman create --name 外掛名字 --plugin_id 外掛id --plugin_version 版本號
實際指令範例:
plugman create --name cordovaHeaLog --plugin_id cordova-plugin-hea-log --plugin_version 1.0
執行後會產生如下的專案結構:

plugman platform add --platform_name android
接著你會看到 src 底下多了一個 android 資料夾,裡面也多了對應的 Java 檔。

在 src/android 中新增一個 logUtil.java:
package cordova.plugin.hea.log;
import android.os.Environment;
import java.io.BufferedWriter;
import java.io.File;
import java.io.FileWriter;
import java.io.IOException;
import java.text.SimpleDateFormat;
import java.util.Calendar;
import java.util.Date;
public class logUtil {
private static int SDCARD_LOG_FILE_SAVE_DAYS = 180; // sd卡中日志文件的最多保存天數
private static String LOG_PATH_SDCARD_DIR =
Environment.getExternalStorageDirectory().toString() + "/VP2/log/"; // 日誌在 sdcard 中的路徑
private static SimpleDateFormat LogSdf = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
private static SimpleDateFormat logDay = new SimpleDateFormat("dd");
private static SimpleDateFormat logTime = new SimpleDateFormat("yyyy-MM");
/**
* 打開日誌文件並寫入日誌
*/
public static void writeLogtoFile(String mylogtype, String tag, String text) {
delFile();
Date nowtime = new Date();
String needWriteMessage = LogSdf.format(nowtime) + " " + tag + "\n" + text + "\n";
String logFileName;
String logFolder = logTime.format(new Date());
if (mylogtype == "error") {
logFileName = "error(" + logDay.format(new Date()) + ").log";
} else if (mylogtype == "crash") {
logFileName = "crash(" + logDay.format(new Date()) + ").log";
} else {
logFileName = "info(" + logDay.format(new Date()) + ").log";
}
File file = new File(LOG_PATH_SDCARD_DIR + logFolder);
if (!file.exists()) {
file.mkdirs();
}
File f = new File(LOG_PATH_SDCARD_DIR + logFolder, logFileName);
try {
FileWriter filerWriter = new FileWriter(f, true);
BufferedWriter bufWriter = new BufferedWriter(filerWriter);
bufWriter.write(needWriteMessage);
bufWriter.newLine();
bufWriter.close();
filerWriter.close();
} catch (IOException e) {
e.printStackTrace();
}
}
/**
* 刪除指定的日誌文件
*/
private static void delFile() {
String needDelFiel = logTime.format(getDateBefore());
File file = new File(LOG_PATH_SDCARD_DIR, needDelFiel);
if (file.exists()) {
file.delete();
}
}
private static Date getDateBefore() {
Date nowtime = new Date();
Calendar now = Calendar.getInstance();
now.setTime(nowtime);
now.set(Calendar.DATE, now.get(Calendar.DATE) - SDCARD_LOG_FILE_SAVE_DAYS);
return now.getTime();
}
}
接著修改 src/android/cordovaHeaLog.java,讓它成為外掛的入口:
package cordova.plugin.hea.log;
import org.apache.cordova.CordovaPlugin;
import org.apache.cordova.CallbackContext;
import org.json.JSONArray;
import org.json.JSONException;
import cordova.plugin.hea.log.logUtil;
/**
* This class echoes a string called from JavaScript.
*/
public class cordovaHeaLog extends CordovaPlugin {
@Override
public boolean execute(String action, JSONArray args, CallbackContext callbackContext)
throws JSONException {
if (action.equals("log")) {
this.log(args.getString(0), args.getString(1), args.getString(2), callbackContext);
return true;
}
return false;
}
private void log(String mylogtype, String tag, String text, CallbackContext callbackContext) {
if (mylogtype != null && mylogtype.length() > 0
&& text != null && text.length() > 0
&& tag != null && tag.length() > 0) {
logUtil.writeLogtoFile(mylogtype, tag, text);
callbackContext.success(mylogtype + " " + tag + " " + text);
} else {
callbackContext.error("參數不可為空");
}
}
}
然後修改 www/cordovaHeaLog.js,這是 JavaScript 端的橋接層:
var exec = require('cordova/exec');
exports.log = function (arg0, arg1, arg2, success, error) {
exec(success, error, "Logjava", "log", [arg0, arg1, arg2]);
};
重點來了。這個檔案我卡最久,折騰好一陣子才跳出來。內容需要改成:
<?xml version='1.0' encoding='utf-8'?>
<plugin id="cordova-plugin-hea-log" version="1"
xmlns="https://apache.org/cordova/ns/plugins/1.0"
xmlns:android="https://schemas.android.com/apk/res/android">
<name>cordovaHeaLog</name>
<js-module name="cordovaHeaLog" src="www/cordovaHeaLog.js">
<clobbers target="cordovaHeaLog" />
</js-module>
<platform name="android">
<config-file parent="/*" target="res/xml/config.xml">
<feature name="Logjava">
<param name="android-package" value="cordova.plugin.hea.log.cordovaHeaLog" />
</feature>
</config-file>
<config-file parent="/*" target="AndroidManifest.xml"></config-file>
<source-file src="src/android/cordovaHeaLog.java"
target-dir="src/cordova/plugin/hea/log/cordovaHeaLog" />
<source-file src="src/android/logUtil.java"
target-dir="src/cordova/plugin/hea/log/logUtil" />
</platform>
</plugin>
這裡的三個 id 必須互為呼應:feature 的 name(Logjava)要與 JS 端 exec 的第三個參數一致;android-package 要與 Java 檔的 package 加類名一致;clobbers 的 target 則決定 JS 端能用什麼全域名稱呼叫。
一般從遠端安裝外掛的寫法:
cordova plugin add cordova-plugin-hea-log
若要加入本地外掛,直接指定路徑即可。我的外掛放在 E:\cordovaHeaLog,就這樣寫:
cordova plugin add E:\cordovaHeaLog
補充說明:之所以平時寫的是 cordova-plugin-hea-log,是因為 plugin.xml 裡設定的 id 就是這個值。

cordova platform add android
因為要寫入 sdcard,必須在 HeaIonic/android/AndroidManifest.xml 中補上權限:
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
打開 platforms/android/assets/www 底下的 cordova_plugins.js,可以看到外掛已註冊進來:

接著就能在頁面上直接呼叫,下圖圈起來的就是新增的程式碼:

然後依次執行 ionic serve 與 cordova build android,再用 Android Studio 打包專案並運行。
結果:外掛成功把日誌寫入檔案。

1. plugin.xml 是問題最多的地方,建議先把它的配置規則弄清楚再動手,尤其是 feature name、android-package、clobbers target 三者的對應關係。
2. logUtil.java 這類工具類別,最好先在一般 Android 專案裡把功能測通,確認無誤後再搬進外掛,能省下大量排查時間。
3. 除錯時,加入外掛後若出現問題,可以透過 Android Studio 的 Logcat 視窗查看錯誤出自何處,它會輸出具體訊息,對照著處理即可。一開始我也一頭霧水,不知道該去哪裡看外掛的錯誤——畢竟還是個小菜鳥,寫完總要實際跑跑看才知道哪裡會出錯。
延伸參考:Android Plugin Development Guide。