事件

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
});

注意：应用程序通常应使用 document.addEventListener 在 deviceready 后附加事件侦听器

下表列出了 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 resume 事件的特性，请参阅 [Android 生命周期指南][AndroidLifeCycleGuide]。

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
});