事件

Events

“

PhoneGap整个生命周期内触发的事件。

事件类型：

backbutton

当用户在Android系统上点击后退按钮的时候触发此事件。

复制

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

详述：

如果你需要在Android系统上重载默认后退按钮的行为，可以通过注册一个事件监听器来监听“backbutton”事件。它不再需求调用任何其他方法来重载后退按钮行为，现在你只需要为“backbutton”事件注册一个事件监听器。

通常情况下，你需要在接收到PhoneGap的“deviceready”事件后，使用document.addEventListener来附加该事件监听器。

支持的平台：

Android
BlackBerry WebWorks (OS 5.0 或更高)

简单的范例：

复制

document.addEventListener("backbutton", onBackKeyDown, false);
	
function onBackKeyDown() {
   // 处理后退按钮操作
}

完整的范例：

复制

	
PhoneGap Device Ready Example

batterycritical

当PhoneGap应用程序发现电池电量降低到临界点时会触发此事件。

复制

window.addEventListener("batterycritical", yourCallbackFunction, false);

详述：

当PhoneGap应用程序发现电池电量降低到临界点百分比时会触发此事件，临界点的值由设备指定。

batterycritical管理程序将调用一个对象，该对象包含以下两个属性：

level：电池剩余电量的百分比，取值范围是0-100。(数字类型)
isPlugged：boolean型的值，表示设备是否接通电源。

通常情况下，你会希望一旦接收到PhoneGap的“deviceready”事件就使用document.addEventListener附加一个事件监听器。

支持的平台：

iOS
Android
BlackBerry WebWorks (OS 5.0 或更高)

简单的范例：

复制

window.addEventListener("batterycritical", onBatteryCritical, false);

function onBatteryCritical(info) {
    //处理电池电量不足的事件。
    alert("Battery Level Critical " + info.level + "%\nRecharge Soon!"); 
}

完整的范例：

复制

	
PhoneGap Device Ready Example

batterylow

当PhoneGap应用程序发现电池降到一个较低水平值时触发此事件。

复制

window.addEventListener("batterylow", yourCallbackFunction, false);

详述：

当PhoneGap应用程序发现电池降到一个较低水平值时触发此事件，该值由设备指定。

batterylow的处理程序将会调用一个对象，该对象包含以下两个属性：

level：电池剩余电量的百分比，取值范围是0-100。(数字类型)
isPlugged：boolean型的值，表示设备是否接通电源。

通常情况下，你会希望一旦接收到PhoneGap的“deviceready”事件就使用document.addEventListener附加一个事件监听器。

支持的平台：

iOS
Android
BlackBerry WebWorks (OS 5.0 或更高)

简单的范例：

复制

window.addEventListener("batterylow", onBatteryLow, false);

function onBatteryLow(info) {
    // 处理电池电量低的事件
    alert("Battery Level Low " + info.level + "%"); 
}

完整的范例：

复制

	
PhoneGap Device Ready Example

batterystatus

当PhoneGap应用程序发现电池状态发生改变时触发此事件。

复制

window.addEventListener("batterystatus", yourCallbackFunction, false);

详述：

当PhoneGap应用程序发现电池电量至少发生百分之一的改变时会触发此事件，另外当设备连接或者断开电源时也会触发此事件。

batterystatus的处理程序会调用一个对象，该对象包含两个属性：

level：电池剩余电量的百分比，取值范围是0-100。(数字类型)
isPlugged：boolean型的值，表示设备是否接通电源。

通常情况下，你会希望一旦接收到PhoneGap的“deviceready”事件就使用document.addEventListener附加一个事件监听器。

支持的平台：

iOS
Android
BlackBerry WebWorks (OS 5.0 或更高)

简单的范例：

复制

window.addEventListener("batterystatus", onBatteryStatus, false);

function onBatteryStatus(info) {
    // 处理电池状态发生改变的事件
    console.log("Level: " + info.level + " isPlugged: " + info.isPlugged); 
}

完整的范例：

复制

	
PhoneGap Device Ready Example

deviceready

当PhoneGap被完全加载后会触发该事件。

复制

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

详述：

这是每个PhoneGap应用程序都会用到的重要事件。

PhoneGap包含两套代码库：本地代码库和JavaScript代码库。当本地代码加载时会显示一个自定义的加载图片，但是，JavaScript只是在DOM加载后就被加载。这潜在的说明用户的Web应用程序可以在PhoneGap加载完成之前调用相应的JavaScript函数。

PhoneGap一旦完全加载就会触发deviceready事件。当设备触发该事件后，用户就可以安全进行PhoneGap函数调用。

通常情况下，你会希望在HTML文件的DOM加载完毕后使用document.addEventListener附加一个事件监听器。

支持的平台：

Android
BlackBerry WebWorks (OS 5.0或更高版本)
iPhone

简单的范例：

复制

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

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

完整的范例：

复制

	
PhoneGap Device Ready Example

BlackBerry (OS 4.6) 的特异情况：

RIM的BrowserField(网页浏览器视图)不支持自定义事件，所以deviceready事件不会被触发。

一种解决方法是一直手动查询PhoneGap.available方法直到PhoneGap完全加载完毕。

复制

function onLoad() {
	// BlackBerry OS 4浏览器不支持自定义事件。
	// 因此通过手动方式等待，直到PhoneGap加载完毕。
	var intervalID = window.setInterval(
		function() {
	 		if (PhoneGap.available) {
		 	window.clearInterval(intervalID);
		 	onDeviceReady();
	 	}
 	},
 	500
	);
}

function onDeviceReady() {
	// 现在可以安全地调用PhoneGap API
}

menubutton

当用户在Android系统上点击菜单按钮的时候触发此事件。

复制

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

详述：

如果你需要在Android系统上重载默认菜单按钮的行为，可以通过注册一个事件监听器来监听“menubutton”事件。

通常情况下，你需要在接受到PhoneGap的“deviceready”事件后，使用document.addEventListener来附加该事件监听器。

支持的平台：

Android
BlackBerry WebWorks (OS 5.0 或更高)

简单的范例：

复制

document.addEventListener("menubutton", onMenuKeyDown, false); 
 
function onMenuKeyDown() { 
	//处理菜单按钮操作 
}

完整的范例：

复制

	
PhoneGap Device Ready Example

startcallbutton

当用户按下通话按钮时会触发该事件。

复制

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

详述：

如果你需要重写默认的通话行为，你可以注册一个监听器用来监听"startcallbutton"事件。

通常情况下，你需要在接受到PhoneGap的“deviceready”事件后，使用document.addEventListener来附加该事件监听器。

支持的平台：

BlackBerry WebWorks (OS 5.0 或更高)

简单的范例：

复制

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

function onStartCallKeyDown() {
    //处理通话按钮操作
}

完整的范例：

复制

	
PhoneGap Device Ready Example

endcallbutton

当用户按下挂机按钮时会触发该事件。

复制

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

详述：

如果你需要重写默认的挂机行为，你可以注册一个监听器用来监听"endcallbutton"事件。

通常情况下，你需要在接受到PhoneGap的“deviceready”事件后，使用document.addEventListener来附加该事件监听器。

支持的平台：

BlackBerry WebWorks (OS 5.0 或更高)

简单的范例：

复制

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

function onEndCallKeyDown() {
    // 处理挂机事件
}

完整的范例：

复制

	
PhoneGap Device Ready Example

volumedownbutton

当用户按下减小音量按钮时会触发该事件。

复制

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

详述：

如果你需要重写默认的减小音量行为，你可以注册一个监听器用来监听"volumedownbutton"事件。

通常情况下，你需要在接受到PhoneGap的“deviceready”事件后，使用document.addEventListener来附加该事件监听器。

支持的平台：

BlackBerry WebWorks (OS 5.0 或更高)

简单的范例：

复制

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

function onVolumeDownKeyDown() {
    // 处理声音减小按钮的事件
}

完整的范例：

复制

	
PhoneGap Device Ready Example

volumeupbutton

当用户按下加大音量按钮时会触发该事件。

复制

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

详述：

如果你需要重写默认的加大音量行为，你可以注册一个监听器用来监听"volumeupbutton"事件。

通常情况下，你需要在接受到PhoneGap的“deviceready”事件后，使用document.addEventListener来附加该事件监听器。

支持的平台：

BlackBerry WebWorks (OS 5.0 或更高)

简单的范例：

复制

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

function onVolumeUpKeyDown() {
    // 处理声音增大按钮事件
}

完整的范例：

复制

	
PhoneGap Device Ready Example

pause

当PhoneGap应用程序被放到后台的时候触发此事件。

复制

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

详述：

PhoneGap包含两套代码库：本地代码库和JavaScript代码库。当本地代码将应用程序放到后台的时候会触发pause事件。

通常情况下，你会希望一旦接收到PhoneGap的“deviceready”事件就使用document.addEventListener附加一个事件监听器。

支持的平台：

Android
BlackBerry WebWorks (OS 5.0或更高版本)
iPhone

简单的范例：

复制

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

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

完整的范例：

复制

	
PhoneGap Device Ready Example

iOS的特异情况：

在pause事件处理过程中，不但任何通过Objective-C的调用不会工作，而且任何交互性的调用也不会工作，比如警示功能。这意味着你不能调用console.log(及其变种)，且任何来自插件或PhoneGap的API的调用都不会有所反应。这些调用只有在应用程序恢复后才会被处理（在下一轮运行循环中处理）。

resume

当PhoneGap应用程序被恢复到前台运行的时候触发此事件。

复制

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

详述：

PhoneGap包含两套代码库：本地代码库和JaPhoneGap包含两套代码库：本地代码库和JavaScript代码库。当本地代码将应用程序从后台提取到前台运行的时候触发resume事件。
通常情况下，你会希望一旦接收到PhoneGap的“deviceready”事件就使用document.addEventListener附加一个事件监听器。

支持的平台：

Android
BlackBerry WebWorks (OS 5.0或更高版本)
iPhone

简单的范例：

复制

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

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

完整的范例：

复制

	
PhoneGap Device Ready Example

online

当PhoneGap应用程序在线（连接到因特网）的时候触发此事件。

复制

document.addEventListener("online", yourCallbackFunction, false);

详述：

当应用程序的网络连接改变为online的时候触发online事件。

通常情况下，你会希望一旦接收到PhoneGap的“deviceready”事件就使用document.addEventListener附加一个事件监听器。

支持的平台：

Android
BlackBerry WebWorks (OS 5.0或更高版本)
iPhone

简单的范例：

复制

document.addEventListener("online", onOnline, false); 
 
function onOnline() {
	// 处理online事件
}

完整的范例：

复制

	
PhoneGap Device Ready Example

iOS的特异情况：

在初次启动的情况下，第一个online事件（如果有的话）将需要至少1秒钟才被触发。

offline

当PhoneGap应用程序离线（没有连接到因特网）的时候触发此事件。

复制

document.addEventListener("offline", yourCallbackFunction, false);

详述：

当应用程序的网络连接改变为offline的时候触发offline事件。

通常情况下，你会希望一旦接收到PhoneGap的“deviceready”事件就使用document.addEventListener附加一个事件监听器。

支持的平台：

Android
BlackBerry WebWorks (OS 5.0或更高版本)
iPhone

简单的范例：

复制

document.addEventListener("offline", onOffline, false); 
 
function onOffline() {
	// 处理offline事件 
}

完整的范例：

复制

	
PhoneGap Device Ready Example

iOS的特异情况：

在初次启动的情况下，第一个offline事件（如果有的话）将需要至少1秒钟才被触发。

Searchbutton

当用户在Android系统上点击搜索按钮的时候触发该事件。

复制

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

详述：

如果你需要在Android系统上重载默认搜索按钮的行为，可以通过注册一个事件监听器来监听“searchbutton”事件。

通常情况下，你需要在接受到PhoneGap的“deviceready”事件后，使用document.addEventListener来附加该事件监听器。

支持的平台：

Android

简单的范例：

复制

document.addEventListener("searchbutton", onSearchKeyDown, false); 
 
function onSearchKeyDown() {
	// 处理搜索按钮操作
}

完整的范例：

复制

	
PhoneGap Device Ready Example