navigator

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

方法：

checkPermission: 检查运行环境的权限
requestPermission: 请求运行环境的权限
closeSplashscreen: 关闭应用启动界面
hasSplashscreen: 查询应用启动界面是否已关闭
updateSplashscreen: 更新程序启动界面
createShortcut: 创建应用快捷方式
hasShortcut: 查询是否存在应用快捷方式
isBackground: 判断当前应用是否切换到后台
isFullscreen: 判断应用当前是否全屏模式显示
isLogs: 判断应用当前是否输出日志
setFullscreen: 设置应用是否全屏显示
setLogs: 设置应用是否输出日志
setStatusBarBackground: 设置系统状态栏背景颜色
getStatusBarBackground: 获取系统状态栏背景颜色
setStatusBarStyle: 设置系统状态栏样式
getStatusBarStyle: 获取系统状态栏样式
getStatusbarHeight: 获取系统状态栏高度
isImmersedStatusbar: 判断当前是否为沉浸式状态栏模式
setUserAgent: 设置userAgent值
getUserAgent: 获取userAgent值
setCookie: 设置Cookie值
getCookie: 获取Cookie值
removeAllCookie: 删除应用所有Cookie值
removeCookie: 删除应用Cookie
removeSessionCookie: 删除应用所有会话期Cookie值

对象：

ShortcutOptions: 创建应用快捷方式要设置的参数
SplashscreenOptions: 更新应用启动界面要设置的参数
PermissionNames: 运行环境权限类型

回调方法：

RequestPermissionCallback: 请求权限的回调函数
ShortcutSuccessCallback: 创建桌面快捷方式成功的回调函数
NavigatorErrorCallback: 操作错误回调函数接口

模块：

5+功能模块（permissions）


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

checkPermission

检查运行环境的权限


String plus.navigator.checkPermission(permission);

说明：

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

参数：

permission: ( PermissionNames ) 必选 要检查的权限名称

返回值：

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);

说明：

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

参数：

permission: ( PermissionNames ) 必选 要请求的权限名称
callback: ( RequestPermissionCallback ) 必选 请求权限结果回调函数
可通过回调函数参数的result属性判断请求权限结果： "authorized"表示程序已被用户授权使用此权限； "denied"表示程序已被用户拒绝使用此权限； "undetermined"表示程序未确定是否可使用此权限，此时调用对应的API时系统会弹出提示框让用户确认； "unsupported"表示程序不支持此权限。

返回值：

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.*下载到本地），更新启动界面后程序下次启动时生效。

参数：

options: ( SplashscreenOptions ) 必选 启动界面设置参数

返回值：

void : 无

平台支持：

Android - ALL (支持)
iOS - ALL (不支持)

示例：


<!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);

说明：

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

参数：

options: ( ShortcutOptions ) 可选 桌面快捷方式的参数
successCallback: ( ShortcutSuccessCallback ) 可选 创建桌面快捷方式成功回调
触发回调函数并不代表快捷方式已经创建成功，仅表示已经触发创建快捷方式操作，其结果受ROM的限制（如权限管理等）。可通过回调函数参数的sure属性判断创建桌面快捷方式是否确定成功。

返回值：

void : 无

平台支持：

Android - 2.3+ (支持): 注意：需要添加创建快捷方式的权限“<uses-permission android:name="com.android.launcher.permission.INSTALL_SHORTCUT"/>”。
iOS - ALL (支持): 仅在流应用环境下支持创建桌面快捷方式（不支持通过options参数自定义快捷方式名称、图标等信息），在5+ APP环境不支持此功能。

示例：


<!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);

参数：

options: ( ShortcutOptions ) 可选 查询桌面快捷方式的参数
successCallback: ( ShortcutSuccessCallback ) 可选 查询桌面快捷方式是否存在回调函数
可通过回调函数参数的result属性判断获取结果： "existing"：快捷方式已存在； "none"：快捷方式不存在； "unknown"：不确定快捷方式是否存在； "nopermissions"：当前环境无快捷方式查询权限； "unsupported"：不支持创建桌面快捷方式（已废弃）。

返回值：

void : 无

平台支持：

Android - 2.3+ (支持)
iOS - ALL (不支持): iOS平台不支持查询桌面快捷方式是否存在。

示例：


<!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。

平台支持：

Android - 2.3+ (支持)
iOS - 7.0+ (不支持): 无日志输出功能。

示例：


<!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);

说明：

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

参数：

fullscreen: ( Boolean ) 必选 是否全屏模式显示
可取值： true表示全屏模式显示，false表示非全屏模式显示，默认为非全屏模式显示。

返回值：

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获取分析日志）。

参数：

log: ( Boolean ) 必选 是否开启输出日志功能
true表示开启输出日志功能，false表示关闭输出日志功能，默认为关闭输出日志功能。

返回值：

void : 无

平台支持：

Android - 2.3+ (支持)
iOS - 7.0+ (不支持): 无日志输出功能。

示例：


<!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);

说明：

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

参数：

color: ( String ) 必选 背景颜色值
颜色值格式为"#RRGGBB"，如"#FF0000"为红色，默认颜色由系统状态栏样式决定。

返回值：

void : 无

平台支持：

Android - 5.0+ (支持): Android5.0及以上版本生效。
iOS - 7.0+ (支持): iOS7.0及以上版本生效。

示例：


<!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"表示红色。如果未设置系统状态栏背景颜色则返回空字符串。

平台支持：

Android - 5.0+ (不支持): Android5.0及以上版本生效。
iOS - 7.0+ (支持): iOS7.0及以上版本生效。

示例：


<!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窗口关闭后仍然生效。

参数：

style: ( String ) 必选 系统状态栏样式
可取值： "dark"：深色前景色样式（即状态栏前景文字为黑色），此时background建议设置为浅颜色； "light"：浅色前景色样式（即状态栏前景文字为白色），此时background建设设置为深颜色； "UIStatusBarStyleDefault"（不推荐使用，将废弃）：iOS6及以下系统状态栏为黑底白字，iOS7及以上系统用于定义系统状态栏上文字颜色为黑字（适用于浅色背景）； "UIStatusBarStyleBlackOpaque"（不推荐使用，将废弃）：深色背景色样式，iOS6及以下系统状态栏为黑底白字，iOS7及以上系统用于定义系统状态栏上文字颜色为白色（适用于深色背景）； "UIStatusBarStyleBlackTranslucent"（不推荐使用，将废弃）：iOS6及以下系统在启动界面为灰底白字，iOS7及以上系统与UIStatusBarStyleBlackOpaque效果一样。

返回值：

void : 无

平台支持：

Android - 5.0+ (支持): Android6.0及以上系统支持，部分ROM（魅族、小米）Android5.0及以上系统支持。通常默认为"dark",不同ROM可能存在差异。
iOS - 7.0+ (支持): iOS7及以上系统默认为"light",iOS6及以下系统默认为"dark"。

示例：


<!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中进行配置。

参数：

useragent: ( String ) 必选 要设置的新的userAgent值
checkplus: ( Boolean ) 可选 是否检测userAgent中自动添加“Html5Plus”标识
布尔类型，true表示检测并自动添加“Html5Plus”标识，false则不检测，默认值为true。 Html5Plus标识格式为Html5Plus/%version%，%version%为版本号，目前为1.0，如" Html5Plus/1.0"。

返回值：

void : 无

平台支持：

Android - 2.2+ (支持): 调用此方法不能更新已经创建好的Webview窗口的userAgent，在此之后创建的Webview窗口将使用新设置的userAgent值。同时调用此方法的Webview窗口也能及时更新userAgent值。
iOS - 4.5+ (支持): 调用此方法不能更新已经创建好的Webview窗口的userAgent，在此之后创建的Webview窗口将使用新设置的userAgent值。调用此方法的Webview窗口同样不能更新userAgent值。

示例：


<!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值，调用此接口后所有的请求都生效。

参数：

url: ( String ) 必选 要设置的cookie所属的网络地址
value: ( String ) 必选 要设置的cookie值
cookie值的格式必需符合RFC2109中定义的SET-COOKIE响应数据格式，如“test=123; expires=Friday,24-Jan-2014 16:24:36 GMT; path=/”。

返回值：

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 );

参数：

url: ( String ) 必选 要获取的cookie所属的网络地址

返回值：

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);

参数：

url: ( String ) 必选 要删除cookie所属的网络地址

返回值：

void : 无

平台支持：

Android - 2.2+ (不支持): 不支持删除指定网络地址的cookie值。
iOS - 4.5+ (支持)

示例：


<!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 : 无

平台支持：

Android - 2.2+ (支持)
iOS - 4.5+ (支持)

示例：


<!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

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

属性：

name: (String 类型 )快捷方式名称
如果未设置则使用应用的名称，manifest.json中name属性值。
icon: (String 类型 )快捷方式的图标
如果未设置则优先使用应用中指定的图标（manifest.json中icon节点下对应分辨率的图标），如未区配则使用应用的图标（仅在独立打包时），否则使用runtime提供的默认图标。
toast: (String 类型 )创建快捷方式后的提示信息
快捷方式创建成功后显示，默认提示内容为“"XXXX"已创建桌面快捷方式”，其中"XXXX"为程序的名称，如果不需要提示则设置此值为空字符串。
extra: (JSON 类型 )快捷方式的扩展参数
其中key和value值都必须是字符串类型。
classname: (String 类型 )要启动Activity类名
通常情况下不需要指定此值，仅在5+SDK集成时自定义Activity才用到。
force: (Boolean 类型 )是否需要强制创建快捷方式
true表示强制创建，false表示不强制创建，默认值为true。强制创建可能会导致在无法判断快捷方式是否存在的设备上重复创建，如果需要尽可能避免出现重复创建桌面快捷方式则应该设置force属性值为false。

SplashscreenOptions

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

属性：

image: (String 类型 )启动界面的图片路径
仅支持本地文件路径，图片必须为png格式。
autoclose: (Boolean 类型 )是否自动关闭启动界面
true表示应用启动后自动关闭启动界面，false表示应用启动后不自动关闭启动界面，需要在应用调用plus.navigator.closeSplashscreen()方法关闭。
autoclose_w2a: (Boolean 类型 )是否自动关闭启动界面（WAP2APP应用）
与autoclose属性值作用一致，仅在WAP2APP应用中有效。不推荐设置此值，如果未设置会自动使用autoclose属性值。
delay: (Number 类型 )启动界面延时关闭时间
仅在设置为自动关闭启动界面时有效。
delay_w2a: (Number 类型 )启动界面延时关闭时间（WAP2APP应用）
与delay属性值作用一致，仅在WAP2APP应用中有效。不推荐设置此值，如果未设置会自动使用delay属性值。

PermissionNames

运行环境权限类型

常量：

CAMERA: (String 类型 )访问摄像头权限
用于调用摄像头（plus.camera.*/plus.barcode.*）。

平台支持
- Android - ALL (不支持): 暂不支持，返回“unsupported”。
- iOS - ALL (支持)
CONTACTS: (String 类型 )访问系统联系人权限
用于访问（读、写）系统通讯录（plus.gallery.*）。

平台支持
- Android - ALL (不支持): 暂不支持，返回“unsupported”。
- iOS - ALL (支持)
GALLERY: (String 类型 )访问系统相册权限
用于访问（读、写）系统相册（plus.gallery.*）。

平台支持
- Android - ALL (不支持): 暂不支持，返回“unsupported”。
- iOS - ALL (支持)
LOCATION: (String 类型 )定位权限
用于获取当前用户位置信息（plus.geolocation.*）。

平台支持
- Android - ALL (不支持): 暂不支持，返回“unsupported”。
- iOS - ALL (支持)
NOTIFITION: (String 类型 )消息通知权限
用于接收系统消息通知（plus.push.*）。

平台支持
- Android - ALL (不支持): 暂不支持，返回“unsupported”。
- iOS - ALL (支持)
RECORD: (String 类型 )录音权限
用于进行本地录音操作（plus.audio.AudioRecorder）。

平台支持
- Android - ALL (不支持): 暂不支持，返回“unsupported”。
- iOS - ALL (支持)
SHORTCUT: (String 类型 )创建桌面快捷方式权限
用于在系统桌面创建快捷方式图标（plus.navigator.createShortcut）。

平台支持
- Android - ALL (支持): 在不同的ROM上存在差异，如果运行环境不支持此权限功能则返回“unsupported”。
- iOS - ALL (不支持): 系统未开放桌面快捷方式权限，可通过plus.navigator.createShortcut切换到Safari引导用户将网址“添加到主屏幕”，然后通过url sheme启动应用。 iOS平台总是返回“unsupported”。

RequestPermissionCallback

请求权限的回调函数


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

参数：

event: ( Event ) 必选 请求权限返回的数据
此对象包含以下属性值： event.result - 请求权限的结果（plus.navigator.requestPermission），可取值： "authorized"表示程序已被用户授权使用此权限； "denied"表示程序已被用户拒绝使用此权限； "undetermined"表示程序未确定是否可使用此权限，此时调用对应的API时系统会弹出提示框让用户确认； "unsupported"表示程序不支持此权限。

返回值：

void : 无

ShortcutSuccessCallback

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


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

参数：

event: ( Event ) 必选 创建桌面快捷方式返回的数据
此对象包含以下属性值： event.result - 查询快捷方式是否存在的结果（plus.navigator.hasShortcut），可取值： existing"，快捷方式已存在； "none"，快捷方式不存在（支持创建）； "unsupported"，不支持创建桌面快捷方式； "unknown"：不确定快捷方式是否存在。 event.sure - 创建快捷方式的结果（plus.navigator.createShortcut），Boolean类型，可取值： true，表示在当前环境下确定快捷方式创建成功； false，表示不确定快捷方式是否已创建。

返回值：

void : 无

平台支持：

Android - ALL (支持)
iOS - 4.3+ (支持): 仅在流应用环境下支持创建桌面快捷方式，在5+ APP环境不支持此功能。

NavigatorErrorCallback

操作错误回调函数接口


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

参数：

error: ( Exception ) 必选 操作失败信息
可通过error.code（Number类型）获取错误编码；可通过error.message（String类型）获取错误描述信息。

返回值：

void : 无

Navigator

API Reference

Plugins

Native.js

方法：

对象：

回调方法：

模块：

说明：

参数：

返回值：

示例：

说明：

参数：

返回值：

示例：

说明：

参数：

返回值：

示例：

说明：

参数：

返回值：

示例：

说明：

参数：

返回值：

平台支持：

示例：

说明：

参数：

返回值：

平台支持：

示例：

参数：

返回值：

平台支持：

示例：

说明：

参数：

返回值：

示例：

参数：

返回值：

示例：

说明：

参数：

返回值：

平台支持：

示例：

说明：

参数：

返回值：

示例：

说明：

参数：

返回值：

平台支持：

示例：

说明：

参数：

返回值：

平台支持：

示例：

说明：

参数：

返回值：

平台支持：

示例：

说明：

参数：

返回值：

平台支持：

示例：

说明：

参数：

返回值：

示例：

说明：

参数：