# [runtime]()
Runtime模块管理运行环境，可用于获取当前运行环境信息、与其它程序进行通讯等。通过plus.runtime可获取运行环境管理对象。
### 属性：
- [version](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.version): 获取客户端的版本号
- [innerVersion](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.innerVersion): 获取客户端运行时环境的版本号
- [arguments](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.arguments): 获取第三方程序调用时传递给程序的参数
- [appid](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.appid): 获取当前应用的APPID
### 方法：
- [getProperty](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.getProperty): 获取指定APPID对应的应用信息
- [install](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.install): 安装应用
- [quit](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.quit): 退出客户端程序
- [restart](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.restart): 重启当前的应用
- [setBadgeNumber](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.setBadgeNumber): 设置程序快捷方式上显示的提示数字
- [openURL](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.openURL): 调用第三方程序打开指定的URL
- [openFile](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.openFile): 调用第三方程序打开指定的文件
- [launchApplication](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.launchApplication): 调用第三方程序
### 对象：
- [WidgetOption](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.WidgetOption): JSON对象，应用安装参数
- [WidgetInfo](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.WidgetInfo): JSON对象，应用信息
- [OpenFileOption](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.OpenFileOption): JSON对象，打开文件参数
- [ApplicationInf](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.ApplicationInf): JSON对象，打开第三方程序参数
### 回调方法：
- [InstallSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.InstallSuccessCallback): 安装应用成功回调函数
- [InstallErrorCallback](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.InstallErrorCallback): 安装应用失败回调函数
- [GetPropertyCallBack](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.GetPropertyCallBack): 获取应用属性成功回调函数
- [OpenErrorCallback](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.OpenErrorCallback): 打开本地文件或URL失败回调函数
- [LaunchErrorCallback](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.LaunchErrorCallback): 调用第三方程序失败回调函数
### 权限：
permissions
~~~
"Runtime": {
"description": "访问运行环境信息"
}
~~~
# [version]()
获取客户端的版本号
~~~
plus.runtime.version;
~~~
### 说明：
DOMString 类型 只读属性
客户端版本号，字符串类型，在编译环境中设置的版本号。
### 平台支持：
- Android - 2.2+ (支持): 支持
- iOS - 4.3+ (支持): 支持
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Version Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
// 处理第三方传入的参数
alert( " Application version: " + plus.runtime.version );
}
</script>
</head>
<body>
</body>
</html>
~~~
# [innerVersion]()
获取客户端运行时环境的版本号
~~~
plus.runtime.innerVersion;
~~~
### 说明：
DOMString 类型 只读属性
运行时环境版本号，格式为：[主版本号].[次版本号].[修订版本号].[编译代号]。
### 平台支持：
- Android - 2.2+ (支持): 支持
- iOS - 4.3+ (支持): 支持
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Version Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
// 处理第三方传入的参数
alert( " Runtime version: " + plus.runtime.innerVersion );
}
</script>
</head>
<body>
</body>
</html>
~~~
# [arguments]()
获取第三方程序调用时传递给程序的参数
~~~
plus.runtime.arguments;
~~~
### 说明：
DOMString 类型 只读属性
第三方程序传递过来的参数，字符串格式类型数据。 不是由第三方程序调用启动，则返回空字符串。
### 平台支持：
- Android - 2.2+ (支持): 支持，把第三方传递过来的参数组合成JSON格式字符串，如“{"name":"XiaoMing","password":"123456"}”
- iOS - 4.3+ (支持):支持，把第三方传递过来的参数，去掉前缀，如“name=XiaoMing&password=”，建议第三方程序传递JSON格式字符串
### 示例：
~~~
<!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>
~~~
# [appid]()
获取当前应用的APPID
~~~
plus.runtime.appid;
~~~
### 说明：
DOMString 类型 只读属性
当前应用的APPID，字符串类型。注意，如果是在HBuilder真机运行获取的是固定值“HBuilder”，需要提交App云端打包后运行才能获取真实的APPID值。
### 平台支持：
- Android - 2.2+ (支持): 支持
- iOS - 4.3+ (支持): 支持
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Version 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>
</body>
</html>
~~~
# [getProperty]()
获取指定APPID对应的应用信息
~~~
void plus.runtime.getProperty( appid, getPropertyCB );
~~~
### 参数：
- appid: *( DOMString ) 必选 *应用的Appid
- getPropertyCB: *( [GetPropertyCallBack](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.GetPropertyCallBack) ) 必选 *获得应用信息成功回调函数
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持): 支持
- iOS - 4.3+ (支持): 支持
# [install]()
安装应用
~~~
void plus.runtime.install( wgtFilePath, options, installSuccessCB, installErrorCB);
~~~
### 说明：
安装包格式为wgt应用，其扩展名为'.wgt'，使用这个方法之前，需要提前把安装包从网络处或其他位置放置到运行时环境可以访问的位置。
### 参数：
- wgtFilePath: *( DOMString ) 必选 *要安装的文件路径
应用安装文件或基座安装文件（扩展名为'.wgt'）
- options: *( [WidgetOption](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.WidgetOption) ) 可选 *
应用安装设置的参数
- installSuccessCB: *( [InstallSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.InstallSuccessCallback) ) 可选 *
正确安装后的回调
- installErrorCB: *( [InstallErrorCallback](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.InstallErrorCallback) ) 可选 *
安装失败的回调
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持): 支持，支持apk包的安装
- iOS - 4.3+ (支持): 支持，不支持ipa包的安装
# [quit]()
退出客户端程序
~~~
void plus.runtime.quit();
~~~
### 参数：
无
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持): 支持
- iOS - 4.3+ (支持): iOS系统不支持此功能，只能通过设备的Home键退出应用。
### 示例：
~~~
<!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() {
document.addEventListener( "back", onKeyBack, false );
}
function onKeyBack() {
plus.runtime.quit();
}
</script>
</head>
<body>
</body>
</html>
~~~
# [restart]()
重启当前的应用
~~~
void plus.runtime.restart();
~~~
### 参数：
无
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持): 支持
- iOS - 4.3+ (支持): 支持
# [setBadgeNumber]()
设置程序快捷方式上显示的提示数字
~~~
void plus.runtime.setBadgeNumber( number );
~~~
### 参数：
- number: *( DOMString ) 必选 *
在快捷方式上显示的数字。
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持): 支持
- iOS - 4.3+ (支持): 支持
# [openURL]()
调用第三方程序打开指定的URL
~~~
void plus.runtime.openURL( url, errorCB, identity );
~~~
### 参数：
- url: *( DOMString ) 必选 *要打开的URL地址
字符串类型，各平台支持的地址类型存在差异，参考平台URL支持表。
- errorCB: *( [OpenErrorCallback](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.OpenErrorCallback) ) 可选 *打开URL地址失败的回调
打开指定URL地址失败时回调，并返回失败信息。
- identity: *( DOMString ) 可选 *指定打开URL地址的程序名称
在iOS平台此参数被忽略，在Android平台为程序包名，如果指定的包名不存在，则打开URL地址失败。
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持): 支持
- iOS - 4.3+ (支持): 支持，不支持identity参数
# [openFile]()
调用第三方程序打开指定的文件
~~~
void plus.runtime.openFile( filepath, options, errorCB );
~~~
### 参数：
- filepath: *( DOMString ) 必选 *打开文件的路径
字符串类型，文件路径必须是本地路径，否则会导致打开文件失败。
- options: *( [OpenFileOption](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.OpenFileOption) ) 可选 *打开文件参数
打开文件的参数，参考OpenFileOption对象。
- errorCB: *( [OpenErrorCallback](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.OpenErrorCallback) ) 必选 *打开文件失败的回调
打开文件操作失败时回调，返回失败信息。
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持): 支持
- iOS - 4.3+ (支持): 支持
### 示例：
~~~
<!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>
<input type="button" value="Open File" onclick="testFile();"/>
</body>
</html>
~~~
# [launchApplication]()
调用第三方程序
~~~
void plus.runtime.launchApplication( appInf, errorCB );
~~~
### 参数：
- appInf: *( [ApplicationInf](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.ApplicationInf) ) 必选 *要启动第三方程序的描述信息
- errorCB: *( [LaunchErrorCallback](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.LaunchErrorCallback) ) 必选 *启动第三方程序操作失败的回调函数
启动第三方程序失败时回调，并返回失败信息。
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持): 支持
- iOS - 4.3+ (支持): 支持
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Runtiem Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
}
// 调用第三方程序
function launchTest() {
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>
<input type="button" value="Launch Application" onclick="launchTest();"/>
</body>
</html>
~~~
# [WidgetOption]()
JSON对象，应用安装参数
### 说明：
可通过对象设置安装的应用是否进行appid校验、版本号校验等。
### 属性：
- appid: *(DOMString 类型)*应用的appid
默认值 null。当前正在安装的应用的appid，填写该值后应用安装时将进行校验，如安装包内的appid和指定的不同则终止当前应用的安装
- force: *(Boolean 类型)*是否强制安装
默认值 false。当取值为true，应用安装为强制安装，不再进行版本号的校验，如果为false则进行版本号校验，如果将要安装应用的版本号不高于现有应用的版本号则终止安装，并返回安装失败
# [WidgetInfo]()
JSON对象，应用信息
### 属性：
- appid: *(DomString 类型)*应用的APPID
- version: *(DomString 类型)*应用的版本号
- name: *(DomString 类型)*应用的名称
- description: *(DomString 类型)*应用描述信息
- author: *(DomString 类型)*应用描述信息
- email: *(DomString 类型)*开发者邮箱地址
- license: *(DomString 类型)*应用授权描述信息
- licensehref: *(DomString 类型)*应用授权说明链接地址
- features: *(DomString[] 类型)*应用许可特性列表
# [OpenFileOption]()
JSON对象，打开文件参数
### 属性：
- popover: *(json 类型)*弹出系统选择程序界面指示区域
JSON对象，格式如{top:10;left:10;width:200;height:200;}，所有值为像素值，左上坐标相对于容器webview的位置。仅在iPad设备平台有效。
# [ApplicationInf]()
JSON对象，打开第三方程序参数
### 属性：
- pname: *(DOMString 类型)*第三方程序包名
仅Android平台支持，表示程序的包名，其它平台忽略此属性值。
### 平台支持
- Android - 2.2+ (支持): 第三方程序的包名，如“io.dclould.HelloH5”。
- iOS - 4.3+ (支持): 忽略此属性值。
- action: *(DOMString 类型)*程序的操作行为
Android平台上与系统的action值一致；iOS平台为要调用程序的URLScheme格式字符串。
### 平台支持
- Android - 2.2+ (支持): 第三方程序的操作行为，与系统的action值完全一致。
- iOS - 4.3+ (支持): 要调用程序的URLScheme格式字符串。
- extra: *(JSON 类型)*调用程序的参数
仅Android平台支持，为JSON格式，用于传递给要调用程序的参数，如extra:{url:"http://www.html5plus.org"}。
### 平台支持
- Android - 2.2+ (支持): 传递给第三方程序的参数，必须是JSON格式数据，如“{'name':'value','name2':'value2'}”。
- iOS - 4.3+ (支持): 忽略此属性值。
# [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 : 无
### 平台支持：
- Android - 2.2+ (支持): 支持
- iOS - 4.3+ (支持): 支持
# [GetPropertyCallBack]()
获取应用属性成功回调函数
~~~
void onGetPropertyCB(widgetInfo){
// Code here
}
~~~
### 参数：
- widgetInfo: *( [WidgetInfo](http://www.dcloud.io/docs/api/zh_cn/runtime.shtml#plus.runtime.WidgetInfo) ) 必选 *
应用信息，参见：WidgetInfo
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持): 支持
- iOS - 4.3+ (支持): 支持
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8"/>
<script type="text/javascript">
function onload() {
var xmlHttp = new plus.net.XMLHttpRequest();
if (xmlHttp!=null) {
xmlhttp.onreadystatechange=state_Change;
xmlHttp.open("GET", "note.xml");
xmlHttp.send(null);
}
else {
alert("Your runtime does not support XMLHTTP.");
}
}
function state_Change() {
if (xmlhttp.readyState==4) {
// 4 = "loaded"
if (xmlhttp.status==200) {
// 200 = OK
// ...our code here...
alert(xmlhttp.responseText);
}
else {
alert("Problem retrieving XML data");
}
}
}
</script>
</head>
<body onload="onload();">
</body>
</html>
~~~
# [OpenErrorCallback]()
打开本地文件或URL失败回调函数
~~~
void onError(error){
// Handle the error
}
~~~
### 参数：
- error: *( DOMException ) 必选 *
打开操作失败的错误信息
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持): 支持
- iOS - 4.3+ (支持): 支持
# [LaunchErrorCallback]()
调用第三方程序失败回调函数
~~~
void onError(error){
// Handle the error
}
~~~
### 参数：
- error: *( DOMException ) 必选 *
操作失败的错误信息
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持): 支持
- iOS - 4.3+ (支持): 支持
- API参考
- Accelerometer
- Audio
- Camera
- Contacts
- Device
- Downloader
- Events
- Gallery
- Geolocation
- IO
- Key
- Messaging
- NativeUI
- Navigator
- Orientation
- Proximity
- SplashScreen
- Storage
- UI
- Uploader
- InterfaceOrientation
- Runtime
- WebView
- XMLHttpRequest
- Zip
- Plugins
- Barcode
- Maps
- Payment
- Push
- Share
- Speech
- Statistic
- Native.js
- Android
- iOS