Events

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

常量：

"plusready": 扩展API加载完成事件
"pause": 运行环境从前台切换到后台事件
"resume": 运行环境从后台切换到前台事件
"netchange": 设备网络状态变化事件
"newintent": 新意图事件
"plusscrollbottom": 窗口滚动到底部事件
"error": 页面加载错误事件
"background": 应用切换到后台运行事件
"foreground": 应用切换到前台运行事件
"trimmemory": 应用需要清理内存事件
"splashclosed": 应用启动界面已关闭事件

方法：

addEventListener: 添加事件监听函数

回调方法：

EventTrigCallback: 事件触发回调函数
ErrorEventTrigCallback: 页面加载错误事件回调函数

"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方法添加扩展事件监听器，当指定事件发生时，将触发对应额监听回调函数。

参数：

event: ( DOMString ) 必选 要添加监听的事件类型，可取上面列出的所有事件常量
callback: ( EventTrigCallback ) 必选 扩展API加载完毕触发的回调函数
capture: ( Boolean ) 可选 事件流捕获顺序，可忽略

返回值：

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窗口加载页面失败后打开错误页面时触发此事件。

参数：

event: ( Event ) 可选 加载页面失败信息
可通过event.url（String类型）获取加载页面的url值，如“./test/html”；可通过event.href（String类型）加载错误的页面完整路径，包括完整的协议头，如Android平台“file:///storage/sdcard0/Android/data/io.dcloud.HBuilder/.HBuilder/apps/HBuilder/www/test.html”，iOS平台“file:///var/mobile/Containers/Data/Application/757966CF-345C-4348-B07F-EEF83CF9A369/Library/Pandora/apps/HBuilder/www/test.html”。

返回值：

void : 无

Events

API Reference

Plugins

Native.js

常量：

方法：

回调方法：

说明：

示例：

说明：

示例：

说明：

示例：

说明：

示例：

说明：

示例：

说明：

示例：

说明：

示例：

说明：

示例：

说明：

示例：

说明：

示例：

说明：

示例：

说明：

参数：

返回值：

说明：

参数：

返回值：

说明：

参数：

返回值：