API Reference

Plugins

Native.js


navigator

navigator用于管理浏览器运行环境信息

方法:

对象:

回调方法:

模块:

5+功能模块(permissions)


{
// ...
"permissions":{
	// ...
	"Navigator": {
		"description": "浏览器信息"
	}
}
}
			

checkPermission

检查运行环境的权限


String plus.navigator.checkPermission(permission);
				

说明:

向系统检查当前程序的权限状态,不触发权限相对应的功能API的调用。

参数:

返回值:

String : 可返回以下值: "authorized"表示程序已被用户授权使用此权限; "denied"表示程序已被用户拒绝使用此权限; "undetermined"表示程序未确定是否可使用此权限,此时调用对应的API时系统会弹出提示框让用户确认; "notdeny"表示程序未被用户拒绝使用此权限(与denied相反,可能是"authorized"或者"undetermined"); "unknown"表示程序未知此权限状态(系统存在权限管理但无法查询); "unsupported"表示程序不支持此权限。

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>navigator Example</title>
	<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
// 检查定位权限
function checkPermissionPos(){
	var pp = plus.navigator.checkPermission('LOCATION');
	switch(pp){
		case 'authorized':
			plus.nativeUI.alert('已开启定位权限');
		break;
		case 'denied':
			plus.nativeUI.alert('已关闭定位权限');
		break;
		case 'undetermined':
			plus.nativeUI.alert('未确定定位权限');
		break;
		case 'unknown':
			plus.nativeUI.alert('无法查询定位权限');
		break;
		default:
			plus.nativeUI.alert('不支持定位权限');
		break;
	}
}
	</script>
	</head>
	<body>
	检查权限<br/>
	<button onclick="checkPermissionPos()">检查定位权限</button>
	</body>
</html>
				

requestPermission

请求运行环境的权限


String plus.navigator.requestPermission(permission, callback);
				

说明:

向系统请求获取权限,此时会弹出系统权限确认框,用户可选择允许或拒绝。

参数:

返回值:

void : 无

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>navigator Example</title>
	<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
// 检查并请求定位权限
function requestPermissionPos(){
	var pp = plus.navigator.checkPermission('LOCATION');
	switch(pp){
		case 'authorized':
			plus.nativeUI.alert('已经获取定位权限');
		break;
		default:// 未知是否有权限,此时需要尝试请求权限
			plus.navigator.requestPermission('LOCATION', function(e){
				switch(e.result){
					case 'authorized':
						plus.nativeUI.alert('用户已允许定位权限');
					break;
					default:
						plus.nativeUI.alert('用户未允许定位权限');
					break;
				}
			});
		break;
	}
}
	</script>
	</head>
	<body>
	请求权限<br/>
	<button onclick="checkPermissionPos()">请求定位权限</button>
	</body>
</html>
				

closeSplashscreen

关闭应用启动界面


void plus.navigator.closeSplashscreen();
				

说明:

很多情况下,应用启动后需要一段时间加载数据,为了避免界面显示空白内容,提高用户体验效果,这时可显示启动界面。 等数据加载完成后再关闭启动界面进入应用,通常可在应用首界面加载数据完成并更新显示内容后调用此方法。 注意:HBuilder7.1版本后启动界面不调用此方法超过6秒后会自动关闭。

参数:

返回值:

void : 无

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>navigator Example</title>
	<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
	// 关闭程序启动界面
	plus.navigator.closeSplashscreen();
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
	</script>
	</head>
	<body>
	关闭程序启动界面
	</body>
</html>
				

hasSplashscreen

查询应用启动界面是否已关闭


Boolean plus.navigator.hasSplashscreen();
				

说明:

如果启动界面显示返回true,否则返回false。

参数:

返回值:

Boolean : true表示启动界面还存在(未关闭),false表示启动界面不存在(已关闭)。

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>navigator Example</title>
	<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
	// 关闭程序启动界面
	plus.navigator.closeSplashscreen();
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
// 查询是否关闭启动界面
function hasSplash(){
	if(plus.navigator.hasSplashscreen()){
		alert('启动界面未关闭');
	}else{
		alert('启动界面已关闭');
	}
}
	</script>
	</head>
	<body>
	查询应用启动界面是否已关闭<br/>
	<button onclick="hasSplash()">查询</button>
	</body>
</html>
				

updateSplashscreen

更新程序启动界面


void plus.navigator.updateSplashscreen(options);
				

说明:

可设置启动界面显示的图片(仅支持本地文件路径,如果是网络资源可先通过plus.downloader.*下载到本地), 更新启动界面后程序下次启动时生效。

参数:

返回值:

void : 无

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>navigator Example</title>
	<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
// 更新启动界面
function updateSplash(){
	plus.navigator.updateSplashscreen({image:'_www/splash.png'});
}
	</script>
	</head>
	<body>
		更新程序启动界面<br/>
		<button onclick="updateSplash()">Update</button>
	</body>
</html>
				

createShortcut

创建应用快捷方式


void plus.navigator.createShortcut(options, successCallback);
				

说明:

在系统桌面创建应用的快捷方式,点击后可直接启动应用。

参数:

返回值:

void : 无

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>navigator Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
	// 创建快捷方式
	plus.navigator.createShortcut();
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
		</script>
	</head>
	<body>
	创建应用快捷方式
	</body>
</html>
				

hasShortcut

查询是否存在应用快捷方式


void plus.navigator.hasShortcut(options, successCallback);
				

参数:

返回值:

void : 无

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>navigator Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
function queryShortcut(){
	plus.navigator.hasShortcut({}, function(e){
		// 可通过eresult获取结果:
		// "existing":快捷方式已存在;
		// "none":快捷方式不存在(支持创建);
		// "unsupported":不支持创建桌面快捷方式;
		// "unknown":不确定快捷方式是否存在。
		console.log("查询结果:"+e.result);
	});
}
		</script>
	</head>
	<body>
	查询是否创建应用快捷方式
	<br/>
	<button onclick="queryShortcut()">查询</button>
	</body>
</html>
				

isBackground

判断当前应用是否切换到后台


Boolean plus.navigator.isBackground();
				

说明:

在多应用运行环境(如流应用)中,启动一个新应用时,之前运行的应用将会自动切换到后台运行,此时plus.navigator.isBackground()返回状态只为true。 注意:此状态不是5+应用切换到系统后台的状态,而是在同一apk中同时运行多个应用时被切换到后台的状态。

参数:

返回值:

Boolean : 应用切换到后台时返回true,否则返回false。

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>navigator Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
	// 判断前后台状态
	document.addEventListener('background', function(){
		console.log('Background: '+plus.navigator.isBackground());
	}, false);
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
		</script>
	</head>
	<body>
	判断当前应用是否切换到后台
	</body>
</html>
				

isFullscreen

判断应用当前是否全屏模式显示


Boolean plus.navigator.isFullscreen();
				

参数:

返回值:

Boolean : 应用全屏模式显示时返回true,否则返回false。

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>navigator Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
	// 是否全屏显示
	console.log(plus.navigator.isFullscreen()?'Fullscreen!':'Not fullscreen!');
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
		</script>
	</head>
	<body>
	判断应用当前是否全屏模式显示
	</body>
</html>
				

isLogs

判断应用当前是否输出日志


Boolean plus.navigator.isLogs();
				

说明:

日志包括应用原生层内部跟踪日志(ADB、LogCat工具可获取的日志)及JS层跟踪日志(console.log输出的日志)。 开启日志在一定程度上会降低程序的性能,通常建议在正式发布时关闭日志输出,在调试时开启日志输出(此时可以通过工具ADB、LogCat获取分析日志)。

参数:

返回值:

Boolean : 应用输出日志时返回true,否则返回false。

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>navigator Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
	// 是否全屏显示
	alert(plus.navigator.isLogs()?'应用开启输出日志!':'应用关闭输出日志!');
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
		</script>
	</head>
	<body>
	判断应用当前是否输出日志
	</body>
</html>
				

setFullscreen

设置应用是否全屏显示


void plus.navigator.setFullscreen(fullscreen);
				

说明:

设置应用在全屏模式显示时,将隐藏系统状态栏,通常游戏类应用才会设置为全屏模式显示。

参数:

返回值:

void : 无

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>navigator Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
	// 全屏显示
	plus.navigator.setFullscreen(true);
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
		</script>
	</head>
	<body>
	应用全屏模式显示
	</body>
</html>
				

setLogs

设置应用是否输出日志


void plus.navigator.setLogs(log);
				

说明:

设置应用是否输出日志信息,默认关闭输出日志功能。 日志包括应用原生层内部跟踪日志(ADB、LogCat工具可获取的日志)及JS层跟踪日志(console.log输出的日志)。 开启日志在一定程度上会降低程序的性能,通常建议在正式发布时关闭日志输出,在调试时开启日志输出(此时可以通过工具ADB、LogCat获取分析日志)。

参数:

返回值:

void : 无

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>navigator Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
	// 开启输出日志
	plus.navigator.setLogs(true);
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
		</script>
	</head>
	<body>
	应用开启输出日志功能
	</body>
</html>
				

setStatusBarBackground

设置系统状态栏背景颜色


void plus.navigator.setStatusBarBackground(color);
				

说明:

设置应用在前台运行时系统状态栏的背景颜色,默认使用系统状态栏默认背景色(有系统状态栏样式决定)。 注意:为了有更好的兼容性,避免设置接近白色或黑色的颜色值。

参数:

返回值:

void : 无

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>navigator Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
	// 设置系统状态栏背景为红色
	plus.navigator.setStatusBarBackground('#FF0000');
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
		</script>
	</head>
	<body>
	设置系统状态栏背景为红色
	</body>
</html>
				

getStatusBarBackground

获取系统状态栏背景颜色


String plus.navigator.getStatusBarBackground();
				

说明:

获取应用在前台运行时系统状态栏的背景颜色。

参数:

返回值:

String : 系统状态栏的背景颜色,颜色值格式为"#RRGGBB",如"#FF0000"表示红色。 如果未设置系统状态栏背景颜色则返回空字符串。

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>navigator Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
	// 获取系统状态栏背景
	var rgb = plus.navigator.getStatusBarBackground();
	console.log('StatusBarBackground:'+rgb);
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
		</script>
	</head>
	<body>
	获取系统状态栏背景
	</body>
</html>
				

setStatusBarStyle

设置系统状态栏样式


void plus.navigator.setStatusBarStyle(style);
				

说明:

设置应用在前台运行时系统状态栏的样式,默认值可通过manifest.json文件的plus->statusbar->style配置。 注意:此操作是应用全局配置,调用的Webview窗口关闭后仍然生效。

参数:

返回值:

void : 无

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>navigator Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
	// 设置系统状态栏样式为深色底白字
	plus.navigator.setStatusBarStyle('dark');
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
		</script>
	</head>
	<body>
	设置系统状态栏样式为深底白字
	</body>
</html>
				

getStatusBarStyle

获取系统状态栏样式


String plus.navigator.getStatusBarStyle();
				

说明:

获取应用运行时系统状态栏的样式。

参数:

返回值:

String : 系统状态栏的样式,调用plus.navigator.setStatusBarStyle()方法设置的值(或者通过manifest.json文件的plus->statusbar->style配置)。 如果未设置系统状态栏则返回空字符串。

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>navigator Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
	// 获取系统状态栏样式
	var ss = plus.navigator.getStatusBarStyle();
	console.log('Statusbar Style: '+ss);
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
		</script>
	</head>
	<body>
	获取系统状态栏样式
	</body>
</html>
				

getStatusbarHeight

获取系统状态栏高度


Number plus.navigator.getStatusbarHeight();
				

说明:

单位为像素(px),值为Webview中的逻辑高度单位,如果要获取真实高度则必须乘以plus.screen.scale。

参数:

返回值:

Number : 系统状态栏的高度值。

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>navigator Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
	// 获取系统状态栏高度
	var lh = plus.navigator.getStatusbarHeight();
	console.log('Statusbar Height: '+lh*plus.screen.scale);
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
		</script>
	</head>
	<body>
	获取系统状态栏高度
	</body>
</html>
				

isImmersedStatusbar

判断当前是否为沉浸式状态栏模式


Boolean plus.navigator.isImmersedStatusbar();
				

说明:

如果当前应用采用沉浸式状态栏则返回true,否则返回false。 注意:如果当前系统版本不支持沉浸式状态栏也返回false。

参数:

返回值:

Boolean : 是否为沉浸式状态栏模式。

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>navigator Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
	// 获取是否为沉浸式状态栏模式
	var bi = plus.navigator.isImmersedStatusbar();
	console.log('Immersed Statusbar: '+bi?'Yes':'No' );
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
		</script>
	</head>
	<body>
	当前是否为沉浸式状态栏模式
	</body>
</html>
				

setUserAgent

设置userAgent值


void plus.navigator.setUserAgent(useragent, checkplus);
				

说明:

设置应用通过navigator.userAgent获取的值,及所有发起Http请求时提交的userAgent值。 如果要设置启动页面的userAgent值则需要在manifest.json中进行配置。

参数:

返回值:

void : 无

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>navigator Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
	// 设置userAgent
	plus.navigator.setUserAgent( "Application/HelloWorld" );
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
		</script>
	</head>
	<body>
	设置userAgent为“Application/HelloWorld”
	</body>
</html>
				

getUserAgent

获取userAgent值


String plus.navigator.getUserAgent();
				

参数:

返回值:

string : 应用的userAgent值

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>navigator Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
// 获取应用的userAgent
function appUserAgent(){
	alert(plus.navigator.getUserAgent());
}
		</script>
	</head>
	<body>
		获取userAgent值<br/>
		<buttong onclick="appUserAgent()">Get userAgent</buttong>
	</body>
</html>
				

setCookie

设置Cookie值


void plus.navigator.setCookie( url, value );
				

说明:

设置应用发起Http请求时提交的cookie值,调用此接口后所有的请求都生效。

参数:

返回值:

void : 无

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>navigator Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
	// 设置cookie
	plus.navigator.setCookie('http://www.dcloud.io/', 'test=123; expires=Friday,24-Jan-2015 16:24:36 GMT; path=/');
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
		</script>
	</head>
	<body>
	设置cookie
	</body>
</html>
				

getCookie

获取Cookie值


String plus.navigator.getCookie( url );
				

参数:

返回值:

string : Cookie值

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>navigator Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
// 获取Cookie
function getCookie(){
	alert( plus.navigator.getCookie('http://www.dcloud.io/') );
}
		</script>
	</head>
	<body>
		获取Cookie值<br/>
		<buttong onclick="getCookie()">Get Cookie</buttong>
	</body>
</html>
				

removeAllCookie

删除应用所有Cookie值


void plus.navigator.removeAllCookie();
				

参数:

返回值:

void : 无

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>navigator Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
// 清除应用的所有Cookie
function clearCookie(){
	plus.navigator.removeAllCookie();
}
		</script>
	</head>
	<body>
		删除应用所有Cookie值<br/>
		<buttong onclick="clearCookie()">Clear Cookie</buttong>
	</body>
</html>
				

removeCookie

删除应用Cookie


void plus.navigator.removeCookie(url);
				

参数:

返回值:

void : 无

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>navigator Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
// 删除应用的Cookie
function removeCookie(){
	plus.navigator.removeCookie('http://www.dcloud.io/');
}
		</script>
	</head>
	<body>
		删除应用Cookie<br/>
		<buttong onclick="removeCookie()">Remove Cookie</buttong>
	</body>
</html>
				

removeSessionCookie

删除应用所有会话期Cookie值


void plus.navigator.removeSessionCookie();
				

参数:

返回值:

void : 无

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>navigator Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener('plusready', plusReady, false);
}
// 清除应用的所有会话期Cookie
function clearCookie(){
	plus.navigator.removeSessionCookie();
}
		</script>
	</head>
	<body>
		删除应用所有会话期Cookie值<br/>
		<buttong onclick="clearCookie()">Clear Cookie</buttong>
	</body>
</html>
				

ShortcutOptions

创建应用快捷方式要设置的参数

属性:

SplashscreenOptions

更新应用启动界面要设置的参数

属性:

PermissionNames

运行环境权限类型

常量:

RequestPermissionCallback

请求权限的回调函数


void onSuccess(Event event){
	var result=event.result; // 请求权限的结果
}
				

参数:

返回值:

void : 无

ShortcutSuccessCallback

创建桌面快捷方式成功的回调函数


void onSuccess(Event event){
	var result=event.result; // 快捷方式是否已经存在,调用plus.navigator.hasShortcut方法时有效
	var sure=event.sure; // 是否确定创建桌面快捷方式成功,调用plus.navigator.createShortcut方法时有效
}
				

参数:

返回值:

void : 无

平台支持:

NavigatorErrorCallback

操作错误回调函数接口


function void onError(Exception error){
	// Error.
	var code = error.code; // 错误编码
	var message = error.message; // 错误描述信息
}
				

参数:

返回值:

void : 无