API Reference

Plugins

Native.js


runtime

Runtime模块管理运行环境,可用于获取当前运行环境信息、与其它程序进行通讯等。通过plus.runtime可获取运行环境管理对象。

属性:

方法:

对象:

回调方法:

模块:

5+功能模块(permissions)


{
// ...
"permissions":{
	// ...
	"Runtime": {
		"description": "运行环境"
	}
}
}
			

appid

当前应用的APPID


plus.runtime.appid;
				

说明:

String 类型 只读属性

当前应用的APPID,字符串类型。注意,如果是在HBuilder真机运行获取的是固定值"HBuilder",需要提交App云端打包后运行才能获取真实的APPID值。

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>Runtime Example</title>
		<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener('plusready', onPlusReady, false);
// 扩展API加载完毕,现在可以正常调用扩展API
function onPlusReady(){
	// 处理第三方传入的参数
	alert('Current APP:' + plus.runtime.appid);
}
		</script>
	</head>
	<body>
		当前应用的APPID
	</body>
</html>
				

arguments

第三方程序调用时传递给程序的参数


plus.runtime.arguments;
					

说明:

String 类型 只读属性

第三方程序传递过来的参数,字符串格式类型数据。 不是由第三方程序调用启动,则返回空字符串。

平台支持:

示例:


<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8">
	<title>Runtime Example</title>
	<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener('plusready', onPlusReady, false);
// 扩展API加载完毕,现在可以正常调用扩展API
function onPlusReady(){
	// 处理第三方传入的参数
	if(plus.runtime.arguments != ""){
		try{
			var aj = JSON.parse(plus.runtime.arguments);
			// 处理JSON对象aj
		}catch(e){
			// 若传入的参数不是JSON格式字符,需处理异常情况
		}
	}
}
	</script>
</head>
<body>
	第三方程序调用时传递给程序的参数
</body>
</html>
				

channel

应用的市场推广渠道标识


plus.runtime.channel;
				

说明:

String 类型 只读属性

"qihoo:browser"标识360浏览器流应用,"qihoo:appstore "表示360手机助手流应用,"dcloud:streamapps"表示DCloud流应用基座。 注意:仅流应用环境中可用(如果没有特殊配置默认返回运行环境的包名),非流应用环境中返回空字符串。

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>Runtime Example</title>
		<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener('plusready', onPlusReady, false);
// 扩展API加载完毕,现在可以正常调用扩展API
function onPlusReady(){
	// 处理第三方传入的参数
	alert('Current APP:' + plus.runtime.appid);
}
		</script>
	</head>
	<body>
		当前应用的APPID
	</body>
</html>
				

launcher

应用启动来源


plus.runtime.launcher;
					

说明:

String 类型 只读属性

5+ APP启动类型,可取以下值: "default":默认启动方式,通常表示应用列表启动(360手助中搜索启动); "scheme":通过urlscheme方式触发启动; "push":通过点击系统通知方式触发启动; "stream":通过流应用api(plus.stream.open)启动; "shortcut":通过快捷方式启动,iOS平台表示通过3D Touch快捷方式,Android平台表示通过桌面快捷方式启动; "barcode":通过二维码扫描启动; "myapp":通过应用收藏列表([流应用]独立App中"我的"列表)触发启动。

平台支持:

origin

应用安装来源


plus.runtime.origin;
					

说明:

String 类型 只读属性

5+应用安装来源,可取以下值: "default":默认安装来源,apk/ipa安装包内置安装; "stream":通过流应用api(plus.stream.open)安装,仅流应用环境下支持; "push":通过点击系统通知方式触发安装,仅流应用环境下支持; "scheme":通过urlscheme方式触发安装,仅流应用环境下支持; "barcode":通过二维码扫描触发安装,仅流应用环境下支持; "silent":通过后台静默方式安装,仅流应用环境下支持。

version

客户端的版本号


plus.runtime.version;
				

说明:

String 类型 只读属性

字符串类型,在编译环境中设置的apk/ipa版本号。

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>Runtime Example</title>
		<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener('plusready', onPlusReady, false);
// 扩展API加载完毕,现在可以正常调用扩展API
function onPlusReady(){
	// 获取apk/ipa版本号
	alert('Application(apk/ipa) version:' + plus.runtime.version);
}
		</script>
	</head>
	<body>
		客户端(apk/ipa)的版本号
	</body>
</html>
				

innerVersion

客户端5+运行环境的版本号


plus.runtime.innerVersion;
				

说明:

String 类型 只读属性

5+运行环境版本号,格式为:[主版本号].[次版本号].[修订版本号].[编译代号]。

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>Runtime Example</title>
		<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener('plusready', onPlusReady, false);
// 扩展API加载完毕,现在可以正常调用扩展API
function onPlusReady(){
	// 获取5+运行环境的版本号
	alert('5+ Runtime version:' + plus.runtime.innerVersion);
}
		</script>
	</head>
	<body>
		5+运行环境的版本号
	</body>
</html>
				

launchLoadedTime

获取当前应用首页加载的时间


plus.runtime.launchLoadedTime;
				

说明:

Number 类型 只读属性

应用加载首页面的总时间,从开始加载首页面到首页面加载完成,单位为ms。 注意,应用首页为网络地址则包括网络传输时间。

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>Runtime Example</title>
		<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener('plusready', onPlusReady, false);
// 扩展API加载完毕,现在可以正常调用扩展API
function onPlusReady(){
	// 处理第三方传入的参数
	alert('首页加载时间:' + plus.runtime.launchLoadedTime + 'ms');
}
		</script>
	</head>
	<body>
		获取当前应用首页加载的时间
	</body>
</html>
				

processId

获取当前应用的进程标识


plus.runtime.processId;
				

说明:

String 类型 只读属性

当前应用所属系统进程标识。

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>Runtime Example</title>
		<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener('plusready', onPlusReady, false);
// 扩展API加载完毕,现在可以正常调用扩展API
function onPlusReady(){
	// 处理第三方传入的参数
	alert('进程标识:' + plus.runtime.processId);
}
		</script>
	</head>
	<body>
		获取当前应用的进程标识
	</body>
</html>
				

startupTime

获取当前应用的启动时间


plus.runtime.startupTime;
				

说明:

Number 类型 只读属性

应用启动时间戳,距1970年1月1日之间的毫秒数。

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>Runtime Example</title>
		<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener('plusready', onPlusReady, false);
// 扩展API加载完毕,现在可以正常调用扩展API
function onPlusReady(){
	// 处理第三方传入的参数
	alert('应用启动时间:' + plus.runtime.startupTime);
}
		</script>
	</head>
	<body>
		获取当前应用的启动时间
	</body>
</html>
				

getProperty

获取指定APPID对应的应用信息


void plus.runtime.getProperty( appid, getPropertyCB );
				

参数:

返回值:

void : 无

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>Runtime Example</title>
		<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕,现在可以正常调用扩展API
function onPlusReady() {
}
// 获取应用信息
function getAppInfo() {
	plus.runtime.getProperty( plus.runtime.appid, function ( wgtinfo ) {
		//appid属性
		var wgtStr = "appid:"+wgtinfo.appid;
		//version属性
		wgtStr += "<br/>version:"+wgtinfo.version;
		//name属性
		wgtStr += "<br/>name:"+wgtinfo.name;
		//description属性
		wgtStr += "<br/>description:"+wgtinfo.description;
		//author属性
		wgtStr += "<br/>author:"+wgtinfo.author;
		//email属性
		wgtStr += "<br/>email:"+wgtinfo.email;
		//licence属性
		wgtStr += "<br/>license:"+wgtinfo.license;
		//licensehref属性
		wgtStr += "<br/>licensehref:"+wgtinfo.licensehref;
		//features 属性
		wgtStr += "<br/>features:"+wgtinfo.features;
		console.log( wgtStr );
	} );
}
		</script>
	</head>
	<body>
		获取应用信息
		<br/>
		<button onclick="getAppInfo()">AppInfo</button>
	</body>
</html>
				

install

安装应用


void plus.runtime.install( wgtFilePath, options, installSuccessCB, installErrorCB);
				

说明:

支持以下类型安装包: 1. 应用资源安装包(wgt),扩展名为'.wgt'; 2. 应用资源差量升级包(wgtu),扩展名为'.wgtu'; 3. 系统程序安装包,要求使用当前平台支持的安装包格式。 注意:仅支持本地地址,调用此方法前需把安装包从网络地址或其他位置放置到运行时环境可以访问的本地目录。

参数:

返回值:

void : 无

平台支持:

quit

退出客户端程序


void plus.runtime.quit();
				

参数:

返回值:

void : 无

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>Runtime Example</title>
		<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕,现在可以正常调用扩展API
function onPlusReady() {
	plus.key.addEventListener( "backbutton", onKeyBack, false );
}
function onKeyBack() {
	plus.runtime.quit();
}
		</script>
	</head>
	<body>
	</body>
</html>
				

restart

重启当前的应用


void plus.runtime.restart();
				

参数:

返回值:

void : 无

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>Runtime Example</title>
		<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕,现在可以正常调用扩展API
function onPlusReady() {
}
// 重启当前的应用
function restartApp() {
	plus.runtime.restart();
}
		</script>
	</head>
	<body>
		重启当前的应用
		<br/>
		<button onclick="restartApp()">Restart</button>
	</body>
</html>
				

setBadgeNumber

设置程序快捷方式上显示的提示数字


void plus.runtime.setBadgeNumber( number );
				

参数:

返回值:

void : 无

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>Runtime Example</title>
		<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕,现在可以正常调用扩展API
function onPlusReady() {
}
// 设置数字
function setBadge() {
	plus.runtime.setBadgeNumber(8);
}
// 清除数字
function clearBadge() {
	plus.runtime.setBadgeNumber(0);
}
		</script>
	</head>
	<body>
		设置程序快捷方式上显示的提示数字
		<br/>
		<button onclick="setBadge()">Set</button>
		<br/>
		<button onclick="clearBadge()">Clear</button>
	</body>
</html>
				

openURL

调用第三方程序打开指定的URL


void plus.runtime.openURL( url, errorCB, identity );
				

参数:

返回值:

void : 无

平台支持:

openFile

调用第三方程序打开指定的文件


void plus.runtime.openFile( filepath, options, errorCB );
				

参数:

返回值:

void : 无

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>Runtime Example</title>
		<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕,现在可以正常调用扩展API
function onPlusReady() {

}
// 打开文件操作
function testFile() {
	plus.runtime.openFile( "_doc/a.pdf" );
}
		</script>
	</head>
	<body>
		调用第三方程序打开文件
		<br/>
		<button onclick="testFile()">Open File</button>
	</body>
</html>
				

processDirectPage

处理直达页面链接参数


String plus.runtime.processDirectPage();
				

说明:

通过URL Scheme启动时,可以在?后面添加__direct_page参数自定义直达页面地址, 如“streamapp://m3w.cn/s/HelloH5?__direct_page=http%3a%2f%2fm.weibo.cn%2fu%2f3196963860”; 在流应用SDK集成时也可以通过direct_page参数(原生调用Intent)设置。 注意:仅第一次调用此API时返回直达页面链接地址,再次调用将返回空字符串;如果应用重新被带直达页面链接参数的URL Scheme启动/激活时,可再次调用此方法获取。

参数:

返回值:

String : 如果启动应用时传入直达页面,则返回直达页面链接地址; 否则返回空字符串。

示例:


<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Runtime Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕,现在可以正常调用扩展API
function onPlusReady() {
	// 应用启动时处理直达页面参数
	processDirectPage();
	document.addEventListener('newintent', function(){
		// 应用被重新激活时处理直达页面参数
		processDirectPage();
	}, false);
}
// 处理直达页面
function processDirectPage(){
	var url = plus.runtime.processDirectPage();
	if(url&&url!==''){
		// 创建新窗口打开并加载
		plus.webview.create(url).show();
	}else{
		console.log('no direct page url.');
	}
}
</script>
</head>
<body>
	处理直达页面链接参数
</body>
</html>
				

launchApplication

调用第三方程序


void plus.runtime.launchApplication( appInf, errorCB );
				

参数:

返回值:

void : 无

平台支持:

示例:


<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Runtime Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕,现在可以正常调用扩展API
function onPlusReady() {

}
// 调用第三方程序
function launchApp() {
	if ( plus.os.name == "Android" ) {
		plus.runtime.launchApplication( {pname:"com.android.browser"
			,extra:{url:"http://www.html5plus.org"}}, function ( e ) {
				alert( "Open system default browser failed: " + e.message );
		} );
	} else if ( plus.os.name == "iOS" ) {
		plus.runtime.launchApplication( {action:"http://www.html5plus.org"}, function ( e ) {
			alert( "Open system default browser failed: " + e.message );
		} );
	}
}
</script>
</head>
<body>
	调用第三方程序
	<br/>
	<button onclick="launchApp()">Launch Application</button>
</body>
</html>
				

isApplicationExist

判断第三方程序是否已存在


Boolean plus.runtime.isApplicationExist(appInf);
				

说明:

如果第三方程序已安装则返回true,未安装则返回false。

参数:

返回值:

Boolean : 第三方程序已安装则返回true,否则返回false。

示例:


<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Runtime Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕,现在可以正常调用扩展API
function onPlusReady() {

}
// 判断第三方程序(微信) 是否安装
function checkApp(){
	if(plus.runtime.isApplicationExist({pname:'com.tencent.mm',action:'weixin://'})){
		console.log("微信应用已安装");
	}else{
		console.log("微信应用未安装");
	}
}
</script>
</head>
<body>
	判断第三方程序是否已存在<br/>
	<button onclick="checkApp()">Check Application</button>
</body>
</html>
				

isCustomLaunchPath

判断是否自定义应用启动页面加载地址


Boolean plus.runtime.isCustomLaunchPath();
				

说明:

通过URL Scheme启动时,可以在?后面添加__launch_path参数自定义应用启动首页加载的页面地址, 如“streamapp://m3w.cn/s/HelloH5?__launch_path=http%3a%2f%2fm.weibo.cn%2fu%2f3196963860”; 在流SDK集成时也可以通过launch_path参数(原生调用Intent)设置。

参数:

返回值:

Boolean : 如果应用自定义页面地址则返回true,否则返回false。

示例:


<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Runtime Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕,现在可以正常调用扩展API
function onPlusReady() {

}
// 判断是否自定义首页地址
function checkLaunchPath(){
	if(plus.runtime.isCustomLaunchPath(){
		console.log("自定义应用首页地址");
	}else{
		console.log("使用应用默认首页地址");
	}
}
</script>
</head>
<body>
	判断是否自定义应用启动页面加载地址<br/>
	<button onclick="checkLaunchPath()">Check LaunchPath</button>
</body>
</html>
				

WidgetOptions

JSON对象,应用安装参数

说明:

可通过对象设置安装的应用是否进行appid校验、版本号校验等。

属性:

平台支持:

示例:


var options = {
	force: true
};
				

WidgetInfo

JSON对象,应用信息

属性:

平台支持:

示例:


var wInfo = {
	appid: "B8B4BD",
	version: "1.0",
	name: "测试应用"
};
				

OpenFileOptions

JSON对象,打开文件参数

属性:

ApplicationInf

JSON对象,打开第三方程序参数

属性:

InstallSuccessCallback

安装应用成功回调函数


void onSuccess(widgetInfo){
	// Code here
}
				

参数:

返回值:

void : 无

平台支持:

InstallErrorCallback

安装应用失败回调函数


void onError(error){
	// Handle the error
}
				

参数:

返回值:

void : 无

平台支持:

GetPropertyCallBack

获取应用属性成功回调函数


void onGetPropertyCB(widgetInfo){
	// Code here
}
				

参数:

返回值:

void : 无

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8">
		<title>Runtime Example</title>
		<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕,现在可以正常调用扩展API
function onPlusReady() {
}
// 获取应用信息
function getAppInfo() {
	plus.runtime.getProperty( plus.runtime.appid, function ( wgtinfo ) {
		//appid属性
		var wgtStr = "appid:"+wgtinfo.appid;
		//version属性
		wgtStr += "<br/>version:"+wgtinfo.version;
		//name属性
		wgtStr += "<br/>name:"+wgtinfo.name;
		//description属性
		wgtStr += "<br/>description:"+wgtinfo.description;
		//author属性
		wgtStr += "<br/>author:"+wgtinfo.author;
		//email属性
		wgtStr += "<br/>email:"+wgtinfo.email;
		//licence属性
		wgtStr += "<br/>license:"+wgtinfo.license;
		//licensehref属性
		wgtStr += "<br/>licensehref:"+wgtinfo.licensehref;
		//features 属性
		wgtStr += "<br/>features:"+wgtinfo.features;
		console.log( wgtStr );
	} );
}
		</script>
	</head>
	<body>
		获取应用信息
		<br/>
		<button onclick="getAppInfo()">AppInfo</button>
	</body>
</html>
				

OpenErrorCallback

打开本地文件或URL失败回调函数


void onError(error){
	// Handle the error
}
				

参数:

返回值:

void : 无

平台支持:

LaunchErrorCallback

调用第三方程序失败回调函数


void onError(error){
	// Handle the error
}
				

参数:

返回值:

void : 无

平台支持: