navigator常见问题我要提意见
navigator用于管理浏览器运行环境信息
方法:
- checkPermission: 检查运行环境的权限
- closeSplashscreen: 关闭应用启动界面
- hasNotchInScreen: 查询设备是否为刘海屏
- hasSplashscreen: 查询应用启动界面是否已关闭
- updateSplashscreen: 更新程序启动界面
- createShortcut: 创建应用快捷方式
- hasShortcut: 查询是否存在应用快捷方式
- hideSystemNavigation: 隐藏系统虚拟按键(导航栏)
- showSystemNavigation: 显示系统虚拟按键(导航栏)
- isBackground: 判断当前应用是否切换到后台
- isFullscreen: 判断应用当前是否全屏模式显示
- isLogs: 判断应用当前是否输出日志
- isRoot: 判断当前设备是否被root破解
- isSimulator: 判断当前应用是否运行在模拟器中
- setFullscreen: 设置应用是否全屏显示
- setLogs: 设置应用是否输出日志
- setStatusBarBackground: 设置系统状态栏背景颜色
- getStatusBarBackground: 获取系统状态栏背景颜色
- setStatusBarStyle: 设置系统状态栏样式
- getStatusBarStyle: 获取系统状态栏样式
- getStatusbarHeight: 获取系统状态栏高度
- isImmersedStatusbar: 判断当前是否为沉浸式状态栏模式
- setUserAgent: 设置userAgent值
- getUserAgent: 获取userAgent值
- setCookie: 设置Cookie值
- getCookie: 获取Cookie值
- removeAllCookie: 删除应用所有Cookie值
- removeCookie: 删除应用Cookie
- removeSessionCookie: 删除应用所有会话期Cookie值
- getSafeAreaInsets: 获取应用的安全区域
- getOrientation: 获取应用的横竖屏状态
- getUIStyle: 获取系统外观样式(暗黑模式)
- getSignature: 获取应用的签名标识
对象:
- ShortcutOptions: 创建应用快捷方式要设置的参数
- SplashscreenOptions: 更新应用启动界面要设置的参数
- PermissionNames: 运行环境权限类型
- SafeAreaInsets: JSON对象,安全区域信息对象
回调方法:
- 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>
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>
hasNotchInScreen
查询设备是否为刘海屏
Boolean plus.navigator.hasNotchInScreen();
说明:
刘海屏返回true,否则返回false。
参数:
无
返回值:
Boolean : true表示设备屏幕为刘海屏,false表示设备屏幕不是刘海屏。平台支持:
- Android
- ALL
(支持)
:
暂时仅支持华为、小米、Oppo、Vivo等品牌设备。
- iOS - ALL (支持)
示例:
<!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 hasNotch(){
if(plus.navigator.hasNotchInScreen()){
alert('此设备是刘海屏');
}else{
alert('此设备不是刘海屏');
}
}
</script>
</head>
<body>
查询设备是否为刘海屏<br/>
<button onclick="hasNotch()">查询</button>
</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>
hideSystemNavigation
隐藏系统虚拟按键(导航栏)
void plus.navigator.hideSystemNavigation();
说明:
HBuilderX2.3.4及以上版本支持。
参数:
无
返回值:
void : 无平台支持:
- Android
- 4.4+
(支持)
:
仅在支持系统虚拟按键设备上生效,并且应用必须设置为沉浸式。注意:由于导航栏对安卓系统很重要,用户交互操作(如上划手势、弹出软键盘、弹出系统框等)时导航栏可能会重新出现。
- iOS
- ALL
(不支持)
:
无效果
showSystemNavigation
显示系统虚拟按键(导航栏)
void plus.navigator.showSystemNavigation();
说明:
HBuilderX3.0.0及以上版本支持。
参数:
无
返回值:
void : 无平台支持:
- Android
- 4.4+
(支持)
:
仅在支持系统虚拟按键设备上生效,并且应用必须设置为沉浸式
- iOS
- ALL
(不支持)
:
无效果
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>
isRoot
判断当前设备是否被root破解
Boolean plus.navigator.isRoot();
说明:
注意:HBuilderX3.0.0及以上版本支持。
参数:
无
返回值:
Boolean : 如果设备已root破解则返回true,否则返回false。平台支持:
- Android
- All
(不支持)
:
暂不支持,返回false。
- iOS
- 9.0+
(支持)
:
iOS平台root破解也叫越狱,越狱则返回true,否则返回false。
isSimulator
判断当前应用是否运行在模拟器中
Boolean plus.navigator.isSimulator();
说明:
注意:HBuilderX3.0.0及以上版本支持。
参数:
无
返回值:
Boolean : 如果运行在模拟器中则返回true,否则返回false。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配置)。平台支持:
- Android
- 5.0+
(支持)
:
返回最后一次设置的值,未设置则返回空字符串。
- 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 : 系统状态栏的高度值。示例:
<!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>
getSafeAreaInsets
获取应用的安全区域
SafeAreaInsets plus.navigator.getSafeAreaInsets();
说明:
可在应用manifest.json的plus->safeArea下配置应用的全局安全区域。
参数:
无
返回值:
SafeAreaInsets : 应用的安全区域信息getOrientation
获取应用的横竖屏状态
Number plus.navigator.getOrientation();
说明:
返回应用当前的横竖屏状态,如果应用横竖屏发生转换,需重新获取。
参数:
无
返回值:
Number : 屏幕方向数值: 0 - 竖屏; 90 - 横屏,HOME键在右; 180 - 反向竖屏; -90 - 反向横屏,HOME'键在左。getUIStyle
获取系统外观样式(暗黑模式)
String plus.navigator.getUIStyle();
说明:
返回当前系统使用的外观样式,用于判断是否设置为暗黑模式。 可通过uistylechange事件监听外观样式的变化。 HBuilderX2.6.3+版本支持,iOS平台适配暗黑模式参考:https://ask.dcloud.net.cn/article/36995。
参数:
无
返回值:
String : 浅色模式返回"light",深色模式(暗黑模式)返回'dark"。平台支持:
- iOS
- 13+
(支持)
:
iOS13+系统支持,低版本系统返回"light"。
- Android
- ALL
(不支持)
:
返回"light"。
getSignature
获取应用的签名标识
String plus.navigator.getSignature();
说明:
签名标识可以认为是应用的身份信息,可以用来判断应用是否被反编译重新签名再发布。
注意:HBuilderX3.0.0及以上版本支持
参数:
无
返回值:
String : 应用的签名标识。平台支持:
- iOS
- 9.0+
(支持)
:
应用签名证书中绑定的Bundle ID(AppleID)的md5值(全部为小写)。
- Android
- ALL
(支持)
:
应用签名证书的SHA1值(全部为小写,中间不包含“:”)。 为了保证应用的安全性,请使用自己生成的证书(不要使用公共测试证书)。
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 (支持)
- Android - ALL (不支持)
:
- CONTACTS: (String
类型
)访问系统联系人权限
用于访问(读、写)系统通讯录(plus.gallery.*)。
平台支持
- Android - ALL (不支持)
:
暂不支持,返回“unsupported”。
- iOS - ALL (支持)
- Android - ALL (不支持)
:
- GALLERY: (String
类型
)访问系统相册权限
用于访问(读、写)系统相册(plus.gallery.*)。
平台支持
- Android - ALL (不支持)
:
暂不支持,返回“unsupported”。
- iOS - ALL (支持)
- Android - ALL (不支持)
:
- LOCATION: (String
类型
)定位权限
用于获取当前用户位置信息(plus.geolocation.*)。
平台支持
- Android - ALL (不支持)
:
暂不支持,返回“unsupported”。
- iOS - ALL (支持)
- Android - ALL (不支持)
:
- NOTIFITION: (String
类型
)消息通知权限
用于接收系统消息通知(plus.push.*)。
平台支持
- Android - ALL (不支持)
:
暂不支持,返回“unsupported”。
- iOS - ALL (支持)
- Android - ALL (不支持)
:
- RECORD: (String
类型
)录音权限
用于进行本地录音操作(plus.audio.AudioRecorder)。
平台支持
- Android - ALL (不支持)
:
暂不支持,返回“unsupported”。
- iOS - ALL (支持)
- Android - ALL (不支持)
:
- SHORTCUT: (String
类型
)创建桌面快捷方式权限
用于在系统桌面创建快捷方式图标(plus.navigator.createShortcut)。
平台支持
- Android - ALL (支持)
:
在不同的ROM上存在差异,如果运行环境不支持此权限功能则返回“unsupported”。
- iOS - ALL (不支持)
:
系统未开放桌面快捷方式权限,可通过plus.navigator.createShortcut切换到Safari引导用户将网址“添加到主屏幕”,然后通过url sheme启动应用。 iOS平台总是返回“unsupported”。
- Android - ALL (支持)
:
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 : 无平台支持:
- 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类型)获取错误描述信息。