Worklight 自行開發(fā)的框架，提供了基于 JavaScript 的客戶端 API，它整合了客戶端需要用到的一些常規(guī)方法，支持使用相同方法在不同手機(jī)平臺(tái)上。

通過(guò)這些技術(shù)，Worklight 在不同平臺(tái)上開發(fā)應(yīng)用的能力大大加強(qiáng)。本文將首先闡述客戶端 API 的作用，然后介紹客戶端 API 的分類和調(diào)用機(jī)制中重要的 options 對(duì)象。***通過(guò)一個(gè)詳細(xì)的例子，展現(xiàn)客戶端 API 的能力。

客戶端 API 的作用

在混合模式下開發(fā)的手機(jī)端應(yīng)用，需要處理的一個(gè)主要問題就是：通過(guò)一種合理的語(yǔ)言，獲取本地的信息（比如手機(jī)的類型，操作系統(tǒng)的版本，硬件的資源）和服務(wù)器端的信息（比如各種數(shù)據(jù)，網(wǎng)絡(luò)的連接情況）。同時(shí)，能夠通過(guò)一種合理的語(yǔ)言，創(chuàng)建一些公共的控件，比如對(duì)話框，這樣就可以減少在不同手機(jī)環(huán)境下，代碼的開發(fā)量。

從廣義的角度來(lái)講，Worklight 混合模式的客戶端 API 分為三個(gè)層次：普通的 JavaScript 框架，例如 jQuery mobile，dojo mobile，prototype 等等，它們主要負(fù)責(zé)和 HTML，CSS 的互動(dòng)，來(lái)實(shí)現(xiàn)豐富的頁(yè)面效果；基于 phonegap 的 JavaScript 框架提供了和手機(jī)本地硬件的交互能力，通過(guò)它能夠很好的調(diào)用本地的一些資源；Worklight 開發(fā)的客戶端 API 則提供了基于 Worklight 整體框架的 JavaScript 功能，比如常規(guī)的調(diào)用 adapter。 的方法，創(chuàng)建各種通用控件的方法，甚至還可以通過(guò)類似反射機(jī)制，和本地的代碼進(jìn)行交互的方法。這些功能為創(chuàng)建強(qiáng)大的混合模式應(yīng)用提供了工具。

表 1. 客戶端的不同選擇

Worklight 的客戶端 API 提供了如下的功能：

• 初始化和重啟應(yīng)用的功能：在啟動(dòng)應(yīng)用時(shí)需要設(shè)置一些默認(rèn)的參數(shù)，比較常用的是 showLogger，用于在開發(fā)階段顯示日志信息；timeout 用于定義連接時(shí)間的上限；heartBeatIntervalInSecs 用于定義在應(yīng)用空閑時(shí)，多久連接一次服務(wù)器，測(cè)試連接狀態(tài)。重啟應(yīng)用的功能為失敗恢復(fù)提供了一種方式，雖然測(cè)試良好的應(yīng)用，應(yīng)該大大減少應(yīng)用崩潰的幾率， 但是在特殊情況下，應(yīng)用還是可能因?yàn)橐恍┣闆r而崩潰，提供應(yīng)用重啟功能是一種良好的補(bǔ)充方式。
• 管理認(rèn)證 session 的功能：在有認(rèn)證系統(tǒng)的條件下，應(yīng)用和服務(wù)器之間的交互需要以認(rèn)證信息作為條件，常用的有用戶的登錄、登出；用戶信息的獲取和更新；用戶登錄狀態(tài)的判定。
• 獲取和更新外部信息系統(tǒng)的功能：應(yīng)用的基本作用，就是從不同系統(tǒng)獲取數(shù)據(jù)，然后展現(xiàn)在手機(jī)端，利用客戶端 API，可以完成這項(xiàng)工作。此外，應(yīng)用可能需要訪問其他的手機(jī) web 網(wǎng)站，在不同手機(jī)系統(tǒng)中，打開網(wǎng)頁(yè)的實(shí)現(xiàn)并不相同，所以利用 Worklight 提供的 API 可以達(dá)到相同的效果。
• 能夠在多個(gè) session 中獲取和儲(chǔ)存用戶偏好設(shè)置的功能：用戶在應(yīng)用中會(huì)設(shè)定個(gè)人偏好，比如微博中就可以設(shè)定更新的排列方式，默認(rèn)展現(xiàn)的群組，這些數(shù)據(jù)可以存在服務(wù)器端，但是在運(yùn)行時(shí)，就需要通過(guò)個(gè)人偏好去管理，實(shí)現(xiàn)運(yùn)行時(shí)個(gè)性化定制。
• 將應(yīng)用信息進(jìn)行多語(yǔ)言支持的功能：多語(yǔ)言支持永遠(yuǎn)是一個(gè)好的應(yīng)用需要思考的方面，如何提供不同的語(yǔ)言版本，如何管理，如何獲取手機(jī)本地的語(yǔ)言信息，Worklight 提供的接口幫助實(shí)現(xiàn)這些功能。
• 獲取用戶手機(jī)的環(huán)境信息，并且定義不同接口的功能：這里所指的手機(jī)環(huán)境更偏向于操作系統(tǒng)級(jí)別。比如手機(jī)的系統(tǒng)是 iOS 還是 Android，手機(jī)的屏幕大小，系統(tǒng)的版本，在這些細(xì)小的差別上提供不同的實(shí)現(xiàn)，更能體現(xiàn)應(yīng)用的精致。
• 將特定的日志存入數(shù)據(jù)庫(kù)用于審計(jì)和制作報(bào)表的功能：當(dāng)應(yīng)用部署上線后，用戶的使用情況是很好的參考材料，發(fā)布方可以根據(jù)這些數(shù)據(jù)修改原有的應(yīng)用。所以，Worklight 提供了相應(yīng)的 API，用于記錄用戶的數(shù)據(jù)，并且生成報(bào)表。
• 將調(diào)試信息寫入日志窗口的功能：在初始化階段設(shè)定了 showLogger 參數(shù)后，需要在一個(gè)固定的控制臺(tái)輸出日志，比如瀏覽器的控制臺(tái)；手機(jī)中的日志文件；模擬器的日志窗口。這些不同的輸出環(huán)境，Worklight 提供了統(tǒng)一的 API，只需要唯一的接口就可以實(shí)現(xiàn)，簡(jiǎn)化了日志輸出的工作。
• 動(dòng)態(tài)讀入頁(yè)面和片段的能力：在混合模式下，數(shù)據(jù)的讀入可能來(lái)自于新的 HTML 頁(yè)面，也可能來(lái)自于某一個(gè)頁(yè)面片段。動(dòng)態(tài)的組織這些內(nèi)容可以提供良好的導(dǎo)航功能，又簡(jiǎn)化系統(tǒng)的文件結(jié)構(gòu)，可以將不同頁(yè)面存入不同的文件中，便于開發(fā)和測(cè)試時(shí)候的管理、定位。

客戶端 API 的分類

Worklight 將 API 分為四類：普通應(yīng)用接口，Worklight 可以創(chuàng)建手機(jī)應(yīng)用外，還可以創(chuàng)建桌面應(yīng)用和 web 應(yīng)用，普通接口在不同環(huán)境下均可使用。手機(jī)的功能函數(shù)和 UI 控件，這些接口完全為了手機(jī)設(shè)定，為了更方便的提供跨平臺(tái)功能，Worklight 對(duì)于不同手機(jī)操作系統(tǒng)實(shí)現(xiàn)的相同功能進(jìn)行抽取，制作了這部分內(nèi)容。桌面和 web 小工具的方法，這些函數(shù)主要用于非手機(jī)端開發(fā)。參數(shù)傳遞機(jī)制，這部分內(nèi)容是在調(diào)用其他三部分時(shí)被使用的，但是因?yàn)檫@個(gè)機(jī)制，調(diào)用 API 的功能顯得很強(qiáng)大，可以實(shí)現(xiàn)各種參數(shù)的設(shè)置和回調(diào)，提高了軟件的靈活性和可讀性。所以在解釋其他部分函數(shù)時(shí)，需要首先了解第四部分的內(nèi)容。

Worklight 方法的調(diào)用機(jī)制

在所有的異步調(diào)用中，都需要傳遞一個(gè) options 對(duì)象給函數(shù)，這個(gè)對(duì)象有三個(gè)公共屬性，對(duì)于所有的函數(shù)來(lái)說(shuō)都會(huì)使用，它們分別是 onSuccess，onFailure，invocationContext，相應(yīng)的格式如清單 1 所示：

清單 1. options 對(duì)象

options = {  
onSuccess: success-handler-function (response),  
onFailure: failure-handler-function (response),  
invocationContext: invocation-context  
};  

屬性 onSuccess 是一個(gè)回調(diào)函數(shù)，當(dāng)異步調(diào)用成功時(shí)，這個(gè)函數(shù)被執(zhí)行。參數(shù) response 是一個(gè)對(duì)象，在不同的異步函數(shù)中內(nèi)容不同，不過(guò)基本的參數(shù)包括兩項(xiàng)：invocationContext 是傳遞過(guò)去的 options 中的內(nèi)容；status 是異步調(diào)用的成功后返回的結(jié)果狀態(tài)。

屬性 onFailure 也是一個(gè)回調(diào)函數(shù)，當(dāng)異步調(diào)用失敗時(shí)（無(wú)論是客戶端失敗還是服務(wù)器端失?。@個(gè)函數(shù)被執(zhí)行。參數(shù) response 是一個(gè)對(duì)象，包括的基本參數(shù)四項(xiàng)，除了 invocationContext 和 status 外，還有 errorCode 和 errorMessage。***項(xiàng)是在 Worklight 中已經(jīng)定義的錯(cuò)誤類型字段；第二項(xiàng)則是錯(cuò)誤的具體信息，由服務(wù)器提供。

屬性 invocationContext 是一個(gè)存放異步函數(shù)上下文信息的地方。當(dāng)調(diào)用結(jié)果從服務(wù)器返回的時(shí)候，需要通過(guò)它來(lái)確認(rèn)客戶端調(diào)用的函數(shù)，完成回調(diào)的過(guò)程。

當(dāng)然這三個(gè)屬性中的內(nèi)容會(huì)因?yàn)檎{(diào)用函數(shù)的不同有差異，在具體用到相應(yīng)函數(shù)時(shí)，可以通過(guò)查看相應(yīng)函數(shù)的說(shuō)明，了解內(nèi)容的擴(kuò)充情況，實(shí)現(xiàn)各自功能。

客戶端 API 的實(shí)現(xiàn)

為了展現(xiàn) Worklight 客戶端 API 的豐富功能，本文將通過(guò)一個(gè)實(shí)際的應(yīng)用來(lái)描述它的作用。

在應(yīng)用創(chuàng)建后（應(yīng)用名稱為：ClientAPIApp），對(duì) ClientAPIApp.html 文件中的 WL.Client.init 函數(shù)進(jìn)行修改，修改后的內(nèi)容如清單 2 所示：

清單 2. Worklight 客戶端初始化

WL.Client.init({showLogger: true, timeout: 10000, heartBeatIntervalInSecs: 60})  

從代碼中可以看到，程序啟動(dòng)后將自動(dòng)啟動(dòng)日志系統(tǒng)；每六十秒和服務(wù)器進(jìn)行一次連接，判定網(wǎng)絡(luò)是否通順；在獲取外部系統(tǒng)內(nèi)容時(shí)，***的等待時(shí)間為 10 秒。在啟動(dòng)應(yīng)用后，通過(guò) preview 界面顯示應(yīng)用，然后等待六十秒，在瀏覽器的窗口可以看到如下日志：

圖 1. 日志窗口

日志窗口的***兩行信息如下：

清單 2. 不同平臺(tái)下心跳日志

瀏覽器 
 - Request [/apps/services/api/ClientAPIApp/common/0/heartbeat]  
 
 - response [/apps/services/api/ClientAPIApp/common/0/heartbeat] success:  
 
 Android 模擬器 
 Request [http://yourip/apps/services/api/ClientAPIApp/android/0/heartbeat]  
 
 response [http://yourip/apps/services/api/ClientAPIApp/android/0/heartbeat]  
 success:  

創(chuàng)建 Android 的環(huán)境代碼，并且在模擬器上運(yùn)行，相應(yīng)的內(nèi)容將被打印在 Android 模擬器的日志系統(tǒng)中，這就說(shuō)明在 Worklight 的日志系統(tǒng)中，相同的日志會(huì)根據(jù)不同的平臺(tái)情況，被記錄在不同地方。為了更好的說(shuō)明這個(gè)問題，在本文的例子中，將在不同地方加入日志，并且查看在不同環(huán)境 下的顯示方式。

與初始化相對(duì)應(yīng)的一個(gè)函數(shù)是重啟函數(shù)，它的格式很簡(jiǎn)單 WL.Client.reloadApp()，作用就是重新讀入主頁(yè)面，執(zhí)行初始化的工作。

接下來(lái)是將公有控件添加到應(yīng)用中，在 Worklight 中比較常用的公有控件有三個(gè)（適應(yīng)于 iPhone 和 Android），分別是等待提示、標(biāo)簽欄、和對(duì)話框。等待提示的主要作用就是在發(fā)送異步調(diào)用時(shí)鎖住界面，防止用戶進(jìn)行其他的操作。

在 Worklight 中創(chuàng)建等待提示比較簡(jiǎn)單，需要設(shè)定兩個(gè)參數(shù)：分別是鎖定的界面節(jié)點(diǎn)和顯示內(nèi)容的參數(shù)設(shè)定。在本例中，界面為全部界面，所以節(jié)點(diǎn)為 null，設(shè)置的參數(shù)包括顯示的文字 text，窗口的透明度 opacity，以及用于顯示等待提示的跳躍效果參數(shù) bounceAnimation。

標(biāo)簽欄的設(shè)置稍微復(fù)雜一點(diǎn)，在 iPhone 和 Android 環(huán)境中，標(biāo)簽欄的實(shí)現(xiàn)是不同的，前者依靠系統(tǒng)自帶的本地控件，后者依靠 web 的實(shí)現(xiàn)方式，所以在 Android 中實(shí)現(xiàn)標(biāo)簽欄，需要設(shè)置一個(gè)父親節(jié)點(diǎn)，并且是在初始化控件之前。標(biāo)簽欄還有一點(diǎn)需要注意的是代碼的位置，在文件系統(tǒng)中，代碼將被放入環(huán)境所在的那個(gè) JavaScript 文件中（圖 2 中綠色框處），這樣才可以在運(yùn)行特定環(huán)境的代碼時(shí)有效果。

圖 2. 標(biāo)簽欄代碼位置

在標(biāo)簽欄的初始化完畢后，需要將不同的標(biāo)簽添加到頁(yè)面中，添加標(biāo)簽的函數(shù)需要定制四個(gè)參數(shù)：標(biāo)簽的 ID，回調(diào)函數(shù)，標(biāo)簽的名稱和圖片的位置。標(biāo)簽的 ID 用一個(gè)字符串來(lái)唯一標(biāo)示標(biāo)簽；回調(diào)函數(shù)用于定義在用戶點(diǎn)擊該標(biāo)簽時(shí)所相應(yīng)的事件；標(biāo)簽名稱為標(biāo)簽頁(yè)顯示的文字內(nèi)容；圖片位置在 iPhone 和 Android 中又不同，前者是指定圖標(biāo)的位置或者系統(tǒng)默認(rèn)支持的一些圖標(biāo)的名稱；后者就是指定圖標(biāo)的位置，包括選中和不選中時(shí)顯示的圖片。

標(biāo)簽欄在 Android 版本中還有一個(gè)需要特別注意的問題：因?yàn)闃?biāo)簽欄生成的頁(yè)面會(huì)掩蓋其余的 web 內(nèi)容，所以需要將其他內(nèi)容的 margin-top 設(shè)置為標(biāo)簽欄的高度，這樣就可以不被標(biāo)簽欄遮蓋。

***一個(gè)是對(duì)話框，對(duì)話框統(tǒng)一的定制三個(gè)參數(shù)：title 定義對(duì)話框的標(biāo)題；text 定義對(duì)話框的說(shuō)明文字；buttons 是一個(gè)數(shù)組，里面均為 JSON 對(duì)象，在對(duì)象中包含了兩個(gè)參數(shù)：btext 為按鈕的顯示名稱，handler 為按鈕點(diǎn)擊時(shí)擊發(fā)的事件函數(shù)。這個(gè)數(shù)組的***有效容量是三個(gè)，當(dāng)長(zhǎng)度超過(guò)三時(shí)，余下的數(shù)據(jù)均無(wú)效。

完成了公共控件的構(gòu)造后，就需要通過(guò)簡(jiǎn)單的按鈕觸發(fā)，來(lái)測(cè)試一些常用的功能。首先，在手機(jī)應(yīng)用中，會(huì)打開一些外部的網(wǎng)頁(yè)，比如一個(gè)企業(yè)的手機(jī)應(yīng)用， 可以內(nèi)置企業(yè)的官方手機(jī)網(wǎng)站，便于用戶的查看。但是利用 JavaScript 技術(shù)打開網(wǎng)頁(yè)的效果會(huì)因?yàn)槭謾C(jī)系統(tǒng)的不同而不同，所以利用 Worklight 封裝的 WL.App.openURL 函數(shù)，可以在程序之外，利用系統(tǒng)自帶的 safari 瀏覽器打開一個(gè)新的網(wǎng)頁(yè)。

然后是測(cè)試網(wǎng)絡(luò)情況的函數(shù)，在判斷手機(jī)是否和網(wǎng)絡(luò)連接，并且根據(jù)不同的網(wǎng)絡(luò)情況使用不同的策略實(shí)現(xiàn)代碼，都可以通過(guò) WL.Device.getNetworkInfo (callback) 函數(shù)來(lái)獲取信息。這個(gè)函數(shù)通過(guò)調(diào)用后返回的數(shù)據(jù)，檢測(cè)各種網(wǎng)絡(luò)情況。需要注意的是 WL.Client.isConnected() 這個(gè)函數(shù)已經(jīng)被 deprecated 了，所以建議在開發(fā)時(shí)不用這個(gè)函數(shù)來(lái)檢測(cè)是否和服務(wù)器連接。

***一個(gè)需要介紹的功能函數(shù)是 WL.App.close()，在不同的手機(jī)應(yīng)用平臺(tái)上，應(yīng)用關(guān)閉會(huì)有不同的方式，這不符合跨平臺(tái)應(yīng)用的需求。通過(guò)這個(gè)簡(jiǎn)單的函數(shù)，應(yīng)用就能被關(guān)閉，然后回到主界面，或者應(yīng)用被調(diào)用的地方。

在介紹了這些功能后，Worklight 的客戶端還提供了如下的的一些函數(shù)，WL.Client.getEnvironment() 用于獲取程序運(yùn)行的環(huán)境，但是在原則上利用 Worklight 的環(huán)境設(shè)置，而不是用這個(gè)函數(shù)去定制不同環(huán)境的代碼；WL.Client.getAppProperty() 可以獲取例如應(yīng)用名稱的數(shù)據(jù)，提供一些輔助的信息；WL.App.getDeviceLocale() 和 WL.App.getDeviceLanguage() 函數(shù)提供了系統(tǒng)的地區(qū)信息和語(yǔ)言信息，根據(jù)這兩項(xiàng)可以對(duì)應(yīng)相應(yīng)的 message 文件，來(lái)完成應(yīng)用多國(guó)化的支持。這些函數(shù)在本文的例子中都有涉及，可以查看如何使用。

結(jié)束語(yǔ)

在混合模式下開發(fā)良好的應(yīng)用，就需要對(duì) Worklight 的客戶端 API 有足夠的了解。本文介紹了很多常用的 API，實(shí)現(xiàn)了在客戶端提供對(duì)公共控件的支持、多語(yǔ)言環(huán)境的支持和根據(jù)網(wǎng)絡(luò)情況進(jìn)行不同代碼實(shí)現(xiàn)的支持。對(duì)于常用的調(diào)用外部系統(tǒng)的函數(shù)，可以查閱 《開始 Worklight 的開發(fā)之旅》 和 《 Worklight 中適配器的開發(fā)》 獲得詳細(xì)的信息。

在熟悉了這些 API 后，開發(fā)者可以利用 Worklight 提供的 LOG 和日志機(jī)制，記錄運(yùn)行時(shí)觸發(fā)的各種日志信息，用于系統(tǒng)后期的調(diào)優(yōu)、錯(cuò)誤修復(fù)和數(shù)據(jù)統(tǒng)計(jì)。