runtime

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

属性:

方法:

对象:

回调方法:

权限:

5+功能模块(permissions)

  1. {
  2. // ...
  3. "permissions":{
  4. // ...
  5. "Runtime": {
  6. "description": "运行环境"
  7. }
  8. }
  9. }

appid

当前应用的APPID

  1. plus.runtime.appid;

说明:

String类型 只读属性

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

示例:

  1. //当前应用的APPID
  2. function getAppid(){
  3. alert('Current APP:' + plus.runtime.appid);
  4. }

uni-app使用plus注意事项

arguments

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

  1. 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启动应用时也没有协议头数据(前缀)。

示例:

  1. //第三方程序调用时传递给程序的参数
  2. //5+ APP通常在plusredy后调用
  3. function getArguments(){
  4. // 处理第三方传入的参数
  5. if(plus.runtime.arguments != ""){
  6. try{
  7. var aj = JSON.parse(plus.runtime.arguments);
  8. // 处理JSON对象aj
  9. }catch(e){
  10. // 若传入的参数不是JSON格式字符,需处理异常情况
  11. }
  12. }
  13. }

uni-app使用plus注意事项

channel

应用的渠道标识

  1. plus.runtime.channel;

说明:

String类型 只读属性

如果应用没有设置渠道标识,则返回空字符串。以下是流应用环境中使用的特殊渠道标识:
  • "qihoo:browser" - 表示360浏览器流应用
  • "qihoo:appstore " - 表示360手机助手流应用
  • "dcloud:streamapps" - 表示DCloud流应用基座

示例:

  1. // 应用的渠道标识
  2. function getChannel(){
  3. alert('Current Channel:' + plus.runtime.channel);
  4. }

uni-app使用plus注意事项

launcher

应用启动来源

  1. plus.runtime.launcher;

说明:

String类型 只读属性

5+ APP启动类型,可取以下值:
  • "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

应用安装来源

  1. plus.runtime.origin;

说明:

String类型 只读属性

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

version

客户端的版本名称

  1. plus.runtime.version;

说明:

String类型 只读属性

字符串类型,在编译环境中设置的apk/ipa版本名称。Android平台对应AndroidManifest.xml中的android:versionName属性值;iOS平台对应Info.plist中的CFBundleShortVersionString字段值。

示例:

  1. //客户端(apk/ipa)的版本名称
  2. function getVersion(){
  3. // 获取apk/ipa版本名称
  4. alert('Application(apk/ipa) version:' + plus.runtime.version);
  5. }

uni-app使用plus注意事项

versionCode

客户端的版本号

  1. plus.runtime.versionCode;

说明:

String类型 只读属性

字符串类型,仅包含数字。Android平台对应AndroidManifest.xml中的android:versionCode属性值;iOS平台对应Info.plist中CFBundleVersion字段值。

示例:

  1. //客户端(apk/ipa)的版本号
  2. function getVersionCode(){
  3. // 获取apk/ipa版本号
  4. alert('Application(apk/ipa) version:' + plus.runtime.versionCode);
  5. }

uni-app使用plus注意事项

innerVersion

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

  1. plus.runtime.innerVersion;

说明:

String类型 只读属性

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

示例:

  1. // 5+运行环境的内部版本号
  2. function getInnerVersion(){
  3. // 获取5+运行环境的版本号
  4. alert('5+ Runtime version:' + plus.runtime.innerVersion);
  5. }

uni-app使用plus注意事项

uniVersion

客户端uni-app运行环境的版本号

  1. plus.runtime.uniVersion;

说明:

String类型 只读属性

uni-app运行环境版本号,格式为:[主版本号].[次版本号].[修订版本号]。注意:仅在uni-app应用中才能获取此版本号,非uni-app应用中返回空字符串。

示例:

  1. // uni-app运行环境版本号
  2. function getUniVersion(){
  3. // 获取uni-app运行环境版本号
  4. alert('uni-app Runtime version:' + plus.runtime.uniVersion);
  5. }

uni-app使用plus注意事项

launchLoadedTime

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

  1. plus.runtime.launchLoadedTime;

说明:

Number类型 只读属性

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

示例:

  1. // 获取当前应用首页加载的时间
  2. function onPlusReady(){
  3. alert('首页加载时间:' + plus.runtime.launchLoadedTime + 'ms');
  4. }

uni-app使用plus注意事项

processId

获取当前应用的进程标识

  1. plus.runtime.processId;

说明:

String类型 只读属性

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

示例:

  1. // 获取当前应用的进程标识
  2. function onPlusReady(){
  3. alert('进程标识:' + plus.runtime.processId);
  4. }

uni-app使用plus注意事项

startupTime

获取当前应用的启动时间戳

  1. plus.runtime.startupTime;

说明:

Number类型 只读属性

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

示例:

  1. // 获取当前应用的启动时间戳
  2. function onPlusReady(){
  3. alert('应用启动时间:' + plus.runtime.startupTime);
  4. }

uni-app使用plus注意事项

isRecovery

应用是否由于内核崩溃自动恢复

  1. plus.runtime.isRecovery;

说明:

Boolean类型 只读属性

如果应用是由于内核(WKWebview)崩溃恢复则返回true,否则返回false。注意:仅iOS平台使用WKWebview内核时生效。

示例:

  1. // 获取当前应用是否由于内核崩溃自动恢复
  2. function onPlusReady(){
  3. alert('应用由内核崩溃恢复:' + plus.runtime.isRecovery);
  4. }

uni-app使用plus注意事项

getProperty

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

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

参数:

  • appid: (String)必选 应用的Appid
  • getPropertyCB: (GetPropertyCallBack)必选 获得应用信息成功回调函数

返回值:

void: 无

示例:

  1. // 获取应用信息
  2. function getAppInfo() {
  3. plus.runtime.getProperty( plus.runtime.appid, function ( wgtinfo ) {
  4. //appid属性
  5. var wgtStr = "appid:"+wgtinfo.appid;
  6. //version属性
  7. wgtStr += "<br/>version:"+wgtinfo.version;
  8. //name属性
  9. wgtStr += "<br/>name:"+wgtinfo.name;
  10. //description属性
  11. wgtStr += "<br/>description:"+wgtinfo.description;
  12. //author属性
  13. wgtStr += "<br/>author:"+wgtinfo.author;
  14. //email属性
  15. wgtStr += "<br/>email:"+wgtinfo.email;
  16. //features 属性
  17. wgtStr += "<br/>features:"+wgtinfo.features;
  18. console.log( wgtStr );
  19. } );
  20. }

uni-app使用plus注意事项

install

安装应用

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

退出应用

  1. void plus.runtime.quit();

说明:

5+APP:退出应用,返回系统桌面;流应用:在“流应用”中调用则退出当前流应用,返回进入应用前的界面(如应用列表)。

参数:

返回值:

void: 无

平台支持:

  • Android- 2.2+(支持): 支持
  • iOS- 4.3+(支持): 5+APP:不支持此功能,调用后无任何作用,只能通过设备的Home键退出应用。

示例:

  1. // 退出应用
  2. function quitApp() {
  3. plus.runtime.quit();
  4. }

uni-app使用plus注意事项

restart

重启当前的应用

  1. void plus.runtime.restart();

说明:

应用热重启,重新启动进入首页。

参数:

返回值:

void: 无

示例:

  1. // 重启当前的应用
  2. function restartApp() {
  3. plus.runtime.restart();
  4. }

uni-app使用plus注意事项

setBadgeNumber

设置程序快捷方式图标上显示的角标数字

  1. void plus.runtime.setBadgeNumber(number, options);

参数:

  • number: (Number)必选 要显示的角标数字值,参数为0则表示清除角标数字。
  • options: (BadgeOptions)可选 小米手机显示角标需要在系统消息中心显示一条通知,此参数用于设置通知的标题(title)和内容(content)。

返回值:

void: 无

平台支持:

  • Android- 2.2+(支持): 目前仅支持小米(MIUI6及以上)和华为设备,其它设备调用后无任何效果。
  • iOS- 4.3+(支持): 应用需开启“Push Notifications”服务才生效。

示例:

  1. // 设置数字
  2. function setBadge() {
  3. plus.runtime.setBadgeNumber(8);
  4. }
  5. // 清除数字
  6. function clearBadge() {
  7. plus.runtime.setBadgeNumber(0);
  8. }

uni-app使用plus注意事项

openURL

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

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

  1. void plus.runtime.openWeb(url);

参数:

  • url: (String)必选 要打开的URL地址字符串类型,仅支持http/https地址。

返回值:

void: 无

openFile

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

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

参数:

  • filepath: (String)必选 打开文件的路径字符串类型,文件路径必须是本地路径,否则会导致打开文件失败。
  • options: (OpenFileOptions)可选 打开文件参数
  • errorCB: (OpenErrorCallback)必选 打开文件失败的回调打开文件操作失败时回调,返回失败信息。

返回值:

void: 无

示例:

  1. // 打开文件操作
  2. function openFile() {
  3. plus.runtime.openFile( "_doc/a.pdf" );
  4. }

uni-app使用plus注意事项

processDirectPage

处理直达页面链接参数

  1. 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: 如果启动应用时传入直达页面,则返回直达页面链接地址;否则返回空字符串。

示例:

  1. // 处理直达页面
  2. // 仅流应用支持,在plusready事件中调用
  3. function processDirectPage(){
  4. var url = plus.runtime.processDirectPage();
  5. if(url&&url!==''){
  6. // 创建新窗口打开并加载
  7. plus.webview.create(url).show();
  8. }else{
  9. console.log('no direct page url.');
  10. }
  11. }

uni-app使用plus注意事项

launchApplication

调用第三方程序

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

参数:

  • appInf: (ApplicationInf)必选 要启动第三方程序的描述信息
  • errorCB: (LaunchErrorCallback)必选 启动第三方程序操作失败的回调函数启动第三方程序失败时回调,并返回失败信息。

返回值:

void: 无

平台支持:

  • Android- 2.2+(支持): 支持
  • iOS- 4.3+(支持): 支持

示例:

  1. // 调用第三方程序
  2. function launchApp() {
  3. if ( plus.os.name == "Android" ) {
  4. plus.runtime.launchApplication( {pname:"com.android.browser"
  5. ,extra:{url:"http://www.html5plus.org"}}, function ( e ) {
  6. alert( "Open system default browser failed: " + e.message );
  7. } );
  8. } else if ( plus.os.name == "iOS" ) {
  9. plus.runtime.launchApplication( {action:"http://www.html5plus.org"}, function ( e ) {
  10. alert( "Open system default browser failed: " + e.message );
  11. } );
  12. }
  13. }

uni-app使用plus注意事项

isApplicationExist

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

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

示例:

  1. // 判断第三方程序(微信) 是否安装
  2. function checkApp(){
  3. if(plus.runtime.isApplicationExist({pname:'com.tencent.mm',action:'weixin://'})){
  4. console.log("微信应用已安装");
  5. }else{
  6. console.log("微信应用未安装");
  7. }
  8. }

uni-app使用plus注意事项

isCustomLaunchPath

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

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

示例:

  1. // 判断是否自定义首页地址
  2. function checkLaunchPath(){
  3. if(plus.runtime.isCustomLaunchPath(){
  4. console.log("自定义应用首页地址");
  5. }else{
  6. console.log("使用应用默认首页地址");
  7. }
  8. }

uni-app使用plus注意事项

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

安装应用成功回调函数

  1. void onSuccess(widgetInfo){
  2. // Code here
  3. }

参数:

  • widgetInfo: (WidgetInfo)必选 应用信息,参见:WidgetInfo

返回值:

void: 无

平台支持:

  • Android- 2.2+(支持): 支持,如安装文件为APK,则不触发此回调函数
  • iOS- 4.3+(支持): 支持

InstallErrorCallback

安装应用失败回调函数

  1. void onError(error){
  2. // Handle the error
  3. }

参数:

  • error: (DOMException)必选 安装失败的错误信息

返回值:

void: 无

GetPropertyCallBack

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

  1. void onGetPropertyCB(widgetInfo){
  2. // Code here
  3. }

参数:

  • widgetInfo: (WidgetInfo)必选 应用信息包括应用名称、标识等属性。

返回值:

void: 无

示例:

  1. // 获取应用信息
  2. function getAppInfo() {
  3. plus.runtime.getProperty( plus.runtime.appid, function(wgtinfo){
  4. //appid属性
  5. var wgtStr = "appid:"+wgtinfo.appid;
  6. //version属性
  7. wgtStr += "<br/>version:"+wgtinfo.version;
  8. //name属性
  9. wgtStr += "<br/>name:"+wgtinfo.name;
  10. //description属性
  11. wgtStr += "<br/>description:"+wgtinfo.description;
  12. //author属性
  13. wgtStr += "<br/>author:"+wgtinfo.author;
  14. //email属性
  15. wgtStr += "<br/>email:"+wgtinfo.email;
  16. //licence属性
  17. wgtStr += "<br/>license:"+wgtinfo.license;
  18. //licensehref属性
  19. wgtStr += "<br/>licensehref:"+wgtinfo.licensehref;
  20. //features 属性
  21. wgtStr += "<br/>features:"+wgtinfo.features;
  22. console.log( wgtStr );
  23. } );
  24. }

uni-app使用plus注意事项

OpenErrorCallback

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

  1. void onError(error){
  2. // Handle the error
  3. }

参数:

  • error: (DOMException)必选 打开操作失败的错误信息

返回值:

void: 无

LaunchErrorCallback

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

  1. void onError(error){
  2. // Handle the error
  3. }

参数:

  • error: (DOMException)必选 操作失败的错误信息可通过error.code(Number类型)获取错误编码;可通过error.message(String类型)获取错误描述信息。

返回值:

void: 无