事件

Cordova 提供了各種事件供應用程式使用。應用程式碼可以為這些事件新增監聽器。例如

HTML 檔案

<!DOCTYPE html>
<html>
    <head>
    <title>Device Ready Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova.js"></script>
    <script type="text/javascript" charset="utf-8" src="example.js"></script>
    </head>
    <body onload="onLoad()">
    </body>
</html>

JS 檔案

// example.js file
// Wait for device API libraries to load
//
function onLoad() {
    document.addEventListener("deviceready", onDeviceReady, false);
}

// device APIs are available
//
function onDeviceReady() {
    document.addEventListener("pause", onPause, false);
    document.addEventListener("resume", onResume, false);
    document.addEventListener("menubutton", onMenuKeyDown, false);
    // Add similar listeners for other events
}

function onPause() {
    // Handle the pause event
}

function onResume() {
    // Handle the resume event
}

function onMenuKeyDown() {
    // Handle the menubutton event
}

// listen for uncaught cordova callback errors
window.addEventListener("cordovacallbackerror", function (event) {
    // event.error contains the original error object
});

注意：應用程式通常應在 deviceready 事件觸發後，使用 document.addEventListener 來附加事件監聽器。

下表列出了 Cordova 事件和支援的平台

支援的平台/ 事件	android	ios
deviceready
pause
resume
backbutton
menubutton
searchbutton
startcallbutton
endcallbutton
volumedownbutton
volumeupbutton
activated
cordovacallbackerror

deviceready

當 Cordova 完全載入時，會觸發 deviceready 事件。此事件對於任何應用程式都至關重要。它表示 Cordova 的裝置 API 已載入並準備好存取。

Cordova 由兩個程式碼庫組成：原生和 JavaScript。當原生程式碼載入時，會顯示自訂的載入圖片。但是，JavaScript 僅在 DOM 載入後才會載入。這表示 Web 應用程式可能會在對應的原生程式碼可用之前呼叫 Cordova JavaScript 函式。

當 Cordova 完全載入後，會觸發 deviceready 事件。一旦事件觸發，您就可以安全地呼叫 Cordova API。應用程式通常會在 HTML 文件 DOM 載入後，使用 document.addEventListener 附加事件監聽器。

deviceready 事件的行為與其他事件略有不同。在 deviceready 事件觸發後註冊的任何事件處理常式都會立即呼叫其回呼函式。

快速範例

document.addEventListener("deviceready", onDeviceReady, false);

function onDeviceReady() {
    // Now safe to use device APIs
}

pause

當原生平台將應用程式放入背景時，通常在使用者切換到其他應用程式時，會觸發 pause 事件。

快速範例

document.addEventListener("pause", onPause, false);

function onPause() {
    // Handle the pause event
}

iOS 特性

在 pause 處理常式中，任何對 Cordova API 的呼叫或透過 Objective-C 的原生外掛都無法運作，以及任何互動式呼叫，例如警示或 console.log()。它們只會在應用程式恢復時，在下一個執行迴圈中處理。

iOS 特有的 resign 事件可以作為 pause 的替代方案，並偵測使用者何時啟用鎖定按鈕來鎖定裝置，且應用程式在前台執行。如果應用程式（和裝置）已啟用多工處理，則這會與後續的 pause 事件配對，但僅在 iOS 5 下。實際上，iOS 5 中所有已啟用多工處理的鎖定應用程式都會被推送到背景。為了使應用程式在 iOS 5 下鎖定時仍能執行，請將 [UIApplicationExitsOnSuspend][UIApplicationExitsOnSuspend] 設定為 YES 來停用應用程式的多工處理。為了在 iOS 4 上鎖定時執行，此設定並不重要。

resume

當原生平台將應用程式從背景拉出時，會觸發 resume 事件。

快速範例

document.addEventListener("resume", onResume, false);

function onResume() {
    // Handle the resume event
}

iOS 特性

從 pause 事件處理常式呼叫的任何互動式函式，會在應用程式恢復時稍後執行，如 resume 事件所表示。這些包括警示、console.log()，以及來自外掛或 Cordova API 的任何呼叫，它們會透過 Objective-C。

active 事件

iOS 特有的 active 事件可以作為 resume 的替代方案，並偵測使用者何時停用鎖定按鈕來解鎖裝置，且應用程式在前台執行。如果應用程式（和裝置）已啟用多工處理，則這會與後續的 resume 事件配對，但僅在 iOS 5 下。實際上，iOS 5 中所有已啟用多工處理的鎖定應用程式都會被推送到背景。為了使應用程式在 iOS 5 下鎖定時仍能執行，請將 [UIApplicationExitsOnSuspend][UIApplicationExitsOnSuspend] 設定為 YES 來停用應用程式的多工處理。為了在 iOS 4 上鎖定時執行，此設定並不重要。

resume 事件

從 resume 事件處理常式呼叫時，諸如 alert() 之類的互動式函式需要包裝在逾時值為零的 setTimeout() 呼叫中，否則應用程式會掛起。例如

  document.addEventListener("resume", onResume, false);
  function onResume() {
      setTimeout(function() {
              // TODO: do your thing!
          }, 0);
  }

Android 特性

請參閱 [Android Life Cycle Guide][AndroidLifeCycleGuide] 以了解有關 resume 事件的 Android 特性的詳細資訊。

backbutton

當使用者按下返回按鈕時，會觸發此事件。若要覆寫預設的返回按鈕行為，請為 backbutton 事件註冊事件監聽器。不再需要呼叫任何其他方法來覆寫返回按鈕行為。

快速範例

document.addEventListener("backbutton", onBackKeyDown, false);

function onBackKeyDown() {
    // Handle the back button
}

menubutton

當使用者按下選單按鈕時，會觸發此事件。套用事件處理常式會覆寫預設的選單按鈕行為。

快速範例

document.addEventListener("menubutton", onMenuKeyDown, false);

function onMenuKeyDown() {
    // Handle the menu button
}

searchbutton

當使用者在 Android 上按下搜尋按鈕時，會觸發此事件。如果您需要在 Android 上覆寫預設的搜尋按鈕行為，您可以為 'searchbutton' 事件註冊事件監聽器。

快速範例

document.addEventListener("searchbutton", onSearchKeyDown, false);

function onSearchKeyDown() {
    // Handle the search button
}

startcallbutton

當使用者按下開始通話按鈕時，會觸發此事件。如果您需要覆寫預設的開始通話行為，您可以為 startcallbutton 事件註冊事件監聽器。

快速範例

document.addEventListener("startcallbutton", onStartCallKeyDown, false);

function onStartCallKeyDown() {
    // Handle the start call button
}

endcallbutton

當使用者按下結束通話按鈕時，會觸發此事件。此事件會覆寫預設的結束通話行為。

快速範例

document.addEventListener("endcallbutton", onEndCallKeyDown, false);

function onEndCallKeyDown() {
    // Handle the end call button
}

volumedownbutton

當使用者按下音量降低按鈕時，會觸發此事件。如果您需要覆寫預設的音量降低行為，您可以為 volumedownbutton 事件註冊事件監聽器。

快速範例

document.addEventListener("volumedownbutton", onVolumeDownKeyDown, false);

function onVolumeDownKeyDown() {
    // Handle the volume down button
}

volumeupbutton

當使用者按下音量增大按鈕時，會觸發此事件。如果您需要覆寫預設的音量增大行為，您可以為 volumeupbutton 事件註冊事件監聽器。

快速範例

document.addEventListener("volumeupbutton", onVolumeUpKeyDown, false);

function onVolumeUpKeyDown() {
    // Handle the volume up button
}

activated

此事件不會針對 Cordova 觸發。

cordovacallbackerror

當原生回呼（成功或錯誤）擲回未捕獲的錯誤時，會觸發此事件。

這不會停止錯誤的傳播。（例如，也會觸發 window.onerror 事件。）

它與其他事件略有不同。您必須監聽 window 物件，而不是 document 物件。

event 物件具有下列屬性

error：回呼中擲回的原始 Error。

快速範例

window.addEventListener("cordovacallbackerror", function (event) {
    // event.error contains the original error object
});