事件

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 函数。

deviceready 事件在 Cordova 完全加载后触发。事件触发后，您可以安全地调用 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 特性

有关 resume 事件的 Android 特性详细信息，请参阅 [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
});