Runtime · Html5+參考

# [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+ (支持): 支持