navigator

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

方法：

closeSplashscreen: 关闭程序启动界面
createShortcut: 创建应用快捷方式
hasShortcut: 查询是否存在应用快捷方式
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: JSON对象，创建应用快捷方式要设置的参数

回调方法：

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

权限：

permissions


"Navigator": {
	"description": "浏览器信息"
}

closeSplashscreen

关闭程序启动界面


void plus.navigator.closeSplashscreen();

说明：

很多情况下，程序启动后需要一段时间加载数据，为了避免界面显示空白内容，提高用户体验效果，这时可显示启动界面。等数据加载完成后再关闭启动界面进入应用，通常可在应用首界面加载数据完成并更新显示内容后调用此方法。

参数：

无

返回值：

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>

createShortcut

创建应用快捷方式


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

说明：

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

参数：

options: ( ShortcutOptions ) 可选 桌面快捷方式的参数
successCallback: ( ShortcutSuccessCallback ) 可选 创建桌面快捷方式成功回调
此功能受系统Launcher限制，可通过回调函数参数的sure属性判断创建桌面快捷方式是否一定成功。
errorCallback: ( NavigatorErrorCallback ) 可选 创建桌面快捷方式失败回调

返回值：

void : 无

平台支持：

Android - 2.3+ (支持): 注意：需要添加创建快捷方式的权限“<uses-permission android:name="com.android.launcher.permission.INSTALL_SHORTCUT"/>”。
iOS - ALL (不支持)

示例：


<!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"：快捷方式不存在（支持创建）；"unsupported"：不支持创建桌面快捷方式；"unknown"：不确定快捷方式是否存在。

返回值：

void : 无

平台支持：

Android - 2.3+ (支持)
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 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>

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

说明：

设置应用在前台运行时系统状态栏的背景颜色，默认使用系统的白色背景。

参数：

rgb: ( String ) 必选 背景颜色字符串，格式为#RRGGBB

返回值：

void : 无

平台支持：

Android - 2.2+ (不支持): 不支持设置系统状态栏背景颜色。
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。

平台支持：

Android - 2.2+ (不支持): 不支持获取系统状态栏背景颜色。
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 );

说明：

设置应用在前台运行时系统状态栏的样式，此操作是应用全局配置，Webview窗口关闭后仍然生效，默认值可在manifest.json中配置。

参数：

style: ( String ) 必选 背景颜色字符串，格式为#RRGGBB
可取值： "UIStatusBarStyleDefault"：iOS6及以下系统状态栏为黑底白字，iOS7及以上系统用于定义系统状态栏上文字颜色为黑字（适用于浅色背景）； "UIStatusBarStyleBlackOpaque"：深色背景色样式，iOS6及以下系统状态栏为黑底白字，iOS7及以上系统用于定义系统状态栏上文字颜色为白色（适用于深色背景）； "UIStatusBarStyleBlackTranslucent"：iOS6及以下系统在启动界面为灰底白字，iOS7及以上系统与UIStatusBarStyleBlackOpaque效果一样。

返回值：

void : 无

平台支持：

Android - 2.2+ (不支持): 不支持设置系统状态栏样式。
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.setStatusBarStyle( "UIStatusBarStyleBlackOpaque" );
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener("plusready",plusReady,false);
}
		</script>
	</head>
	<body>
	设置系统状态栏样式为浅色（白色）文字
	</body>
</html>

getStatusBarStyle

获取系统状态栏样式


String plus.navigator.getStatusBarStyle();

说明：

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

参数：

无

返回值：

String : 系统状态栏的背景样式，可取值： "UIStatusBarStyleDefault"：iOS6及以下系统状态栏为黑底白字，iOS7及以上系统用于定义系统状态栏上文字颜色为黑字（适用于浅色背景）； "UIStatusBarStyleBlackOpaque"：深色背景色样式，iOS6及以下系统状态栏为黑底白字，iOS7及以上系统用于定义系统状态栏上文字颜色为白色（适用于深色背景）； "UIStatusBarStyleBlackTranslucent"：iOS6及以下系统在启动界面为灰底白字，iOS7及以上系统不会返回此值。

平台支持：

Android - 2.2+ (不支持): 不支持获取系统状态栏样式。
iOS - 7.0+ (支持)

示例：


<!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 : 系统状态栏的高度值。

平台支持：

Android - 2.3+ (支持)
iOS - 5.1+ (支持)

示例：


<!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 : 是否为沉浸式状态栏模式。

平台支持：

Android - 2.3+ (支持)
iOS - 5.1+ (支持)

示例：


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

平台支持：

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

JSON对象，创建应用快捷方式要设置的参数

属性：

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才用到。

ShortcutSuccessCallback

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


void onSuccess( Event event ){
	var sure=event.sure; // 是否确定创建桌面快捷方式成功
}

参数：

event: ( Event ) 必选 创建桌面快捷方式返回的数据
在部分Launcher上无法确定是否创建桌面快捷方式成功，此时可通过event.sure（Boolean类型）获取是否确定创建成功。

返回值：

void : 无

平台支持：

Android - ALL (支持)
iOS - 4.3+ (不支持): 不支持创建桌面快捷方式。

NavigatorErrorCallback

操作错误回调函数接口


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

参数：

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

返回值：

void : 无