# navigator

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

## 方法：

- checkPermission: 检查运行环境的权限
- closeSplashscreen: 关闭应用启动界面
- hasNotchInScreen: 查询设备是否为刘海屏
- 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值
- getSafeAreaInsets: 获取应用的安全区域
- getOrientation: 获取应用的横竖屏状态
- hideSystemNavigation: 隐藏系统虚拟按键（导航栏）

## 对象：

- ShortcutOptions: 创建应用快捷方式要设置的参数
- SplashscreenOptions: 更新应用启动界面要设置的参数
- PermissionNames: 运行环境权限类型
- SafeAreaInsets: JSON对象，安全区域信息对象

## 回调方法：

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

## 权限：

5+功能模块（permissions）

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

# 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.*）。

- CONTACTS: (String 类型 )访问系统联系人权限

  用于访问（读、写）系统通讯录（plus.gallery.*）。

- GALLERY: (String 类型 )访问系统相册权限

  用于访问（读、写）系统相册（plus.gallery.*）。

- LOCATION: (String 类型 )定位权限

  用于获取当前用户位置信息（plus.geolocation.*）。

- NOTIFITION: (String 类型 )消息通知权限

  用于接收系统消息通知（plus.push.*）。

- RECORD: (String 类型 )录音权限

  用于进行本地录音操作（plus.audio.AudioRecorder）。

- SHORTCUT: (String 类型 )创建桌面快捷方式权限

  用于在系统桌面创建快捷方式图标（plus.navigator.createShortcut）。

# SafeAreaInsets

JSON对象，安全区域信息对象

## 说明：

通过getSafeAreaInsets方法返回的信息。

## 属性：

- bottom: (Number 类型 )应用底部安全区域偏移量

  单位为逻辑像素（px）， 如果应用已经配置底部安全区域则返回0。

- left: (Number 类型 )应用左侧安全区域偏移量

  单位为逻辑像素（px）， 如果应用已经配置左侧安全区域则返回0。

- right: (Number 类型 )应用右侧安全区域偏移量

  单位为逻辑像素（px）， 如果应用已经配置右侧安全区域则返回0。

- top: (Number 类型 )应用顶部安全区域偏移量

  单位为逻辑像素（px）， 如果应用已经配置顶部安全区域则返回0。

- deviceBottom: (Number 类型 )设备底部安全区域偏移量

  单位为逻辑像素（px）。

- deviceLeft: (Number 类型 )设备左侧安全区域偏移量

  单位为逻辑像素（px）。

- deviceRight: (Number 类型 )设备右侧安全区域偏移量

  单位为逻辑像素（px）。

- deviceTop: (Number 类型 )设备顶部安全区域偏移量

  单位为逻辑像素（px）。

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

# NavigatorErrorCallback

操作错误回调函数接口

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

## 参数：

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

## 返回值：

void : 无