使用Cordova API開發(上)

到目前爲止咱們已經瞭解瞭如何搭建Cordova開發環境及如何使用Cordova和移動平臺開發商提供的工具。之後的部分將討論更多的關於Cordova編程方面的內容。這裏介紹Cordova APIs，及在應用中如何使用。

本文承接上篇《使用PhoneGap Build》。

對API自己不會太深刻，關於這些內容請參考官方API文檔，主要演示如何在應用中使用。

Cordova核心API

Hybrid應用比web應用強大之處在於可使運行在容器中的web內容訪問native APIs。Cordova提供了用於移動設備上的API的子集，包括：

• 加速度計(Accelerometer)
• 相機(Camera)
• 錄製(Capture)
• 指南針(Compass)
• 網絡鏈接(Connection)
• 聯繫人(Contacts)
• 設備(Device)
• 事件(Events)
• 文件(File)
• 地理定位(Geolocation)
• 全球化(Globalization)
• 內置瀏覽器(InAppBrowser)
• 多媒體(Media)
• 消息提醒(Notification)
• 閃屏(Splashscreen)
• 存儲(Storage)

某些情景中，API模仿已經由現代瀏覽器提供的能力；大多數狀況下，應用使用內嵌在Cordova容器中的native瀏覽器、webView提供的API。對於沒有在瀏覽器上實現提供API的平臺，Cordova開發團隊會實現這個API,這樣在全部支持的平臺上均可以使用了。能夠看看Cordova地理定位(Geolocation)、文件(File)或存儲(Storage)API。它們在大多數平臺上的實現都很標準，實現時不用作太多處理。

而文件和存儲的API已經成爲移動瀏覽器的標準，Geolocation也是這種狀況，可是以後會談到的"硬件API"部分涉及到的API和它相似，因此也會談到些。Contacts API也是基於這種標準的，可是由於比較特殊須要說明一下。

以前提到過全部的核心API在3.0版本以後都從Cordova容器中移除並以插件的形式實現。所以須要在項目中使用以下命令關聯插件：

cordova plugin add path_to_plugin

例如要使用Camera API，使用以下命令添加相機功能：

cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-camera.git

這樣就把相機插件從公共Git資源庫下載下來了，若是插件位於本地，好比"d:\cordova\"下，path_to_plugin替換成本地存儲路徑。

cordova plugin add d:\cordova\cordova-plugin-camera

更多這方面的內容請參考《使用Cordova命令行》。

使用API的Cordova文檔

由於有開發團隊一直在維護Cordova容器、API和插件，而且有專門的團隊在努力維護文檔，因此它的的API文檔寫的很好，在構建Cordova應用時值得花些時間閱讀。在線文檔地址在www.cordova.io，文檔連接在頁面的下面，連接指向適當的語言和最近發佈的框架版本。文檔頁面右上方有下拉列表能夠選擇不一樣的版本。

使用API開發時，要注意在文檔中說明的每一個API特別之處。雖然Cordova開發團隊盡力在跨平臺上保存API的一致性，在一些平臺上實現的某些功能是不可用的，或者並非要實現的狀態。碰到使用Cordova API不盡如人意的地方能夠去文檔中檢查一下API的特別說明。

設置應用許可

大多數Cordova API使用navtive API,許多都有安全限制。出於保護用戶和設備考慮，開發者在部署到設備上時要設置應用配置。這些設置配置了native應用容器，由它在安裝時通知操做系統使用了有某些限制的API。這樣操做系統在安裝時會彈出是否容許應用的API。

以下圖是在安裝HelloCordova應用時出現的提示：

若是某個API或功能在平臺上不可用，或者被用戶禁用了，使用它的應用在執行這部分時會失敗且不會給出提示。設想一下這種狀況應用會拋出某種異常，可是由於沒有處理的case，所以在執行時會跳過執行這個API。若是在實現某個功能而且只是不工做而不給出任何提示時，檢查一下應用權限設置。

要了解應用中使用的API須要什麼樣的配置設置，要參考具體的API的文檔。下圖是一個Camera API文檔頁面，其中包括叫"Accessing the Feature"的部分，描述了怎樣向項目中添加API和在應用中使用API時要作怎樣的配置設備。

如上圖說明了在每一個支持的平臺上須要更新的配置文件，以及啓用功能時文件中要添加的內容。配置文件一般是config.xml文件，平臺不一樣位置不一樣。

幸虧Cordova CLI能夠爲咱們管理設置應用權限。若是用CLI添加插件，它會在config.xml中爲項目中全部平臺做了一些配置改動。以下面的配置文件所示(添加camera再粘一遍)：

<?xml version='1.0' encoding='utf-8'?>
<widget id="io.cordova.hellocordova" version="0.0.1" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
    <name>HelloCordova</name>
    <description>
        A sample Apache Cordova application that responds to the deviceready event.
    </description>
    <author email="dev@cordova.apache.org" href="http://cordova.io">
        Apache Cordova Team
    </author>
    <content src="index.html" />
    <plugin name="cordova-plugin-whitelist" version="1" />
    <access origin="*" />
    <allow-intent href="http://*/*" />
    <allow-intent href="https://*/*" />
    <allow-intent href="tel:*" />
    <allow-intent href="sms:*" />
    <allow-intent href="mailto:*" />
    <allow-intent href="geo:*" />
    <platform name="android">
        <allow-intent href="market:*" />
    </platform>
    <platform name="ios">
        <allow-intent href="itms:*" />
        <allow-intent href="itms-apps:*" />
    </platform>
</widget>

到這裏討論了全部背景知識，開始討論API。

Cordova對象

一些Cordova API並非必要的，然而它們對於Cordova應用也是有用的對象。好比connection和device，下面對它們作下介紹而且在說明如何在應用中使用。

Connection類型

移動應用時常須要知道可用網絡鏈接的類型。由於網絡服務商在對超出的數據流量要收取費用，應用在進行數據量大的升級時建議使用收費低的Wifi而不要使用蜂窩移動網絡。最佳實踐是開發者對應用使用的數據使用類型作出分類，以便在寫代碼時使用數據流量費用最少。對於這種狀況Cordova提供了connection對象用來識別當前可用的網絡鏈接。使用前首先添加插件：

cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-network-information.git

在代碼適當的位置，經過如下js代碼肯定鏈接類型：

var ct = navigator.connection.type;

接下來能夠把ct的值和預約義的鏈接類型屬性的作值對比：

• Connection.CELL
• Connection.CELL_2G
• Connection.CELL_3G
• Connection.CELL_4G
• Connection.ETHERNET
• Connection.NONE
• Connection.UNKOWN
• Connection.WIFI

應用使用網絡前要肯定是否有網絡鏈接，能夠這麼寫：

ct = navigator.connection.type;
if (ct != Connection.None) {
    console.log("You have a connection");
    // 使用網絡的代碼

} else {
    // 警告用戶沒有網絡鏈接沒法進行
}

應用在每次要知道網絡的狀態是要查詢connection對象，前面的ct變量在網絡狀態變化時不會繼續維持一個有效狀態值。以後會涉及到相關事件能夠看到如何監視網絡鏈接。

或者要檢查某個網絡類型，能夠這麼寫：

ct = navigator.connection.type;
if (ct == Connection.WIFI) {
    console.log("You have a WIFI Connection");
    // 使用WIFI的的代碼功能
} else {
    // 警告用戶沒有WIFI沒法繼續
}

應用可使用online和offline事件監視網絡的實時狀態(稍後介紹)。

Device

device對象能夠用來肯定設備的有限數量的信息。可用的設備屬性以下：

• device.name
• device.cordova
• device.platform
• device.uuid
• device.verson
• device.model

使用前安裝device插件，在《Cordova應用解析中》對它有描述。

警告用戶

開發者常常要通知用戶一些活動的狀況。web應用能夠在頁面內部或以HTML彈出框顯示這些信息。但有時候須要開發者管理這種提示。有兩種類型的提示，姑且稱之爲hardware notifications和visual notifications，下面分別說明。

Hardware Nofifications

大多數智能手機爲開發者提供了讓設備蜂鳴或振動的API，Cordova也提供了相同的調用接口。使用前要安裝，命令以下：

cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-vibration.git

Beep

要使用設備的蜂鳴，應用要調用navigator.notification.beep方法，振動要調用navigator.notification.vibrate方法。每一個都帶一個參數，用來控制提示要持續多久或發生多少次。beep方法的參數用來控制方法調用時設備蜂鳴多少次：

navigator.notification.beep(quantity);

Vibrate

vibrate方法接受一個持續時間參數，單位是毫秒：

navigator.notification.vibrate(duration);

Visual Notification

web應用能夠調用Cordova的一些方法與用戶交互，固然可使用js的alert()、confirm()和prompt()方法，可是Cordova的方法是異步的，而且對顯示內容有更大的控制權限。

使用前先安裝插件，命令以下：

cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-dialog.git

Alert()

不一樣於js中的alert()方法，Cordova的alert()方法以下：

navigator.notification.alert("This is a Cordova Alert()", myCallback, "Alert Test", "Click Me");

這樣能夠設置對話框標題和按鈕文本。js alert()方法是同步的而Cordova alert()方法是異步的，也就是說js警告會立刻顯示，而Cordova警告在Cordova容器準備好後顯示，方法以下：

naviator.notification.alert(message, callback, [title], [buttonLabel])

callback參數定義了點擊對話框中按鈕時調用的函數，應用在用戶點擊按鈕以前是空閒狀態，點擊執行回調函數。若是把callback參數設爲null,則應用在警告彈出以後繼續執行而不會等用戶點擊按鈕。

title和buttonLabel參數都是可選的。

Confirm

confirm方法與alert方法類似，但它能夠指定多個按鈕的標籤，而且callback方法傳入了幾個值用來指明點擊了哪一個按鈕。方法聲明以下：

navigator.notification.confirm(message, callback,[title],[buttonLabels]);

如下代碼段說明了怎樣使用confirm方法：

navigator.notification.confirm('Do you want to continue?', doContinue, 'Please confirm', 'Yes, No');

function doContinue(buttonNum) {
    navigator.nofication.alert('You chose option #' + 'buttonNum + '?', null, 'Really?', 'Yes');
};

傳遞給回調函數的參數是數值型，指出點擊了哪一個按鈕，若是點擊第1個按鈕回調函數接受1，點擊第2個則接受2，依次類推。

Prompt

Prompt收集來自表單外部的用戶信息。調用函數聲明以下：

navigator.notification.prompt(message, callback, [title], [buutonLabels], [defaultText]);

一樣中括號中的參數是可選的。調用prompt方法並定義處理用戶輸入的回調函數。

navigator.notification.prompt('Please enter your nickname', gotData, 'NickName', ['Cancel', 'OK'], 'Jimmy');

function gotData(res) {
    navigator.notification.alert('You chose option #" + res.buttonIndex + '\nYou entered: ' + res.input1, null, "Results' + 'OK');
};

注意prompt使用了和confirm不一樣的按鈕標籤格式。prompt使用字符串數組，而confirm使用逗號分隔的字符串。

Cordova事件

Cordova框架了一組事件，開發者用來對某些運行Cordova應用的設備上的事件做出反應。事件處理的一種狀況是硬件相關活動，如電池狀態變化或用戶按了某個物理按鈕；另外一種狀況是應用程序狀態的變化，如應用被停止或恢復。這些web應用使用的事件同Native應用使用的是同樣的。

完整的支持的事件列表以下：

Cordova 事件	描述
backbutton	用戶按設備後退鍵時觸發
batterycritical	電池達到關鍵狀態時觸發。關鍵狀態的定義因平臺而異
batterylow	電池低電量狀態時觸發。低電量狀態的定義因平臺而異
batterystatus	電池狀態至少改變1%時時觸發(增長或減小)
deviceready	cordova容器完成初始化時觸發
endcallbutton	在用戶按手機的結束通話鍵時觸發
menubutton	在用戶按手機的菜單鍵時觸發
offline	在設備失去網絡鏈接時觸發
online	在設備由沒有網絡鏈接轉換到鏈接狀態時觸發
pause	Cordova應用被掛起時觸發。通常發生在用戶跳轉到另外一個應用，系統把當前應用放在後臺時
resume	在被掛起的應用轉到前臺時觸發
searchbutton	在用戶按查找鍵時觸發
startcallbutton	在用戶按通話鍵時觸發
volumedownbutton	用戶按音量減小鍵時觸發
volumnupbutton	用戶按音量鍵增長時觸發

老式手機使用物理按鈕來撥通和結束通話。在較新的設備上，這些按鈕被移除並用虛擬按鍵代替。虛擬按鍵只在用到(如菜單和查找按鍵)，或只用於某些應用(像電話按鍵)。

大多數的列出的事件都在Cordova容器中實現了。只有電池狀態以插件形式實現了。要使應用可以監視電池事件必須首先添加電池狀態插件：

cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin=battery-status.git

其中device事件在《cordova應用解析》討論過。

要監視這些事件能夠簡單的在應用中爲某個事件註冊監聽器。

document.addEventListener("eventName", eventFunction);

如要監聽是否斷開網絡鏈接，能夠註冊offline事件的監聽器：

document.addEventListener("offline", isOffline);

function isOffline() {
    // 斷開網絡鏈接時的動做
}

事件在不一樣的移動平臺上並不都準確的定期望的狀況觸發，須要在不一樣設備上測試確保應用定期望的工做。