runtime

优质

小牛编辑

124浏览

2023-12-01

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

属性：

appid: 当前应用的APPID
arguments: 第三方程序调用时传递给程序的参数
channel: 应用的渠道标识
launcher: 应用启动来源
origin: 应用安装来源
version: 客户端的版本名称
versionCode: 客户端的版本号
innerVersion: 客户端5+运行环境的内部版本号
uniVersion: 客户端uni-app运行环境的版本号
launchLoadedTime: 获取当前应用首页加载的时间
processId: 获取当前应用的进程标识
startupTime: 获取当前应用的启动时间戳
isRecovery: 应用是否由于内核崩溃自动恢复

方法：

agreePrivacy: 用户同意隐私政策
disagreePrivacy: 用户不同意隐私政策
isAgreePrivacy: 查询用户是否同意隐私政策
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": "运行环境"
	}
}
}

launcher

应用启动来源


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

应用安装来源


plus.runtime.origin;

说明：

String 类型只读属性

5+应用安装来源，可取以下值：

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

agreePrivacy

用户同意隐私政策


void plus.runtime.agreePrivacy();

说明：

HBuilderX2.5.11+版本支持，配置为自定义隐私政策提示框时有效，参考： https://ask.dcloud.net.cn/article/36937
设置应用状态为用户同意隐私政策，可通过plus.runtime.isAgreePrivacy判断是否已经同意。

参数：

无

返回值：

void : 无

disagreePrivacy

用户不同意隐私政策


void plus.runtime.disagreePrivacy();

说明：

HBuilderX2.5.11+版本支持，配置为自定义隐私政策提示框时有效，参考： https://ask.dcloud.net.cn/article/36937
设置应用状态为用户不同意隐私政策，可通过plus.runtime.isAgreePrivacy判断是否已经同意。

参数：

无

返回值：

void : 无

isAgreePrivacy

查询用户是否同意隐私政策


Boolean plus.runtime.isAgreePrivacy();

说明：

HBuilderX2.5.11+版本支持，配置为自定义隐私政策提示框时有效，参考： https://ask.dcloud.net.cn/article/36937
查询当前应用是否用户同意隐私政策。

参数：

无

返回值：

Boolean : 已同意返回true，否则返回false

平台支持：

Android - ALL (支持) :
应用设置为“自定义隐私政策提示框”模式时才有效，没有调用plus.runtime.agreePrivacy()将返回false，调用后将返回ture；其它模式返回true。
iOS - ALL (支持) :
调用plus.runtime.agreePrivacy()将返回false，调用后将返回ture。

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需添加以下权限：
- "<uses-permission android:name="android.permission.INSTALL_PACKAGES"/>"
- "<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES"/>"
参考：https://ask.dcloud.net.cn/article/36982。
iOS - 4.3+ (支持) :
不支持ipa包的安装，需跳转appsotre引导用户手动操作安装。

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

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.');
	}
}

uni-app使用plus注意事项

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 );
		} );
	}
}

uni-app使用plus注意事项

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("微信应用未安装");
	}
}

uni-app使用plus注意事项

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("使用应用默认首页地址");
	}
}

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 类型 )优先使用的程序包名
如果指定包名的程序已经安装，则调用其打开文件，若程序不支持打开文件则触发错误回调。如果指定包名的程序未安装，则弹出系统支持打开此文件的列表，由用户选择程序打开。

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: ( Exception ) 必选
安装失败的错误信息

返回值：

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 );
	} );
}

uni-app使用plus注意事项

OpenErrorCallback

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


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

参数：

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

返回值：

void : 无

LaunchErrorCallback

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


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

参数：

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

返回值：

void : 无