API Reference

Plugins

Native.js


Events

Events模块管理客户端事件,包括系统事件,如扩展API加载完毕、程序前后台切换等。

常量:

方法:

回调方法:

"plusready"

扩展API加载完成事件


				
document.addEventListener("plusready", plusreadyCallback, capture);
				
				

说明:

String 类型

为了保证扩展API的有效调用,所有应用页面都会用到的重要事件。 应用页面显示时需要首先加载扩展和API代码库,当扩展API代码库加载完成时会触发pluseready事件,当设备触发该事件后,用户就可以安全的调用扩展API。 如果程序中打开多个页面,每个都会收到此事件。

示例:


				
<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Events Example</title>
	<script type="text/javascript" >
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener("plusready", onPlusReady, false); 
function onPlusReady(){
	// 扩展API加载完毕,现在可以正常调用扩展API
	// ...... 
}
	</script>
	</head>
	<body >
	</body>
</html>
				
				

"pause"

运行环境从前台切换到后台事件


				
document.addEventListener("pause", pauseCallback, capture);
				
				

说明:

String 类型

当程序从前台切换到后台时会触发此事件。 若应用需要处理从前台切换到后台的事件行为,可通过注册事件监听器来监听“pause”事件,此事件需要在plusready事件后通过document进行注册。

示例:


				
<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Events Example</title>
	<script type="text/javascript" >
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener("plusready", onPlusReady, false); 
function onPlusReady(){
	document.addEventListener("pause", onAppPause, false);
}
function onAppPause(){
	console.log("Application paused!"); 
}
	</script>
	</head>
	<body >
	</body>
</html>
				
				

"resume"

运行环境从后台切换到前台事件


				
document.addEventListener("resume", resumeCallback, capture);
				
				

说明:

String 类型

当程序从后台切换到前台时会触发此事件。 若应用需要处理从后台切换到前台的事件行为,可通过注册事件监听器来监听“resume”事件,此事件需要在plusready事件后通过document进行注册。

示例:


				
<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Events Example</title>
	<script type="text/javascript" >
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener("plusready", onPlusReady, false); 
function onPlusReady(){
	document.addEventListener("resume", onAppReume, false);
}
function onAppReume(){
	alert("Application resumed!"); 
}
	</script>
	</head>
	<body >
	</body>
</html>
				
				

"netchange"

设备网络状态变化事件


				
document.addEventListener("netchange", netchangeCallback, capture);
				
				

说明:

String 类型

设备网络状态发生时会触发此事件。 若应用需要处理网络状态变化的事件行为,可通过注册事件监听器来监听“netchange”事件,此事件需要在plusready事件后通过document进行注册。

示例:


				
<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Events Example</title>
	<script type="text/javascript" >
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener("plusready", onPlusReady, false);
function onPlusReady(){
	document.addEventListener("netchange", onNetChange, false);  
}
function onNetChange(){
	var nt = plus.networkinfo.getCurrentType();
	switch (nt){
		case plus.networkinfo.CONNECTION_ETHERNET:
		case plus.networkinfo.CONNECTION_WIFI:
		alert("Switch to Wifi networks!"); 
		break; 
		case plus.networkinfo.CONNECTION_CELL2G:
		case plus.networkinfo.CONNECTION_CELL3G:
		case plus.networkinfo.CONNECTION_CELL4G:
		alert("Switch to Cellular networks!");  
		break; 
		default:
		alert("Not networks!"); 
		break;
	}
}
	</script>
	</head>
	<body >
	</body>
</html>
				
				

"newintent"

新意图事件


				
document.addEventListener("newintent", newintentCallback, capture);
				
				

说明:

String 类型

程序从后台被第三方程序调用并传入新意图事件。 此时程序将切换到前台运行,若应用需要处理新意图的事件行为,可通过注册事件监听器来监听“newintent”事件,此事件需要在plusready事件后通过document进行注册。

示例:


				
<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>Events Example</title>
		<script type="text/javascript" >
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener("plusready", onPlusReady, false);
function onPlusReady(){
	document.addEventListener("newintent", onNetIntent, false);
}
function onNetIntent(){
	// 获取新意图传入的参数
	var args = plus.runtime.arguments;
	// 处理意图事件
}
		</script>
	</head>
	<body >
	</body>
</html>
				
				

"plusscrollbottom"

窗口滚动到底部事件


				
document.addEventListener("plusscrollbottom", eventCallback, capture);
				
				

说明:

String 类型

当滚动Webview窗口到底部时触发此事件。

示例:


				
<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>Events Example</title>
		<script type="text/javascript" >
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener("plusready", onPlusReady, false);
function onPlusReady(){
	document.addEventListener("plusscrollbottom", onScrollToBottom, false);
}
function onScrollToBottom(){
	// 处理滚动到窗口底部事件
}
		</script>
	</head>
	<body >
	</body>
</html>
				
				

"error"

页面加载错误事件


				
document.addEventListener("error", eventCallback, capture);
				
				

说明:

String 类型

当Webview窗口加载页面失败后打开错误页面时触发此事件。 注意:此事件仅在错误页面中才触发。

示例:


				
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8"/>
    <meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
	<meta name="HandheldFriendly" content="true"/>
	<meta name="MobileOptimized" content="320"/>
	<title>Error</title>
	<script type="text/javascript">
// H5 plus事件处理
var ws=null;
function plusReady(){
	// Android处理返回键
	plus.key.addEventListener('backbutton',function(){
		(history.length==1)&&ws.close();
		var c=setTimeout(function(){
			ws.close();
		},1000);
		window.onbeforeunload=function(){
			clearTimeout(c);
		}
		history.go(-2);
	},false);
	ws=plus.webview.currentWebview();
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready',plusReady,false);
}
document.addEventListener('touchstart',function(){
    return false;
},true);
// 禁止选择
document.oncontextmenu=function(){
	return false;
};
// 获取错误信息
document.addEventListener("error",function(e){
	info.innerText="请求的页面("+e.href+")无法打开";
},false);
	</script>
	<style>
*{
	-webkit-user-select: none;
}
html,body{
	margin: 0px;
	padding: 0px;
	width: 100%;
	height: 100%;
	text-align: center;
	-webkit-touch-callout:none;
	-webkit-tap-highlight-color:rgba(0,0,0,0);
}
.button{
	width: 50%;
	font-size: 18px;
	font-weight: normal;
	text-decoration: none;
	text-align: center;
	padding: .5em 0em;
	margin: .5em auto;
	color: #333333;
	background-color: #EEEEEE;
	border: 1px solid #CCCCCC;
	-webkit-border-radius: 5px;
	border-radius: 5px;
}
.button:active{
	background-color: #CCCCCC;
}
	</style>
</head>
<body>
	<div style="width:100%;height:20%;"></div>
	<svg xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0 0 512 512" style="height:20%;"> 
	<g id="icomoon-ignore">
		<line stroke-width="1" x1="" y1="" x2="" y2="" stroke="#449FDB" opacity=""></line>
	</g>
	<path d="M256 0c-141.385 0-256 114.615-256 256s114.615 256 256 256 256-114.615 256-256-114.615-256-256-256zM352 128c17.673 0 32 14.327 32 32s-14.327 32-32 32-32-14.327-32-32 14.327-32 32-32zM160 128c17.673 0 32 14.327 32 32s-14.327 32-32 32-32-14.327-32-32 14.327-32 32-32zM352.049 390.37c-19.587-32.574-55.272-54.37-96.049-54.37s-76.462 21.796-96.049 54.37l-41.164-24.698c27.98-46.535 78.958-77.672 137.213-77.672s109.232 31.137 137.213 77.672l-41.164 24.698z" fill="#666666"></path>
    </svg>
	<p style="font-size:18px;font-weight:bolder;">We're sorry ...</p>
	<p id="info" style="font-size:12px;"></p>
	<!--<div class="button" onclick="history.back()">Retry</div>-->
	<div class="button" onclick="if(history.length == 1){ws.close();}else{ws.back();ws.back();}">Back</div>
	<div class="button" onclick="ws.close()">Close</div>
</body>
</html>
				
				

"background"

应用切换到后台运行事件


				
document.addEventListener("background", backgroundCallback, capture);
				
				

说明:

String 类型

在多应用运行环境(如流应用)中,启动一个新应用时,之前运行的应用将会自动切换到后台运行。 切换到后台运行的应用将会触发此事件。

示例:


				
<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Events Example</title>
	<script type="text/javascript" >
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener("plusready", onPlusReady, false); 
function onPlusReady(){
	document.addEventListener("background", onAppBackground, false);
}
function onAppBackground(){
	console.log("Application background!"); 
}
	</script>
	</head>
	<body >
	</body>
</html>
				
				

"foreground"

应用切换到前台运行事件


				
document.addEventListener("foreground", foregroundCallback, capture);
				
				

说明:

String 类型

在多应用运行环境(如流应用)中,应用切换到后台运行后再次被启动时,不会创建新的应用实例,而是将后台应用激活到前台运行。 此时切换到前台运行的应用将会触发foreground事件。 回调函数原型为void onForeground(e){}其中e.active表明激活应用到前台来源,可取值:"default"-默认激活方式,通常表示通过应用列表启动激活,或者关闭前一个应用后自动激活等;"stream"-通过流应用api(plus.stream.open)激活;"scheme"-通过urlscheme方式触发激活; "push"-通过点击系统通知方式触发激活; "barcode"-通过二维码扫描激活; "myapp"-通过应用收藏列表([流应用]独立App中"我的"列表)触发激活。

示例:


				
<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Events Example</title>
	<script type="text/javascript" >
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener("plusready", onPlusReady, false); 
function onPlusReady(){
	document.addEventListener("foreground", onAppForeground, false);
}
function onAppForeground(e){
	console.log("Application foreground!");
	var activeType = e.active;	// 获取激活到前台来源
}
	</script>
	</head>
	<body >
	</body>
</html>
				
				

"trimmemory"

应用需要清理内存事件


				
document.addEventListener("trimmemory", trimmemoryCallback, capture);
				
				

说明:

String 类型

在多应用运行环境(如流应用)中,可同时运行多个应用,当运行过多应用时会导致内存占用过多的情况,此时切换到后台运行的应用会收到清理内存事件。 此时应用应该释放资源来减少内存的使用(如关闭非必要的Webview窗口等)。

示例:


				
<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Events Example</title>
	<script type="text/javascript" >
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener("plusready", onPlusReady, false); 
function onPlusReady(){
	document.addEventListener("trimmemory", onAppTrimMemory, false);
}
function onAppTrimMemory(){
	console.log("Trim Memory!"); 
}
	</script>
	</head>
	<body >
	</body>
</html>
				
				

"splashclosed"

应用启动界面已关闭事件


				
document.addEventListener("splashclosed", splashClosedCallback, capture);
				
				

说明:

String 类型

应用启动后关闭启动界面时触发,不管是应用自动关闭还是调用plus.navigator.closeSplashscreen方法,都会触发此事件。

示例:


				
<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Events Example</title>
	<script type="text/javascript" >
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener("plusready", onPlusReady, false); 
function onPlusReady(){
	document.addEventListener("splashclosed", onSplashClosed, false);
}
function onSplashClosed(){
	console.log("Splash closed!"); 
}
	</script>
	</head>
	<body >
	</body>
</html>
				
				

addEventListener

添加事件监听函数


				
void document.addEventListener(event, callback, capture);
				
				

说明:

通过Html中标准document对象的addEventListener方法添加扩展事件监听器,当指定事件发生时,将触发对应额监听回调函数。

参数:

返回值:

void : 无

EventTrigCallback

事件触发回调函数


				
void onTrig(){
	// Event trig code
}
				
				

说明:

指定事件触发时的回调函数,在指定的事件已经发生时调用。

参数:

返回值:

void : 无

ErrorEventTrigCallback

页面加载错误事件回调函数


				
void onErrorTrig(Event event){
	// Event trig code
	var url = event.url;  // 加载错误的页面路径,API中传入的url值
	var href = event.href;  // 加载错误的页面完整路径,通常以“file://”开头的路径
}
				
				

说明:

当Webview窗口加载页面失败后打开错误页面时触发此事件。

参数:

返回值:

void : 无