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

通過這些技術，Worklight 在不同平臺上開發應用的能力大大加強。本文將首先闡述客戶端 API 的作用，然后介紹客戶端 API 的分類和調用機制中重要的 options 對象。***通過一個詳細的例子，展現客戶端 API 的能力。

客戶端 API 的作用

在混合模式下開發的手機端應用，需要處理的一個主要問題就是：通過一種合理的語言，獲取本地的信息（比如手機的類型，操作系統的版本，硬件的資源）和服務器端的信息（比如各種數據，網絡的連接情況）。同時，能夠通過一種合理的語言，創建一些公共的控件，比如對話框，這樣就可以減少在不同手機環境下，代碼的開發量。

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

表 1. 客戶端的不同選擇

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

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

客戶端 API 的分類

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

Worklight 方法的調用機制

在所有的異步調用中，都需要傳遞一個 options 對象給函數，這個對象有三個公共屬性，對于所有的函數來說都會使用，它們分別是 onSuccess，onFailure，invocationContext，相應的格式如清單 1 所示：

清單 1. options 對象

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

屬性 onSuccess 是一個回調函數，當異步調用成功時，這個函數被執行。參數 response 是一個對象，在不同的異步函數中內容不同，不過基本的參數包括兩項：invocationContext 是傳遞過去的 options 中的內容；status 是異步調用的成功后返回的結果狀態。

屬性 onFailure 也是一個回調函數，當異步調用失敗時（無論是客戶端失敗還是服務器端失敗），這個函數被執行。參數 response 是一個對象，包括的基本參數四項，除了 invocationContext 和 status 外，還有 errorCode 和 errorMessage。***項是在 Worklight 中已經定義的錯誤類型字段；第二項則是錯誤的具體信息，由服務器提供。

屬性 invocationContext 是一個存放異步函數上下文信息的地方。當調用結果從服務器返回的時候，需要通過它來確認客戶端調用的函數，完成回調的過程。

當然這三個屬性中的內容會因為調用函數的不同有差異，在具體用到相應函數時，可以通過查看相應函數的說明，了解內容的擴充情況，實現各自功能。

客戶端 API 的實現

為了展現 Worklight 客戶端 API 的豐富功能，本文將通過一個實際的應用來描述它的作用。

在應用創建后（應用名稱為：ClientAPIApp），對 ClientAPIApp.html 文件中的 WL.Client.init 函數進行修改，修改后的內容如清單 2 所示：

清單 2. Worklight 客戶端初始化

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

從代碼中可以看到，程序啟動后將自動啟動日志系統；每六十秒和服務器進行一次連接，判定網絡是否通順；在獲取外部系統內容時，***的等待時間為 10 秒。在啟動應用后，通過 preview 界面顯示應用，然后等待六十秒，在瀏覽器的窗口可以看到如下日志：

圖 1. 日志窗口

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

清單 2. 不同平臺下心跳日志

瀏覽器 
 - 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:  

創建 Android 的環境代碼，并且在模擬器上運行，相應的內容將被打印在 Android 模擬器的日志系統中，這就說明在 Worklight 的日志系統中，相同的日志會根據不同的平臺情況，被記錄在不同地方。為了更好的說明這個問題，在本文的例子中，將在不同地方加入日志，并且查看在不同環境 下的顯示方式。

與初始化相對應的一個函數是重啟函數，它的格式很簡單 WL.Client.reloadApp()，作用就是重新讀入主頁面，執行初始化的工作。

接下來是將公有控件添加到應用中，在 Worklight 中比較常用的公有控件有三個（適應于 iPhone 和 Android），分別是等待提示、標簽欄、和對話框。等待提示的主要作用就是在發送異步調用時鎖住界面，防止用戶進行其他的操作。

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

標簽欄的設置稍微復雜一點，在 iPhone 和 Android 環境中，標簽欄的實現是不同的，前者依靠系統自帶的本地控件，后者依靠 web 的實現方式，所以在 Android 中實現標簽欄，需要設置一個父親節點，并且是在初始化控件之前。標簽欄還有一點需要注意的是代碼的位置，在文件系統中，代碼將被放入環境所在的那個 JavaScript 文件中（圖 2 中綠色框處），這樣才可以在運行特定環境的代碼時有效果。

圖 2. 標簽欄代碼位置

在標簽欄的初始化完畢后，需要將不同的標簽添加到頁面中，添加標簽的函數需要定制四個參數：標簽的 ID，回調函數，標簽的名稱和圖片的位置。標簽的 ID 用一個字符串來唯一標示標簽；回調函數用于定義在用戶點擊該標簽時所相應的事件；標簽名稱為標簽頁顯示的文字內容；圖片位置在 iPhone 和 Android 中又不同，前者是指定圖標的位置或者系統默認支持的一些圖標的名稱；后者就是指定圖標的位置，包括選中和不選中時顯示的圖片。

標簽欄在 Android 版本中還有一個需要特別注意的問題：因為標簽欄生成的頁面會掩蓋其余的 web 內容，所以需要將其他內容的 margin-top 設置為標簽欄的高度，這樣就可以不被標簽欄遮蓋。

***一個是對話框，對話框統一的定制三個參數：title 定義對話框的標題；text 定義對話框的說明文字；buttons 是一個數組，里面均為 JSON 對象，在對象中包含了兩個參數：btext 為按鈕的顯示名稱，handler 為按鈕點擊時擊發的事件函數。這個數組的***有效容量是三個，當長度超過三時，余下的數據均無效。

完成了公共控件的構造后，就需要通過簡單的按鈕觸發，來測試一些常用的功能。首先，在手機應用中，會打開一些外部的網頁，比如一個企業的手機應用， 可以內置企業的官方手機網站，便于用戶的查看。但是利用 JavaScript 技術打開網頁的效果會因為手機系統的不同而不同，所以利用 Worklight 封裝的 WL.App.openURL 函數，可以在程序之外，利用系統自帶的 safari 瀏覽器打開一個新的網頁。

然后是測試網絡情況的函數，在判斷手機是否和網絡連接，并且根據不同的網絡情況使用不同的策略實現代碼，都可以通過 WL.Device.getNetworkInfo (callback) 函數來獲取信息。這個函數通過調用后返回的數據，檢測各種網絡情況。需要注意的是 WL.Client.isConnected() 這個函數已經被 deprecated 了，所以建議在開發時不用這個函數來檢測是否和服務器連接。

***一個需要介紹的功能函數是 WL.App.close()，在不同的手機應用平臺上，應用關閉會有不同的方式，這不符合跨平臺應用的需求。通過這個簡單的函數，應用就能被關閉，然后回到主界面，或者應用被調用的地方。

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

結束語

在混合模式下開發良好的應用，就需要對 Worklight 的客戶端 API 有足夠的了解。本文介紹了很多常用的 API，實現了在客戶端提供對公共控件的支持、多語言環境的支持和根據網絡情況進行不同代碼實現的支持。對于常用的調用外部系統的函數，可以查閱 《開始 Worklight 的開發之旅》 和 《 Worklight 中適配器的開發》 獲得詳細的信息。

在熟悉了這些 API 后，開發者可以利用 Worklight 提供的 LOG 和日志機制，記錄運行時觸發的各種日志信息，用于系統后期的調優、錯誤修復和數據統計。