- runtime
- appid
- arguments
- channel
- launcher
- origin
- version
- versionCode
- innerVersion
- uniVersion
- launchLoadedTime
- processId
- startupTime
- isRecovery
- getProperty
- install
- quit
- restart
- setBadgeNumber
- openURL
- openWeb
- openFile
- processDirectPage
- launchApplication
- isApplicationExist
- isCustomLaunchPath
- ApplicationInf
- BadgeOptions
- OpenFileOptions
- WidgetInfo
- WidgetOptions
- InstallSuccessCallback
- InstallErrorCallback
- GetPropertyCallBack
- OpenErrorCallback
- LaunchErrorCallback
runtime
Runtime模块管理运行环境,可用于获取当前运行环境信息、与其它程序进行通讯等。通过plus.runtime可获取运行环境管理对象。
属性:
- appid: 当前应用的APPID
- arguments: 第三方程序调用时传递给程序的参数
- channel: 应用的渠道标识
- launcher: 应用启动来源
- origin: 应用安装来源
- version: 客户端的版本名称
- versionCode: 客户端的版本号
- innerVersion: 客户端5+运行环境的内部版本号
- uniVersion: 客户端uni-app运行环境的版本号
- launchLoadedTime: 获取当前应用首页加载的时间
- processId: 获取当前应用的进程标识
- startupTime: 获取当前应用的启动时间戳
- isRecovery: 应用是否由于内核崩溃自动恢复
方法:
- getProperty: 获取指定APPID对应的应用信息
- install: 安装应用
- quit: 退出应用
- restart: 重启当前的应用
- setBadgeNumber: 设置程序快捷方式图标上显示的角标数字
- openURL: 调用第三方程序打开指定的URL
- openWeb: 使用内置Webview窗口打开URL
- openFile: 调用第三方程序打开指定的文件
- processDirectPage: 处理直达页面链接参数
- launchApplication: 调用第三方程序
- isApplicationExist: 判断第三方程序是否已存在
- isCustomLaunchPath: 判断是否自定义应用启动页面加载地址
对象:
- ApplicationInf: JSON对象,打开第三方程序参数
- BadgeOptions: JSON对象,应用角标显示需要的通知栏消息的参数
- OpenFileOptions: JSON对象,打开文件参数
- WidgetInfo: JSON对象,应用信息
- WidgetOptions: JSON对象,应用安装参数
回调方法:
- InstallSuccessCallback: 安装应用成功回调函数
- InstallErrorCallback: 安装应用失败回调函数
- GetPropertyCallBack: 获取应用属性成功回调函数
- OpenErrorCallback: 打开本地文件或URL失败回调函数
- LaunchErrorCallback: 调用第三方程序失败回调函数
权限:
5+功能模块(permissions)
{
// ...
"permissions":{
// ...
"Runtime": {
"description": "运行环境"
}
}
}
appid
当前应用的APPID
plus.runtime.appid;
说明:
String类型 只读属性
当前应用的APPID,字符串类型。注意,如果是在HBuilder真机运行获取的是固定值"HBuilder",需要提交App云端打包后运行才能获取真实的APPID值。
示例:
//当前应用的APPID
function getAppid(){
alert('Current APP:' + plus.runtime.appid);
}
arguments
第三方程序调用时传递给程序的参数
plus.runtime.arguments;
说明:
String类型 只读属性
第三方程序传递过来的参数,字符串格式类型数据。不是由第三方程序调用启动,则返回空字符串。
平台支持:
- Android- 2.2+(支持): 如果是第三方APP调用,则把传递过来的参数组合成JSON格式字符串,如“{"name":"XiaoMing","password":"123456"}”;如果是通过URL Scheme调用则将协议头(前缀)和参数组合成字符串,如“streamapp://name=XiaoMing&password=123456”。
- iOS- 4.3+(支持): 把第三方传递过来的参数组合成字符串,如“name=XiaoMing&password=123456”,建议第三方程序传递JSON格式字符串;注:由于iOS平台原生传递参数与URL Scheme一致,通过URL Scheme启动应用时也没有协议头数据(前缀)。
示例:
//第三方程序调用时传递给程序的参数
//5+ APP通常在plusredy后调用
function getArguments(){
// 处理第三方传入的参数
if(plus.runtime.arguments != ""){
try{
var aj = JSON.parse(plus.runtime.arguments);
// 处理JSON对象aj
}catch(e){
// 若传入的参数不是JSON格式字符,需处理异常情况
}
}
}
channel
应用的渠道标识
plus.runtime.channel;
说明:
String类型 只读属性
- "qihoo:browser" - 表示360浏览器流应用
- "qihoo:appstore " - 表示360手机助手流应用
- "dcloud:streamapps" - 表示DCloud流应用基座
示例:
// 应用的渠道标识
function getChannel(){
alert('Current Channel:' + plus.runtime.channel);
}
launcher
应用启动来源
plus.runtime.launcher;
说明:
String类型 只读属性
- "default":默认启动方式,通常表示应用列表启动(360手助中搜索启动)
- "scheme":通过urlscheme方式触发启动
- "push":通过点击系统通知方式触发启动
- "stream":通过流应用api(plus.stream.open)启动
- "shortcut":通过快捷方式启动,iOS平台表示通过3D Touch快捷方式,Android平台表示通过桌面快捷方式启动
- "barcode":通过二维码扫描启动
- "myapp":通过流应用"我的"应用列表或历史列表中触发启动
- "favorite":通过流应用的"收藏"应用列表启动
- "browser":通过流应用的内置浏览器导流启动的流应用(地址栏输入url启动应用、点击wap页面链接启动应用)
- "engines":通过流应用的浏览器界面作为搜索引擎启动
- "search":通过流应用的应用搜索启动应用(如iOS平台的T9键盘搜索)
- "speech":通过流应用的语音识别启动应用
- "uniLink":通过通用链接(universal link)启动应用
- "miniProgram":通过微信小程序启动应用
平台支持:
- Android- 2.2+(支持): "shortcut"表示通过桌面快捷方式启动。
- iOS- 5.1+(支持): "shortcut"表示通过3D Touch弹出的快捷方式启动。
origin
应用安装来源
plus.runtime.origin;
说明:
String类型 只读属性
- "default":默认安装来源,apk/ipa安装包内置安装
- "stream":通过流应用api(plus.stream.open)安装,仅流应用环境下支持
- "push":通过点击系统通知方式触发安装,仅流应用环境下支持
- "scheme":通过urlscheme方式触发安装,仅流应用环境下支持
- "barcode":通过二维码扫描触发安装,仅流应用环境下支持
- "silent":通过后台静默方式安装,仅流应用环境下支持
- "speech":通过语音识别方式触发安装,仅流应用环境下支持
- "favorite":通过收藏界面启动触发安装,仅流应用环境下支持
version
客户端的版本名称
plus.runtime.version;
说明:
String类型 只读属性
字符串类型,在编译环境中设置的apk/ipa版本名称。Android平台对应AndroidManifest.xml中的android:versionName属性值;iOS平台对应Info.plist中的CFBundleShortVersionString字段值。
示例:
//客户端(apk/ipa)的版本名称
function getVersion(){
// 获取apk/ipa版本名称
alert('Application(apk/ipa) version:' + plus.runtime.version);
}
versionCode
客户端的版本号
plus.runtime.versionCode;
说明:
String类型 只读属性
字符串类型,仅包含数字。Android平台对应AndroidManifest.xml中的android:versionCode属性值;iOS平台对应Info.plist中CFBundleVersion字段值。
示例:
//客户端(apk/ipa)的版本号
function getVersionCode(){
// 获取apk/ipa版本号
alert('Application(apk/ipa) version:' + plus.runtime.versionCode);
}
innerVersion
客户端5+运行环境的内部版本号
plus.runtime.innerVersion;
说明:
String类型 只读属性
5+运行环境内部版本号,格式为:[主版本号].[次版本号].[修订版本号].[编译代号]。
示例:
// 5+运行环境的内部版本号
function getInnerVersion(){
// 获取5+运行环境的版本号
alert('5+ Runtime version:' + plus.runtime.innerVersion);
}
uniVersion
客户端uni-app运行环境的版本号
plus.runtime.uniVersion;
说明:
String类型 只读属性
uni-app运行环境版本号,格式为:[主版本号].[次版本号].[修订版本号]。注意:仅在uni-app应用中才能获取此版本号,非uni-app应用中返回空字符串。
示例:
// uni-app运行环境版本号
function getUniVersion(){
// 获取uni-app运行环境版本号
alert('uni-app Runtime version:' + plus.runtime.uniVersion);
}
launchLoadedTime
获取当前应用首页加载的时间
plus.runtime.launchLoadedTime;
说明:
Number类型 只读属性
应用加载首页面的总时间,从开始加载首页面到首页面加载完成,单位为ms。注意,应用首页为网络地址则包括网络传输时间。
示例:
// 获取当前应用首页加载的时间
function onPlusReady(){
alert('首页加载时间:' + plus.runtime.launchLoadedTime + 'ms');
}
processId
获取当前应用的进程标识
plus.runtime.processId;
说明:
String类型 只读属性
当前应用所属系统进程标识。
示例:
// 获取当前应用的进程标识
function onPlusReady(){
alert('进程标识:' + plus.runtime.processId);
}
startupTime
获取当前应用的启动时间戳
plus.runtime.startupTime;
说明:
Number类型 只读属性
应用启动时间戳,距1970年1月1日之间的毫秒数。
示例:
// 获取当前应用的启动时间戳
function onPlusReady(){
alert('应用启动时间:' + plus.runtime.startupTime);
}
isRecovery
应用是否由于内核崩溃自动恢复
plus.runtime.isRecovery;
说明:
Boolean类型 只读属性
如果应用是由于内核(WKWebview)崩溃恢复则返回true,否则返回false。注意:仅iOS平台使用WKWebview内核时生效。
示例:
// 获取当前应用是否由于内核崩溃自动恢复
function onPlusReady(){
alert('应用由内核崩溃恢复:' + plus.runtime.isRecovery);
}
getProperty
获取指定APPID对应的应用信息
void plus.runtime.getProperty( appid, getPropertyCB );
参数:
- appid: (String)必选 应用的Appid
- getPropertyCB: (GetPropertyCallBack)必选 获得应用信息成功回调函数
返回值:
void: 无
示例:
// 获取应用信息
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;
//features 属性
wgtStr += "<br/>features:"+wgtinfo.features;
console.log( wgtStr );
} );
}
install
安装应用
void plus.runtime.install(filePath, options, installSuccessCB, installErrorCB);
说明:
支持以下类型安装包:1. 应用资源安装包(wgt),扩展名为'.wgt';2. 应用资源差量升级包(wgtu),扩展名为'.wgtu';3. 系统程序安装包(apk),要求使用当前平台支持的安装包格式。注意:仅支持本地地址,调用此方法前需把安装包从网络地址或其他位置放置到运行时环境可以访问的本地目录。
参数:
- filePath: (String)必选 要安装的文件路径支持应用资源安装包(wgt)、应用资源差量升级包(wgtu)、系统程序包(apk)。
- options: (WidgetOptions)可选 应用安装设置的参数
- installSuccessCB: (InstallSuccessCallback)可选 正确安装后的回调
- installErrorCB: (InstallErrorCallback)可选 安装失败的回调
返回值:
void: 无
平台支持:
- Android- 2.2+(支持): 可支持apk包的安装
- iOS- 4.3+(支持): 不支持ipa包的安装
quit
退出应用
void plus.runtime.quit();
说明:
5+APP:退出应用,返回系统桌面;流应用:在“流应用”中调用则退出当前流应用,返回进入应用前的界面(如应用列表)。
参数:
无
返回值:
void: 无
平台支持:
- Android- 2.2+(支持): 支持
- iOS- 4.3+(支持): 5+APP:不支持此功能,调用后无任何作用,只能通过设备的Home键退出应用。
示例:
// 退出应用
function quitApp() {
plus.runtime.quit();
}
restart
重启当前的应用
void plus.runtime.restart();
说明:
应用热重启,重新启动进入首页。
参数:
无
返回值:
void: 无
示例:
// 重启当前的应用
function restartApp() {
plus.runtime.restart();
}
setBadgeNumber
设置程序快捷方式图标上显示的角标数字
void plus.runtime.setBadgeNumber(number, options);
参数:
- number: (Number)必选 要显示的角标数字值,参数为0则表示清除角标数字。
- options: (BadgeOptions)可选 小米手机显示角标需要在系统消息中心显示一条通知,此参数用于设置通知的标题(title)和内容(content)。
返回值:
void: 无
平台支持:
- Android- 2.2+(支持): 目前仅支持小米(MIUI6及以上)和华为设备,其它设备调用后无任何效果。
- iOS- 4.3+(支持): 应用需开启“Push Notifications”服务才生效。
示例:
// 设置数字
function setBadge() {
plus.runtime.setBadgeNumber(8);
}
// 清除数字
function clearBadge() {
plus.runtime.setBadgeNumber(0);
}
openURL
调用第三方程序打开指定的URL
void plus.runtime.openURL( url, errorCB, identity );
参数:
- url: (String)必选 要打开的URL地址字符串类型,各平台支持的地址类型存在差异,参考平台URL支持表。
- errorCB: (OpenErrorCallback)可选 打开URL地址失败的回调打开指定URL地址失败时回调,并返回失败信息。
- identity: (String)可选 指定打开URL地址的程序名称在iOS平台此参数被忽略,在Android平台为程序包名,如果指定的包名不存在,则打开URL地址失败。
返回值:
void: 无
平台支持:
- Android- 2.2+(支持): 支持
- iOS- 4.3+(支持): 支持,不支持identity参数
openWeb
使用内置Webview窗口打开URL
void plus.runtime.openWeb(url);
参数:
- url: (String)必选 要打开的URL地址字符串类型,仅支持http/https地址。
返回值:
void: 无
openFile
调用第三方程序打开指定的文件
void plus.runtime.openFile( filepath, options, errorCB );
参数:
- filepath: (String)必选 打开文件的路径字符串类型,文件路径必须是本地路径,否则会导致打开文件失败。
- options: (OpenFileOptions)可选 打开文件参数
- errorCB: (OpenErrorCallback)必选 打开文件失败的回调打开文件操作失败时回调,返回失败信息。
返回值:
void: 无
示例:
// 打开文件操作
function openFile() {
plus.runtime.openFile( "_doc/a.pdf" );
}
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: 如果启动应用时传入直达页面,则返回直达页面链接地址;否则返回空字符串。
示例:
// 处理直达页面
// 仅流应用支持,在plusready事件中调用
function processDirectPage(){
var url = plus.runtime.processDirectPage();
if(url&&url!==''){
// 创建新窗口打开并加载
plus.webview.create(url).show();
}else{
console.log('no direct page url.');
}
}
launchApplication
调用第三方程序
void plus.runtime.launchApplication( appInf, errorCB );
参数:
- appInf: (ApplicationInf)必选 要启动第三方程序的描述信息
- errorCB: (LaunchErrorCallback)必选 启动第三方程序操作失败的回调函数启动第三方程序失败时回调,并返回失败信息。
返回值:
void: 无
平台支持:
- Android- 2.2+(支持): 支持
- iOS- 4.3+(支持): 支持
示例:
// 调用第三方程序
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 );
} );
}
}
isApplicationExist
判断第三方程序是否已存在
Boolean plus.runtime.isApplicationExist(appInf);
说明:
如果第三方程序已安装则返回true,未安装则返回false。
参数:
- appInf: (ApplicationInf)必选 要判断第三方程序的描述信息Android平台需要通过设置appInf的pname属性(包名)进行查询。iOS平台需要通过设置appInf的action属性(Scheme)进行查询,在iOS9以后需要添加白名单才可查询,在manifest.json文件plus->distribute->apple->urlschemewhitelist节点下添加(如urlschemewhitelist:["weixin"]).
返回值:
Boolean: 第三方程序已安装则返回true,否则返回false。
示例:
// 判断第三方程序(微信) 是否安装
function checkApp(){
if(plus.runtime.isApplicationExist({pname:'com.tencent.mm',action:'weixin://'})){
console.log("微信应用已安装");
}else{
console.log("微信应用未安装");
}
}
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。
示例:
// 判断是否自定义首页地址
function checkLaunchPath(){
if(plus.runtime.isCustomLaunchPath(){
console.log("自定义应用首页地址");
}else{
console.log("使用应用默认首页地址");
}
}
ApplicationInf
JSON对象,打开第三方程序参数
属性:
- pname: (String类型)第三方程序包名仅Android平台支持,表示程序的包名,其它平台忽略此属性值。
平台支持
- Android - 2.2+ (支持): 第三方程序的包名,如“io.dclould.HelloH5”。
- iOS - ALL (不支持): 忽略此属性值。
- action: (String类型)程序的操作行为Android平台上与系统的action值一致;iOS平台为要调用程序的URLScheme格式字符串。
平台支持
- Android - 2.2+ (支持): 第三方程序的操作行为,与系统的action值完全一致。
- iOS - 4.3+ (支持): 要调用程序的URLScheme格式字符串。
- newTask: (Boolean类型)新任务模式标记可取值:true-使用新任务模式标记(FLAG_ACTIVITY_NEW_TASK)启动应用;false-不使用新任务模式标记(FLAG_ACTIVITY_NEW_TASK)启动应用。默认值为true。注意:由于5+应用配置的launchMode为singleTask,所以另一个5+应用通过plus.runtime.launchApplication启动时如果应用已经在后台运行则不会触发newintent事件,为了避免此问题需要将newTask参数值设置为false。
平台支持
- Android - 2.2+ (支持)
- iOS - ALL (不支持): 忽略此属性值。
- extra: (JSON类型)调用程序的参数仅Android平台支持,为JSON格式,用于传递给要调用程序的参数,如extra:{url:"http://www.html5plus.org"}。
平台支持
- Android - 2.2+ (支持): 传递给第三方程序的参数,必须是JSON格式数据,如“{'name':'value','name2':'value2'}”。
- iOS - ALL (不支持): 忽略此属性值。
BadgeOptions
JSON对象,应用角标显示需要的通知栏消息的参数
属性:
title: (String类型)消息的标题默认值为应用的名称。
content: (String类型)消息的内容默认值为“您有x条未读消息"”,其中x未设置的角标数字值。
OpenFileOptions
JSON对象,打开文件参数
属性:
pname: (String类型)优先使用的程序包名如果指定包名的程序已经安装,则调用其打开文件,若程序不支持打开文件则触发错误回调。如果指定包名的程序未安装,则弹出系统支持打开此文件的列表,由用户选择程序打开。
popover: (json类型)弹出系统选择程序界面指示区域JSON对象,格式如{top:10;left:10;width:200;height:200;},所有值为像素值,左上坐标相对于容器webview的位置。仅在iPad设备平台有效。
WidgetInfo
JSON对象,应用信息
属性:
appid: (String类型)应用的APPID对应manifest.json中的id字段值。
version: (String类型)应用的版本名称对应manifest.json中的version->name字段值。
versionCode: (String类型)应用的版本号对应manifest.json中的version->code字段值。
name: (String类型)应用的名称对应manifest.json中的name字段值。
description: (String类型)应用描述信息对应manifest.json中的description字段值。
author: (String类型)应用描述信息对应manifest.json中的developer->name字段值。
email: (String类型)开发者邮箱地址对应manifest.json中的developer->email字段值。
features: (String[]类型)应用许可特性列表对应manifest.json中的permissions字段下所有键名的列表。
WidgetOptions
JSON对象,应用安装参数
说明:
可通过对象设置安装的应用是否进行appid校验、版本号校验等。
属性:
- force: (Boolean类型)是否强制安装true表示强制安装,不进行版本号的校验;false则需要版本号校验,如果将要安装应用的版本号不高于现有应用的版本号则终止安装,并返回安装失败。仅安装wgt和wgtu时生效,默认值 false。
InstallSuccessCallback
安装应用成功回调函数
void onSuccess(widgetInfo){
// Code here
}
参数:
- widgetInfo: (WidgetInfo)必选 应用信息,参见:WidgetInfo
返回值:
void: 无
平台支持:
- Android- 2.2+(支持): 支持,如安装文件为APK,则不触发此回调函数
- iOS- 4.3+(支持): 支持
InstallErrorCallback
安装应用失败回调函数
void onError(error){
// Handle the error
}
参数:
- error: (DOMException)必选 安装失败的错误信息
返回值:
void: 无
GetPropertyCallBack
获取应用属性成功回调函数
void onGetPropertyCB(widgetInfo){
// Code here
}
参数:
- widgetInfo: (WidgetInfo)必选 应用信息包括应用名称、标识等属性。
返回值:
void: 无
示例:
// 获取应用信息
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 );
} );
}
OpenErrorCallback
打开本地文件或URL失败回调函数
void onError(error){
// Handle the error
}
参数:
- error: (DOMException)必选 打开操作失败的错误信息
返回值:
void: 无
LaunchErrorCallback
调用第三方程序失败回调函数
void onError(error){
// Handle the error
}
参数:
- error: (DOMException)必选 操作失败的错误信息可通过error.code(Number类型)获取错误编码;可通过error.message(String类型)获取错误描述信息。
返回值:
void: 无