runtime
Runtime模块管理运行环境,可用于获取当前运行环境信息、与其它程序进行通讯等。通过plus.runtime可获取运行环境管理对象。
属性:
- version: 获取客户端的版本号
- innerVersion: 获取客户端运行时环境的版本号
- arguments: 获取第三方程序调用时传递给程序的参数
- appid: 获取当前应用的APPID
方法:
- getProperty: 获取指定APPID对应的应用信息
- install: 安装应用
- quit: 退出客户端程序
- restart: 重启当前的应用
- setBadgeNumber: 设置程序快捷方式上显示的提示数字
- openURL: 调用第三方程序打开指定的URL
- openFile: 调用第三方程序打开指定的文件
- launchApplication: 调用第三方程序
对象:
- WidgetOption: JSON对象,应用安装参数
- WidgetInfo: JSON对象,应用信息
- OpenFileOption: JSON对象,打开文件参数
- ApplicationInf: JSON对象,打开第三方程序参数
回调方法:
- InstallSuccessCallback: 安装应用成功回调函数
- InstallErrorCallback: 安装应用失败回调函数
- GetPropertyCallBack: 获取应用属性成功回调函数
- OpenErrorCallback: 打开本地文件或URL失败回调函数
- LaunchErrorCallback: 调用第三方程序失败回调函数
权限:
permissions
"Runtime": { "description": "访问运行环境信息" }
version
获取客户端的版本号
plus.runtime.version;
说明:
DOMString 类型 只读属性
客户端版本号,字符串类型,在编译环境中设置的版本号。
平台支持:
- Android2.2+ (支持): 支持
- iOS4.3+ (支持): 支持
- WP7.5+ (支持): 暂不支持
示例:
<!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 类型 只读属性
运行时环境版本号,格式为:[主版本号].[次版本号].[修订版本号].[编译代号]。 注:编译代号为SVN上代码版本号
平台支持:
- Android2.2+ (支持): 支持
- iOS4.3+ (支持): 支持
- WP7.5+ (支持): 暂不支持
示例:
<!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 类型 只读属性
第三方程序传递过来的参数,字符串格式类型数据。 不是由第三方程序调用启动,则返回空字符串。
平台支持:
- Android2.2+ (支持): 支持,把第三方传递过来的参数组合成JSON格式字符串,如“{"name":"XiaoMing","password":"123456"}”
- iOS4.3+ (支持): 支持,把第三方传递过来的参数,去掉前缀,如“name=XiaoMing&password=”,建议第三方程序传递JSON格式字符串
- WP7.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() { // 处理第三方传入的参数 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,字符串类型。
平台支持:
- Android2.2+ (支持): 支持
- iOS4.3+ (支持): 支持
- WP7.5+ (支持): 支持
示例:
<!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
)
必选 获得应用信息成功回调函数
返回值:
void : 无平台支持:
- Android2.2+ (支持): 支持
- iOS4.3+ (支持): 支持
- WP7.5+ (支持): 暂不支持
install
安装应用
void plus.runtime.install( wgtFilePath, options, installSuccessCB, installErrorCB);
说明:
安装包格式为wgt应用,其扩展名为'.wgt',使用这个方法之前,需要提前把安装包从网络处或其他位置放置到运行时环境可以访问的位置。
参数:
- wgtFilePath:
(
DOMString
)
必选 要安装的文件路径
应用安装文件或基座安装文件(扩展名为'.wgt') - options:
(
WidgetOption
)
可选
应用安装设置的参数 - installSuccessCB:
(
InstallSuccessCallback
)
可选
正确安装后的回调 - installErrorCB:
(
InstallErrorCallback
)
可选
安装失败的回调
返回值:
void : 无平台支持:
- Android2.2+ (支持): 支持,还支持apk方式的安装
- iOS4.3+ (支持): 支持
- WP7.5+ (支持): 暂不支持
quit
退出客户端程序
void plus.runtime.quit();
参数:
无
返回值:
void : 无平台支持:
- Android2.2+ (支持): 支持
- iOS4.3+ (支持): 支持
- WP7.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() { document.addEventListener( "back", onKeyBack, false ); } function onKeyBack() { plus.runtime.quit(); } </script> </head> <body> </body> </html>
restart
重启当前的应用
void plus.runtime.restart();
参数:
无
返回值:
void : 无平台支持:
- Android2.2+ (支持): 支持
- iOS4.3+ (支持): 支持
- WP7.5+ (支持): 暂不支持
setBadgeNumber
设置程序快捷方式上显示的提示数字
void plus.runtime.setBadgeNumber( number );
参数:
- number:
(
DOMString
)
必选
在快捷方式上显示的数字。
返回值:
void : 无平台支持:
- Android2.2+ (支持): 支持
- iOS4.3+ (支持): 支持
- WP7.5+ (支持): 暂不支持
openURL
调用第三方程序打开指定的URL
void plus.runtime.openURL( url, errorCB, identity );
参数:
- url:
(
DOMString
)
必选 要打开的URL地址
字符串类型,各平台支持的地址类型存在差异,参考平台URL支持表。 - errorCB:
(
OpenErrorCallback
)
可选 打开URL地址失败的回调
打开指定URL地址失败时回调,并返回失败信息。 - identity:
(
DOMString
)
可选 指定打开URL地址的程序名称
在iOS平台此参数被忽略,在Android平台为程序包名,如果指定的包名不存在,则打开URL地址失败。
返回值:
void : 无平台支持:
- Android2.2+ (支持): 支持
- iOS4.3+ (支持): 支持,不支持identity参数
- WP7.5+ (支持): 支持,不支持identity参数
openFile
调用第三方程序打开指定的文件
void plus.runtime.openFile( filepath, options, errorCB );
参数:
- filepath:
(
DOMString
)
必选 打开文件的路径
字符串类型,文件路径必须是本地路径,否则会导致打开文件失败。 - options:
(
OpenFileOption
)
可选 打开文件参数
打开文件的参数,参考OpenFileOption对象。 - errorCB:
(
OpenErrorCallback
)
必选 打开文件失败的回调
打开文件操作失败时回调,返回失败信息。
返回值:
void : 无平台支持:
- Android2.2+ (支持): 支持
- iOS4.3+ (支持): 支持
- WP7.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() { } // 打开文件操作 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
)
必选 要启动第三方程序的描述信息
- errorCB:
(
LaunchErrorCallback
)
必选 启动第三方程序操作失败的回调函数
启动第三方程序失败时回调,并返回失败信息。
返回值:
void : 无平台支持:
- Android2.2+ (支持): 支持
- iOS4.3+ (支持): 支持
- WP7.5+ (支持): 暂不支持
示例:
<!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: (josn
类型
)弹出系统选择程序界面指示区域
JSON对象,格式如{top:10;left:10;width:200;height:200;},所有值为像素值,左上坐标相对于容器webview的位置。仅在iPad设备平台有效。
ApplicationInf
JSON对象,打开第三方程序参数
属性:
- pname: (DOMString
类型
)第三方程序包名
仅Android平台支持,表示程序的包名,其它平台忽略此属性值。
平台支持
- Android2.2+ (支持): 第三方程序的包名,如“io.dclould.HelloH5”。
- iOS4.3+ (支持): 忽略此属性值。
- WP7.5+ (支持): 忽略此属性值。
- action: (DOMString
类型
)程序的操作行为
Android平台上与系统的action值一致;iOS平台为要调用程序的URLScheme格式字符串。
平台支持
- Android2.2+ (支持): 第三方程序的操作行为,与系统的action值完全一致。
- iOS4.3+ (支持): 要调用程序的URLScheme格式字符串。
- WP7.5+ (支持): 暂不支持属性值。
- extra: (JSON
类型
)调用程序的参数
仅Android平台支持,为JSON格式,用于传递给要调用程序的参数,如extra:{url:"http://www.html5plus.org"}。
平台支持
- Android2.2+ (支持): 传递给第三方程序的参数,必须是JSON格式数据,如“{'name':'value','name2':'value2'}”。
- iOS4.3+ (支持): 忽略此属性值。
- WP7.5+ (支持): 忽略此属性值。
InstallSuccessCallback
安装应用成功回调函数
void onSuccess(widgetInfo){ // Code here }
参数:
- widgetInfo:
(
WidgetInfo
)
必选
应用信息,参见:WidgetInfo
返回值:
void : 无平台支持:
- Android2.2+ (支持): 支持,如安装文件为APK,则不触发此回调函数
- iOS4.3+ (支持): 支持
- WP7.5+ (支持): 暂不支持
InstallErrorCallback
安装应用失败回调函数
void onError(error){ // Handle the error }
参数:
- error:
(
DOMException
)
必选
安装失败的错误信息
返回值:
void : 无平台支持:
- Android2.2+ (支持): 支持
- iOS4.3+ (支持): 支持
- WP7.5+ (支持): 暂不支持
GetPropertyCallBack
获取应用属性成功回调函数
void onGetPropertyCB(widgetInfo){ // Code here }
参数:
- widgetInfo:
(
WidgetInfo
)
必选
应用信息,参见:WidgetInfo
返回值:
void : 无平台支持:
- Android2.2+ (支持): 支持
- iOS4.3+ (支持): 支持
- WP7.5+ (支持): 暂不支持
示例:
<!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 : 无平台支持:
- Android2.2+ (支持): 支持
- iOS4.3+ (支持): 支持
- WP7.5+ (支持): 暂不支持
LaunchErrorCallback
调用第三方程序失败回调函数
void onError(error){ // Handle the error }
参数:
- error:
(
DOMException
)
必选
操作失败的错误信息
返回值:
void : 无平台支持:
- Android2.2+ (支持): 支持
- iOS4.3+ (支持): 支持
- WP7.5+ (支持): 暂不支持