mui 开发知识 积累总结-----puls.runtime
Runtime
Runtime模块管理运行环境，可用于获取当前运行环境信息、与其它程序进行通讯等。通过plus.runtime可获取运行环境管理对象。
属性：
- version获取客户端的版本号
- innerVersion获取客户端运行时环境的版本号
- arguments获取第三方程序调用时传递给程序的参数
- appid获取当前应用的APPID
方法：
- getProperty获取指定APPID对应的应用信息
- install安装应用
- quit退出客户端程序
- restart重启当前的应用
- setBadgeNumber设置程序快捷方式上显示的提示数字
- openURL调用第三方程序打开指定的URL
- openFile调用第三方程序打开指定的文件
- launchApplication调用第三方程序
对象：
- WidgetOptionJSON对象，应用安装参数
- WidgetInfoJSON对象，应用信息
- OpenFileOptionJSON对象，打开文件参数
- ApplicationInfJSON对象，打开第三方程序参数
回调方法：
- InstallSuccessCallback安装应用成功回调函数
- InstallErrorCallback安装应用失败回调函数
- GetPropertyCallBack获取应用属性成功回调函数
- OpenErrorCallback打开本地文件或URL失败回调函数
- LaunchErrorCallback调用第三方程序失败回调函数
getProperty
获取指定APPID对应的应用信息
void plus.runtime.getProperty( appid, getPropertyCB );
说明：
获取指定APPID对应的应用信息
参数：
- appid (DOMString) 可选 应用的Appid
- getPropertyCB (GetPropertyCallBack) 可选 获得应用信息成功回调函数
返回值：
无
平台支持：
Android : 2.2+
支持iOS : 4.3+
支持WP : 7.5+
暂不支持示例：
-
-
<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 getAppInfo() {
-
plus.runtime.getProperty( plus.runtime.appid,
function ( wgtinfo ) {
-
//appid属性
-
var wgtStr =
"appid:"+wgtinfo.appid;
-
//version属性
-
wgtStr +=
"
version:"+wgtinfo.version;
-
//name属性
-
wgtStr +=
"
name:"+wgtinfo.name;
-
//description属性
-
wgtStr +=
"
description:"+wgtinfo.description;
-
//author属性
-
wgtStr +=
"
author:"+wgtinfo.author;
-
//email属性
-
wgtStr +=
"
email:"+wgtinfo.email;
-
//licence属性
-
wgtStr +=
"
license:"+wgtinfo.license;
-
//licensehref属性
-
wgtStr +=
"
licensehref:"+wgtinfo.licensehref;
-
//features 属性
-
wgtStr +=
"
features:"+wgtinfo.features;
-
console.log( wgtStr );
-
} );
-
}
-
script>
-
head>
-
<body>
-
获取应用信息
-
<br/>
-
<button onclick="getAppInfo()">AppInfo
button>
-
body>
-
html>
install
安装应用
void plus.runtime.install( wgtFilePath, options, installSuccessCB, installErrorCB);
说明：
安装包格式为wgt应用，其扩展名为'.wgt'，使用这个方法之前，需要提前把安装包从网络处或其他位置放置到运行时环境可以访问的位置。
参数：
- wgtFilePath (DOMString) 可选 应用安装文件或基座安装文件（扩展名为'.wgt'）
- options (WidgetOption) 可选 应用安装设置的参数
- installSuccessCB (InstallSuccessCallback) 可选 正确安装后的回调
- installErrorCB (InstallErrorCallback) 可选 安装失败的回调
返回值：
无
平台支持：
Android : 2.2+
支持，支持apk包的安装iOS : 4.3+
支持，不支持ipa包的安装WP : 7.5+
暂不支持quit
退出客户端程序
void plus.runtime.quit();
说明：
退出客户端程序
返回值：
无
平台支持：
Android : 2.2+
支持iOS : 4.3+
iOS系统不支持此功能，只能通过设备的Home键退出应用。WP : 7.5+
暂不支持示例：
-
-
<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() {
-
plus.key.addEventListener(
"backbutton", onKeyBack,
false );
-
}
-
function onKeyBack() {
-
plus.runtime.quit();
-
}
-
script>
-
head>
-
<body>
-
body>
-
html>
restart
重启当前的应用
void plus.runtime.restart();
说明：
重启当前的应用
返回值：
无
平台支持：
Android : 2.2+
支持iOS : 4.3+
支持WP : 7.5+
暂不支持示例：
-
-
<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 restartApp() {
-
plus.runtime.restart();
-
}
-
script>
-
head>
-
<body>
-
重启当前的应用
-
<br/>
-
<button onclick="restartApp()">Restart
button>
-
body>
-
html>
setBadgeNumber
设置程序快捷方式上显示的提示数字
void plus.runtime.setBadgeNumber( number );
说明：
设置程序快捷方式上显示的提示数字
参数：
- number (DOMString) 可选 在快捷方式上显示的数字，参数为0则表示清除提示数字。
返回值：
无
平台支持：
Android : 2.2+
支持iOS : 4.3+
支持WP : 7.5+
暂不支持示例：
-
-
<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 setBadge() {
-
plus.runtime.setBadgeNumber(
8);
-
}
-
// 清除数字
-
function clearBadge() {
-
plus.runtime.setBadgeNumber(
0);
-
}
-
script>
-
head>
-
<body>
-
设置程序快捷方式上显示的提示数字
-
<br/>
-
<button onclick="setBadge()">Set
button>
-
<br/>
-
<button onclick="clearBadge()">Clear
button>
-
body>
-
html>
openURL
调用第三方程序打开指定的URL
void plus.runtime.openURL( url, errorCB, identity );
说明：
调用第三方程序打开指定的URL
参数：
- url (DOMString) 可选 字符串类型，各平台支持的地址类型存在差异，参考平台URL支持表。
- errorCB (OpenErrorCallback) 可选 打开指定URL地址失败时回调，并返回失败信息。
- identity (DOMString) 可选 在iOS平台此参数被忽略，在Android平台为程序包名，如果指定的包名不存在，则打开URL地址失败。
返回值：
无
平台支持：
Android : 2.2+
支持iOS : 4.3+
支持，不支持identity参数WP : 7.5+
支持，不支持identity参数openFile
调用第三方程序打开指定的文件
void plus.runtime.openFile( filepath, options, errorCB );
说明：
调用第三方程序打开指定的文件
参数：
- filepath (DOMString) 可选 字符串类型，文件路径必须是本地路径，否则会导致打开文件失败。
- options (OpenFileOption) 可选 打开文件的参数，参考OpenFileOption对象。
- errorCB (OpenErrorCallback) 可选 打开文件操作失败时回调，返回失败信息。
返回值：
无
平台支持：
Android : 2.2+
支持iOS : 4.3+
支持WP : 7.5+
支持示例：
-
-
<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>
-
调用第三方程序打开文件
-
<br/>
-
<button onclick="testFile()">Open File
button>
-
body>
-
html>
launchApplication
调用第三方程序
void plus.runtime.launchApplication( appInf, errorCB );
说明：
调用第三方程序
参数：
- appInf (ApplicationInf) 可选 要启动第三方程序的描述信息
- errorCB (LaunchErrorCallback) 可选 启动第三方程序失败时回调，并返回失败信息。
返回值：
无
平台支持：
Android : 2.2+
支持iOS : 4.3+
支持WP : 7.5+
暂不支持示例：
-
-
<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 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 );
-
} );
-
}
-
}
-
script>
-
head>
-
<body>
-
调用第三方程序
-
<br/>
-
<button onclick="launchApp()">Launch Application
button>
-
body>
-
html>
version
获取客户端的版本号
plus.runtime.version;
说明：
客户端版本号，字符串类型，在编译环境中设置的版本号。
平台支持：
Android : 2.2+
支持iOS : 4.3+
支持WP : 7.5+
暂不支持innerVersion
获取客户端运行时环境的版本号
plus.runtime.innerVersion;
说明：
运行时环境版本号，格式为：[主版本号].[次版本号].[修订版本号].[编译代号]。
平台支持：
Android : 2.2+
支持iOS : 4.3+
支持WP : 7.5+
暂不支持arguments
获取第三方程序调用时传递给程序的参数
plus.runtime.arguments;
说明：
第三方程序传递过来的参数，字符串格式类型数据。 不是由第三方程序调用启动，则返回空字符串。
平台支持：
Android : 2.2+
支持，把第三方传递过来的参数组合成JSON格式字符串，如“{"name":"XiaoMing","password":"123456"}”iOS : 4.3+
支持，把第三方传递过来的参数，去掉前缀，如“name=XiaoMing&password=”，建议第三方程序传递JSON格式字符串WP : 7.5+
暂不支持appid
获取当前应用的APPID
plus.runtime.appid;
说明：
当前应用的APPID，字符串类型。注意，如果是在HBuilder真机运行获取的是固定值“HBuilder”，需要提交App云端打包后运行才能获取真实的APPID值。
平台支持：
Android : 2.2+
支持iOS : 4.3+
支持WP : 7.5+
支持WidgetOption
JSON对象，应用安装参数
说明：
可通过对象设置安装的应用是否进行appid校验、版本号校验等。
属性：
- appid：DOMString，只读属性，默认值 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平台支持，表示程序的包名，其它平台忽略此属性值。
- action：DOMString，Android平台上与系统的action值一致；iOS平台为要调用程序的URLScheme格式字符串。
- extra：JSON，仅Android平台支持，为JSON格式，用于传递给要调用程序的参数，如extra:{url:"http://www.html5plus.org"}。
InstallSuccessCallback
安装应用成功回调函数
-
void onSuccess(widgetInfo){
-
// Code here
-
}
说明：
安装应用成功回调函数
参数：
- widgetInfo (WidgetInfo) 必选 应用信息，参见：WidgetInfo
平台支持：
Android : 2.2+
支持，如安装文件为APK，则不触发此回调函数iOS : 4.3+
支持WP : 7.5+
暂不支持InstallErrorCallback
安装应用失败回调函数
-
void onError(error){
-
// Handle the error
-
}
说明：
安装应用失败回调函数
参数：
- error (DOMException) 必选 安装失败的错误信息
平台支持：
Android : 2.2+
支持iOS : 4.3+
支持WP : 7.5+
暂不支持GetPropertyCallBack
获取应用属性成功回调函数
-
void onGetPropertyCB(widgetInfo){
-
// Code here
-
}
说明：
获取应用属性成功回调函数
参数：
- widgetInfo (WidgetInfo) 必选 应用信息，参见：WidgetInfo
平台支持：
Android : 2.2+
支持iOS : 4.3+
支持WP : 7.5+
暂不支持OpenErrorCallback
打开本地文件或URL失败回调函数
-
void onError(error){
-
// Handle the error
-
}
说明：
打开本地文件或URL失败回调函数
参数：
- error (DOMException) 必选 打开操作失败的错误信息
平台支持：
Android : 2.2+
支持iOS : 4.3+
支持WP : 7.5+
暂不支持LaunchErrorCallback
调用第三方程序失败回调函数
-
void onError(error){
-
// Handle the error
-
}
说明：
调用第三方程序失败回调函数
参数：
- error (DOMException) 必选 操作失败的错误信息
平台支持：
Android : 2.2+
支持iOS : 4.3+
支持WP : 7.5+
暂不支持