PhoneGap(後來的 Cordova)最大的魅力在於可以用 HTML、CSS、JavaScript 寫出跨平台 App,但一旦需要呼叫相機、藍牙、支付這類原生能力,就必須自己動手寫 Plugin。本文以 Xcode 4.5.1 搭配 PhoneGap 2.1.0,示範如何打造一個最簡單的「字串相加」Plugin,把 JavaScript 的呼叫一路串到 Objective-C 的原生實作,再把結果回傳給網頁。
新增一個名為 MyPlugin 的工程,確認環境版本如下:
Xcode:4.5.1
PhoneGap:2.1.0
先建立標頭檔 MyPlugin.h,讓它繼承 CDVPlugin,並宣告一個接收 CDVInvokedUrlCommand 的方法:
//
// MyPlugin.h
// MyPGPlugin
//
#import <Cordova/CDV.h>
@interface MyPlugin : CDVPlugin
- (void) add:(CDVInvokedUrlCommand*)command;
@end接著是實作檔 MyPlugin.m。這裡有幾個關鍵角色值得先記住:CDVInvokedUrlCommand 負責承載 JavaScript 傳過來的參數與 callbackId;CDVPluginResult 負責封裝回傳結果;而 writeJavascript: 則是把結果送回網頁的通道。
#import "MyPlugin.h"
#import <Cordova/CDV.h>
@implementation MyPlugin
- (void) add:(CDVInvokedUrlCommand*)command{
CDVPluginResult* pluginResult = nil;
NSString* javaScript = nil;
@try {
NSString* echo = [command.arguments objectAtIndex:0];
NSString* echo2 = [command.arguments objectAtIndex:1];
if (echo != nil
&& [echo length] > 0
&& echo2 != nil
&& [echo2 length] > 0) {
/**
* 相加(拼接)字串
*/
NSString *addResult = [NSString stringWithFormat:@"%@%@", echo, echo2];
pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK
messageAsString:addResult];
javaScript = [pluginResult toSuccessCallbackString:command.callbackId];
} else {
pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_ERROR];
javaScript = [pluginResult toErrorCallbackString:command.callbackId];
}
} @catch (NSException* exception) {
pluginResult = [CDVPluginResult resultWithStatus:CDVCommandStatus_JSON_EXCEPTION
messageAsString:[exception reason]];
javaScript = [pluginResult toErrorCallbackString:command.callbackId];
}
[self writeJavascript:javaScript];
}
@end這裡刻意用 @try / @catch 包住整個流程,是因為參數可能是 nil 或型別不如預期。Cordova 官方範例也都遵循這個慣例,避免一個 JS 呼叫就把整個 App 弄崩。
原生端寫完還不夠,網頁端需要一個對外的介面。建立 MyPlugin.js,核心就是 cordova.exec:
var MyPlugin = {
add: function(args, args2, addSuc, addFaild) {
cordova.exec(addSuc, addFaild, "MyPlugin", "add", [args, args2]);
}
};cordova.exec 的五個參數依序是:成功回呼、失敗回呼、Plugin 名稱、要呼叫的方法名、以及參數陣列。這裡的 "MyPlugin" 必須和 Cordova.plist 的註冊名稱一致,"add" 則要對得上 Objective-C 的方法簽章。
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="format-detection" content="telephone=no" />
<meta name="viewport" content="user-scalable=no, initial-scale=1,
maximum-scale=1, minimum-scale=1, width=device-width,
height=device-height, target-densitydpi=device-dpi" />
<link rel="stylesheet" type="text/css" href="css/index.css" />
<title>MyPlugin Demo</title>
</head>
<body>
<div class="app">
<h1>Apache Cordova MyPlugin</h1>
<div id="deviceready" class="blink">
<p class="event listening">Connecting to Device</p>
<p class="event received">Device is Ready</p>
</div>
</div>
<script type="text/javascript" src="cordova-2.1.0.js"></script>
<script type="text/javascript" src="js/MyPlugin.js"></script>
<script type="text/javascript">
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
// 裝置就緒後才呼叫 Plugin
MyPlugin.add("My", "Plugin", addSuc, addFiald);
}
</script>
<script type="text/javascript">
// JS 端回呼函式
function addSuc(result) {
console.log('addSuc=' + result);
}
function addFiald() {
console.log('addFiald');
}
</script>
</body>
</html>務必在 deviceready 事件之後才呼叫 Plugin。在 Cordova 尚未初始化完成前就呼叫 cordova.exec,是新手最常踩的坑之一。
在 Cordova.plist 的 Plugins 區段中新增一筆:
MyPlugin = MyPlugin
左邊的鍵是 JavaScript 呼叫時使用的名稱,右邊的值則是 Objective-C 的類別名稱。兩邊只要有一個字拼錯,執行時就會出現找不到 class 的錯誤。
按下 Run,若 console 印出 addSuc=MyPlugin,代表整条鏈路已經打通:JS 呼叫 → cordova.exec → Objective-C 的 add: 方法 → CDVPluginResult → 回呼 JS。
掌握這個模式之後,任何原生能力都能用同樣的四個步驟包裝起來,差別只在於中間那段 Objective-C 實作的複雜度。