事件

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文件
// 等待设备API库加载好
//
function onLoad() {
    document.addEventListener("deviceready", onDeviceReady, false);
}

// 设备API可以使用了
//
function onDeviceReady() {
    document.addEventListener("pause", onPause, false);
    document.addEventListener("resume", onResume, false);
    document.addEventListener("menubutton", onMenuKeyDown, false);
    //给其他事件添加类似的监听
}

function onPause() {
    //处理暂停事件
}

function onResume() {
    //处理恢复事件
}

function onMenuKeyDown() {
    //处理"菜单"按钮事件
}

// 给其他事件添加类似的事件处理

注意: 应用程序通常一旦deviceready触发就应该用document.addEventListener绑定事件监听。

下面的表格列除了cordova的事件和支持的平台:

支持的平台/
事件
android blackberry10 ios Windows Phone 8 Windows
deviceready
pause
resume
backbutton
menubutton
searchbutton
startcallbutton
endcallbutton
volumedownbutton
volumeupbutton

deviceready

当Cordova完全加载好deviceready事件会触发。这个事件对每一个应用程序都是必须的。他是Cordova设备API准备好并可以访问的信号。

Cordova由两个代码库组成:原生(native)和JavaScript。一旦原生的代码加载好,自定义的加载图片就可以显示了。然而,JavaScript代码只在DOM加载后加载。这意味这webapp可能在对应的原生代码变得可用之前执行JavaScript方法。

一旦Cordova全部加载deviceready事件就会触发。一定事件出发,你可以安全的进行CordovaAPI的调用。应用程序通常一旦HTML document DOM加载完成,就会使用 document.addEventListener绑定一个事件监听。

deviceready事件和其他事件有点不同。其他事件的事件处理函数注册都是在deviceready事件出发的回调函数中立马执行。

简单的例子

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

function onDeviceReady() {
    // 现在可以安全的使用设备API
}

pause

当原生平台把应用程序放入后台这个pause事件会触发,通常是用户切换到了不同的应用程序。

简单的例子

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

function onPause() {
    // 处理pause事件
}

iOS的古怪行为

pause处理函数中,任何的CordovaAPI调用或者通过Objective-C完成的原生插件他们是不工作的,和任何的交互调用,如alertconsole.log()是一样的。只有在下一个运行时钟中,app被唤醒才会处理。

iOS的特定resign事件可作为pause的替代品,并可以检测用户启动 Lock按钮锁定设备和app在前台运行。如果app(和设备)支持多任务,这个事件了一系列pause事件是配对出现的,但是仅在iOS5。事实上,在支持多任务的iOS5中,所有被锁的应用程序都被推送到了后台。对于应用程序来说挡在iOS中被锁任然在运行的,让多任务不可用可以设置UIApplicationExitsOnSuspendYES。在iOS锁定时运行,这个设置无效。

resume

当原生平台将应用程序从后台运行拉出resume事件就会触发。

简单的例子

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

function onResume() {
    // 处理resume事件
}

iOS的古怪行为

任何在pause事件处理函数中调用的交互方法都会在app恢复的时候执行,以resume事件作为信号。包括alerts、console.log()和其他任何来自插件和CordovaAPId的调用,他们是通过Object-C完成的。

  • active 事件

iOS的特定active事件可作为resume的替代品,并可以检测用户关闭 Lock按钮解锁设备和app在前台运行。如果app(和设备)支持多任务,这个事件了一系列resume事件是配对出现的,但是仅在iOS5。事实上,在支持多任务的iOS5中,所有被锁的应用程序都被推送到了后台。对于应用程序来说挡在iOS中被锁任然在运行的,让多任务不可用可以设置UIApplicationExitsOnSuspendYES。在iOS锁定时运行,这个设置无效。

  • resume 事件

    当从resume事件回掉中调用交互方法,比如:alert()需要用setTimeout()时间为0包裹调用,或者其他app挂起。例子:

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

Android的古怪行为

参考Android生命周期指南来获取关于resume事件在Android中古怪行为的详细信息。

backbutton(按下返回按钮)

当用户按下返回按钮事件触发,如果你需要重写默写行为你可以注册backbutton事件监听。不在需要其他调用方法来重写返回按钮的行为。

简单的例子

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

function onBackKeyDown() {
    // 返回按钮事件的事件处理函数
}

menubutton(按下菜单按钮)

当用户按下菜单按钮事件触发,如果你需要重写默写行为你可以注册menubutton事件监听。

简单的例子

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

function onMenuKeyDown() {
    // 菜单按钮事件的事件处理函数
}

searchbutton(按下搜索按钮)

Android中当用户按下搜索按钮事件触发,如果你需要重写默写行为你可以注册'searchbutton'事件监听。

简单的例子

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

function onSearchKeyDown() {
    // 搜索按钮事件的事件处理函数
}

startcallbutton(按下通话按钮)

当用户按下通话按钮事件触发,如果你需要重写默写行为你可以注册startcallbutton 事件监听。

简单的例子

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

function onStartCallKeyDown() {
    // 通话按钮事件的事件处理函数
}

endcallbutton(按下挂断通话按钮)

当用户按下挂断通话按钮事件触发,如果你需要重写默写行为你可以注册endcallbutton事件监听。

简单的例子

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

function onEndCallKeyDown() {
    // 挂断通话按钮事件的事件处理函数
}

volumedownbutton(按下降低声音按钮)

当用户按下降低声音按钮事件触发,如果你需要重写默写行为你可以注册volumedownbutton事件监听。

简单的例子

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

function onVolumeDownKeyDown() {
    // 降低声音按钮事件的事件处理函数
}

volumeupbutton(按下增加声音按钮)

当用户按下增加声音按钮事件触发,如果你需要重写默写行为你可以注册volumeupbutton事件监听。

简单的例子

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

function onVolumeUpKeyDown() {
    // 增加声音按钮事件的事件处理函数
}