本文詳細探討如何在 Xcode(以 iOS 為目標)中為 PhoneGap(即 Apache Cordova)應用撰寫本機插件。如果你剛接觸 PhoneGap,建議先讀過入門教學再回來看這篇。
本文交替使用 Cordova 與 PhoneGap 指稱同一個開源平台——它讓你能用 HTML 與 JavaScript 打造原生的行動應用。PhoneGap 的程式碼庫已捐贈給 Apache 軟體基金會,名為 Cordova;Adobe 仍以 PhoneGap 之名散布。差異主要在於下載包的名稱,其餘基本一致。
PhoneGap 不僅能讓你用 Web 技術建構 UI,還提供一組 JavaScript API 與裝置功能互動。預設情況下可存取的包括相機、加速度計、檔案系統、GPS 位置與媒體播放等。但 PhoneGap 並未揭露所有原生 API,因此若需要執行預設功能之外的行為,就得透過本機插件模型來擴展核心 API。
要釐清的是:PhoneGap 本機插件與桌面瀏覽器的插件完全不同。它提供的是一种「以原生程式碼自訂功能,並透過 PhoneGap 的原生-JavaScript 橋接層暴露給 JavaScript 層」的機制。這意味著你可以把任何原生函式庫或框架,包裝成 JavaScript 應用內部可用的能力。
所有 Cordova API 都由兩個部分組成:一個可在應用內部存取的 JavaScript 介面,以及一個以原生程式碼執行實際動作的對應類別。兩者的 API 通常彼此鏡像,方便追蹤。
JavaScript 類別透過 Cordova.exec() 呼叫原生程式碼。呼叫時會傳入結果處理函式、錯誤處理函式、一組參數,以及原生類別名稱與函式名稱。Cordova 負責管理 JavaScript 與原生之間的溝通,你只需專心寫自己的邏輯。
先依入門教學建立一個新的 PhoneGap 專案(此例命名為 MyFirstPhoneGapNativePlugin)。
在 www 目錄下建立 HelloPlugin.js:
var HelloPlugin = {
callNativeFunction: function (success, fail, resultType) {
return Cordova.exec(success, fail, "com.tricedesigns.HelloPlugin", "nativeFunction", [resultType]);
}
};
callNativeFunction 接收一個成功回呼、一個錯誤回呼與一個 resultType 參數,內部呼叫 Cordova.exec 觸發真正的原生程式碼。
Cordova.exec 的五個參數分別是:
請記住:JavaScript 與原生層之間的執行不是同步的,因此開發本機插件時必須使用回呼函式與非同步編碼風格。
接著建立擴展 CDVPlugin 的 Objective-C 類別:
1. 在專案的 Plugins 目錄上按右鍵選擇 New File。
圖 1. 建立新檔案
2. 選擇 Objective-C class 範本。
圖 2. 選擇 Objective-C class 範本
3. 類別名稱輸入 HelloPlugin,並設為 CDVPlugin 的子類。
圖 3. 命名類別
CDVPlugin 是所有 Cordova 類別必須繼承的父類,它封裝了 PhoneGap API 進行原生-JavaScript 溝通所需的全部邏輯。Cordova.exec 可以呼叫這個新類別上的函式。CDVPlugin 還提供一個核心函式 writeJavascript,所有從原生回 JavaScript 方向的通訊都必須透過它完成。
4. 指定檔案位置(建議放在 Plugins 目錄下)後完成。
你會看到專案中出現新的標頭檔 (.h) 與實作檔 (.m)。
圖 4. 新的原生類別檔案
5. 在 .h 中宣告方法:
#import <Cordova/CDV.h>
@interface HelloPlugin : CDVPlugin
- (void) nativeFunction:(NSMutableArray *)arguments
withDict:(NSMutableDictionary *)options;
@end
參數中 arguments 是從 JavaScript 層收到的參數陣列,options 則是字典(map)。標頭檔只放方法簽名,不寫任何應用邏輯。
6. 在 .m 中實作:
#import "HelloPlugin.h"
@implementation HelloPlugin
- (void) nativeFunction:(NSMutableArray *)arguments
withDict:(NSMutableDictionary *)options {
// 取得 callback id,PhoneGap 靠它把回應對應回呼叫的 JavaScript
NSString *callbackId = [arguments pop];
NSLog(@"Hello, this is a native function called from PhoneGap/Cordova!");
NSString *resultType = [arguments objectAtIndex:0];
CDVPluginResult *result;
if ([resultType isEqualToString:@"success"]) {
result = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK
messageAsString:@"Success :)"];
[self writeJavascript:[result toSuccessCallbackString:callbackId]];
} else {
result = [CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR
messageAsString:@"Error :("];
[self writeJavascript:[result toErrorCallbackString:callbackId]];
}
}
@end
流程說明:先取出 callbackId;用 NSLog 寫入除錯主控台以確認確實執行了原生碼;再檢查 resultType 並建立對應的 CDVPluginResult;最後用 [self writeJavascript:] 把成功或錯誤回呼寫回 JavaScript 層。
需要注意的是:回寫結果時應一律使用 CDVPluginResult 實例,但 writeJavascript 本身也可以傳任何 JavaScript 字串。這項技巧甚至可以用來把資料從原生層即時推送到 JavaScript 層。
1. 在 index.html 中引入 JavaScript 介面:
<script type="text/javascript" charset="utf-8" src="HelloPlugin.js"></script>
2. 在 onDeviceReady() 之後加入呼叫與處理的函式:
function callNativePlugin(returnSuccess) {
HelloPlugin.callNativeFunction(nativePluginResultHandler,
nativePluginErrorHandler,
returnSuccess);
}
function nativePluginResultHandler(result) {
alert("SUCCESS: \r\n" + result);
}
function nativePluginErrorHandler(error) {
alert("ERROR: \r\n" + error);
}
3. callNativePlugin 只是呼叫 JavaScript 側的介面並傳入兩個回呼。原生層成功時觸發 nativePluginResultHandler,失敗時觸發 nativePluginErrorHandler。
4. 加上兩個按鈕:
<body onload="onBodyLoad()">
<h1>Hey, it's Cordova!</h1>
<button onclick="callNativePlugin('success');">Invoke with SUCCESS</button>
<button onclick="callNativePlugin('error');">Invoke with ERROR</button>
</body>
按第一顆按鈕會傳入 "success",PhoneGap 執行原生碼後在 JavaScript 層呼叫成功回呼;第二顆則傳 "error",觸發錯誤回呼。
最後一步是讓 Cordova 認得你的原生類別。還記得 Cordova.exec 第三個參數那個字串參照嗎?必須把它映射到 Cordova.plist 中的實際類別。
1. 在專案導航器中打開 Supporting Files,點開 Cordova.plist。
2. 往下捲動到 Plugins 項目並展開。
3. 新增一筆:key 為 com.tricedesigns.HelloPlugin,value 為 HelloPlugin(請用自己的 bundle identifier 取代 com.tricedesigns)。
key 是 PhoneGap.exec 用來識別原生類別的唯一字串參照;value 則是實際要呼叫的原生類別名稱。
4. 存檔。
圖 5. 編輯 Cordova.plist
點擊 Run 或選擇 Product > Run。在 iOS 模擬器或真機上啟動後,你會看到帶有兩個按鈕的簡單畫面。點任一按鈕,原生碼就會被呼叫,並透過 JavaScript 彈出一則提示訊息。
圖 6. 在 iOS 模擬器中執行的應用
同時在 Xcode 的除錯主控台中,也能看到 NSLog 輸出的訊息,證明原生碼確實被觸發了。
圖 7. Xcode 除錯主控台的記錄
Cordova.exec 在 iOS 上會自動做拆分處理,容易對不上。保持類別名稱簡潔是最安全的做法。config.xml 的 <feature> 標籤取代。若你使用的是較新的 Cordova,請改用 config.xml 宣告插件映射。