## API對象 [TOC] ## 概述 api 對象是您入門 APICloud 必須了解和熟練掌握的一個基礎對象。api 對象提供了構建應用程序所需要的一些基本的方法（method），如窗口操作、相冊和網絡數據訪問等；以及一些常見的屬性（Attrbute），如屏幕寬度（screenWidth），系統類型（systemType）等；還有一些常用事件，如電量低（batterylow）事件、應用進入后臺（pause）事件。api 對象不需要 require 引用，可以直接在 js 中使用。 ## appId 應用的 ID，可以在網站控制臺概覽里面查看，字符串類型 ### 示例代碼 var appId = api.appId; //比如: A6980386445546 ### 可用性 iOS系統，Android系統 可提供的1.1.0及更高版本 ## appName 應用在桌面顯示名稱，字符串類型 ### 示例代碼 var appName = api.appName; //比如: AppLoader ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## appVersion 應用版本號，字符串類型 ### 示例代碼 var appVersion = api.appVersion; // 比如: 1.0.0 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## systemType 系統類型，如iOS、Android，取值范圍詳見[系統類型](!Constant#b18)常量，字符串類型 ### 示例代碼 var systemType = api.systemType; // 比如: iOS ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## systemVersion 手機平臺的系統版本，字符串類型 ### 示例代碼 var systemVersion = api.systemVersion; // 比如: 8.0 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## version 引擎版本信息，字符串類型 ### 示例代碼 var version = api.version; //比如: 1.0.0 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## deviceId 設備唯一標識，字符串類型 ### 示例代碼 var deviceId = api.deviceId; //比如: FC408F8B-9598-48B6-A740-B9037ADCXXXE ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## deviceToken iOS中用于推送的Token，若未從系統獲取到則返回空字符串，字符串類型 ### 示例代碼 var deviceToken = api.deviceToken; //比如: a22241adab6c68b3687a9f0f086c540341f4b3f010546d4af4834ada32281615 ### 可用性 iOS系統 可提供的1.1.0及更高版本 ## deviceModel 設備型號，字符串類型 ### 示例代碼 var deviceModel = api.deviceModel; // 比如: iPhone 5 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## deviceName 設備名稱，字符串類型 ### 示例代碼 var deviceName = api.deviceName; // 比如:“柚子”的 iPhone ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## operator 運營商名稱，若未獲取到則返回none，字符串類型 ### 示例代碼 var operator = api.operator; // 比如:中國移動 ### 可用性 iOS系統，Android系統 可提供的1.1.0及更高版本 ## connectionType 當前網絡連接類型，如 2g、3g、4g、wifi 等，取值范圍詳見[網絡類型](!Constant#b16)常量，字符串類型 ### 示例代碼 var connectionType = api.connectionType; //比如: wifi ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## fullScreen 應用是否全屏，布爾類型，只支持iOS ### 示例代碼 var fullScreen = api.fullScreen; // 比如: true ### 可用性 iOS系統 可提供的1.0.0及更高版本 ## screenWidth 屏幕分辨率寬，數字類型 ### 示例代碼 var screenWidth = api.screenWidth; // 比如: 640 ### 可用性 iOS系統，Android系統 可提供的1.1.0及更高版本 ## screenHeight 屏幕分辨率高，數字類型 ### 示例代碼 var screenHeight = api.screenHeight; // 比如: 960 ### 可用性 iOS系統，Android系統 可提供的1.1.0及更高版本 ## winName 當前 window 名稱，字符串類型 該屬性值為 openWin() 時傳遞的 name 參數值，注意首頁的名稱為 root ### 示例代碼 var winName = api.winName; //比如: root ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## winWidth 當前 window 寬度，數字類型 此屬性值不同于屏幕的分辨率，比如 iPhone 5 的分辨率為 640*1136，但是其 winWidth 為 320，因此前端需根據 winWidth 和 winHeight 來進行布局 ### 示例代碼 var winWidth = api.winWidth; // 比如: 320 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## winHeight 當前 window 高度，數字類型 此屬性值不同于屏幕的分辨率，比如 iPhone 5 的分辨率為 640*1136，但是其 winHeight 為 568（若不使用iOS7風格則為 548），因此前端需根據 winWidth 和 winHeight 來進行布局 ### 示例代碼 var winHeight = api.winHeight; // 比如: 568 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## frameName frame 名稱，字符串類型 若當前環境為 window 中，則該屬性值為空字符串 ### 示例代碼 var frameName = api.frameName; //比如: trans-con ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## frameWidth frame 寬度，數字類型 若當前環境為 window 中，則值和 winWidth 相同 ### 示例代碼 var frameWidth = api.frameWidth; // 例如: 320 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## frameHeight frame 高度，數字類型 若當前環境為 window 中，則值和 winHeight 相同 ### 示例代碼 var frameHeight = api.frameHeight; // 比如: 504 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## pageParam 頁面參數，JSON 對象類型 用于獲取頁面間傳遞的參數值，為 openWin()、openFrame() 等方法中的 pageParam 參數對應值 ### 示例代碼 var pageParam = api.pageParam; //比如: {"name" : "tans-con"} ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## wgtParam widget 參數，JSON 對象類型 用于獲取 widget 間傳遞的參數值，為 openWidget() 方法中的 wgtParam 參數對應值 ### 示例代碼 var wgtParam = api.wgtParam; //比如: {"name": "API Demo"} ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## appParam 當應用被第三方應用打開時，傳遞過來的參數，字符串類型 ### 示例代碼 var appParam = api.appParam; // 比如: appLoader ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## wgtRootDir widget: //協議對應的真實目錄，即 widget 網頁包的根目錄，字符串類型 注意該目錄為只讀，不要往該目錄下面寫文件 ### 示例代碼 ```js var wgtRootDir = api.wgtRootDir; /* 比如: /private/var/mobile/Containers/Bundle/Application/56218B5B-1B59-48CD-8080-DAC54DB46446/UZApp.app/widget */ ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## fsDir fs: //協議對應地真實目錄，字符串類型 ### 示例代碼 ```js var fsDir = api.fsDir; /* 例如: /var/mobile/Containers/Data/Application/4E376FDE-D595-4E08-B0A4-A06561B31000/Documents/uzfs/A123456789 */ ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## cacheDir cache://協議對應的真實目錄，字符串類型 iOS 平臺下載的文件一般存放于該目錄下，否則提交 AppStore 審核時可能會不通過，且此目錄下的內容在手機備份時不會被備份 ### 示例代碼 ```js var cacheDir = api.cacheDir; /* 例如: /var/mobile/Containers/Data/Application/4E376FDE-D595-4E08-B0A4-A06561B31000/Library/Caches/APICloud/Cache/XXXXXX */ ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## toast位置 toast 位置，字符串類型 用于 toast() 方法中 location 字段 ### 取值范圍 ```js top //頂部 middle //中間 bottom //底部 ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 傳感器類型 傳感器類型，字符串類型 用于 startSensor() 方法中 type 字段 ### 取值范圍 ```js accelerometer //加速計 gyroscope //陀螺儀 magnetic_field //地磁傳感器 proximity //近接傳感器 ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 錯誤碼 錯誤碼，數字類型 ### 取值范圍 ```js 0 //錯誤 1 //沒有指定模塊 2 //沒有指定方法 3 //參數不匹配 4 //沒有權限 ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 電話類型 電話類型，字符串類型 用于 call() 方法中 type 字段 ### 取值范圍 ```js tel //直接撥打電話 tel_prompt //iOS撥打電話之前會彈出提示框 facetime //facetime通話，Android不支持 ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 定位精度 定位精度，字符串類型 根據需要來選擇適當的精度來進行定位，用于 startLocation() 方法中 accuracy 字段 ### 取值范圍 ```js 10m //精度在10米范圍內 100m //精度在100米范圍內 1km //精度在1千米范圍內 3km //精度在3千米范圍內 ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 動畫類型 打開 window 或打開 widget 時的動畫類型，Android 部分動畫不支持，字符串類型 ### 取值范圍 ```js none //無動畫效果 push //新視圖將舊視圖推開 movein //新視圖移到舊視圖上面 fade //交叉淡化過渡（不支持過渡方向） flip //翻轉效果 reveal //將舊視圖移開,顯示下面的新視圖 ripple //滴水效果（不支持過渡方向） curl //向上翻一頁 un_curl //向下翻一頁 suck //收縮效果（不支持過渡方向） cube //立方體翻滾效果 ``` ### 可用性 iOS系統，Android系統（flip，ripple，curl，un_curl，suck，cube 類型不支持） 可提供的1.0.0及更高版本 ## 動畫曲線類型 動畫曲線類型，指定動畫開始和結束時的快慢，字符串類型 用于 animation() 方法中 curve 字段 ### 取值范圍 ```js ease_in_out //開始和結束時慢 ease_in //開始時慢 ease_out //結束時慢 linear //整個動畫過程速率一樣 ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 動畫子類型 動畫子類型，字符串類型 部分動畫如 fade 可能沒有過渡方向 ### 取值范圍 ```js from_right //從右邊開始動畫 from_left //從左邊開始動畫 from_top //從頂部開始動畫 from_bottom //從底部開始動畫 ``` ### 可用性 iOS系統，Android系統（僅限于from_right，from_left） 可提供的1.0.0及更高版本 ## 進度提示框動畫類型 進度提示框動畫類型，字符串類型 用于 showProgress() 方法中 animationType 字段 ### 取值范圍 ```js fade //漸隱漸現 zoom //縮放 ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 進度提示框風格 進度提示框風格，字符串類型 用于 showProgress() 方法中 style 字段 ### 取值范圍 ```js default //默認 ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 媒體類型 媒體類型，字符串類型 用于 getPicture() 方法中 mediaValue 字段 ### 取值范圍 ```js pic //圖片 video //視頻 all //圖片和視頻，Android不支持 ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 拾取器類型 拾取器類型，字符串類型 用于 openPicker() 方法中 type 字段 ### 取值范圍 ```js date //日期 time //時間 date_time //日期和時間，Android不支持 ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 圖片編碼類型 圖片編碼類型，字符串類型 用于 getPicture() 方法中 encodingType 字段 ### 取值范圍 ```js jpg //指定圖片格式為jpg png //指定圖片格式為png ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 圖片數據格式 圖片數據格式，字符串類型 用于 getPicture() 方法中 destinationType 字段 ### 取值范圍 ```js base64 //指定返回數據為base64編碼后內容 url //指定返回數據為選取的圖片地址 ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 圖片源類型 圖片源類型，字符串類型 用于 getPicture() 方法中 sourceType 字段 ### 取值范圍 ```js library //圖片庫 camera //相機 album //相冊 ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 網絡類型 網絡類型，字符串類型 用于 connectionType 屬性 ### 取值范圍 ```js unknown //未知 ethernet //以太網 wifi //wifi 2g //2G網絡 3g //3G網絡 4g //4G網絡 none //無網絡 ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 文件操作錯誤碼 文件操作錯誤碼，數字類型 指定 readFile()、writeFile() 方法返回錯誤時的錯誤類型 ### 取值范圍 ```js 0 //沒有錯誤 1 //找不到文件錯誤 2 //不可讀取錯誤 3 //編碼格式錯誤 4 //無效操作錯誤 5 //無效修改錯誤 6 //磁盤溢出錯誤 7 //文件已存在錯誤 ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 系統類型 系統類型，字符串類型 用于 systemType 屬性 ### 取值范圍 ```js iOS //iOS系統 Android //Android系統 win //Windows系統 wp //Windows Phone系統 ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 下載狀態 下載狀態，數字類型 用于 download() 方法返回值中的 state 字段 ### 取值范圍 ```js 0 //下載中 1 //下載完成 2 //下載失敗 ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 異步請求錯誤類型 異步請求錯誤類型，數字類型 用于 ajax() 方法返回錯誤時的 code 字段 ### 取值范圍 ```js 0 //連接錯誤 1 //超時 2 //授權錯誤 3 //數據類型錯誤 ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 異步請求返回數據類型 異步請求返回數據類型，字符串類型 用于 ajax() 方法中 dataType 字段 ### 取值范圍 ```js json //返回數據為 JSON 對象 text //返回數據為字符串類型 ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 異步請求方法類型 異步請求方法類型，字符串類型 用于 ajax() 方法中 method 字段 ### 取值范圍 ```js get post put delete head ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 狀態欄樣式 狀態欄樣式，字符串類型 用于 setStatusBarStyle() 方法中 style 字段 ### 取值范圍 ```js dark //狀態欄字體為黑色，適用于淺色背景 light //狀態欄字體為白色，適用于深色背景 ``` ### 可用性 iOS系統 可提供的1.0.0及更高版本 ## 屏幕旋轉方向 指定屏幕旋轉到特定方向，或根據重力感應自動旋轉，字符串類型 用于 setScreenOrientation() 方法中 orientation 字段 ### 取值范圍 ```js portrait_up //豎屏時，屏幕在home鍵的上面 portrait_down //豎屏時，屏幕在home鍵的下面，部分手機不支持 landscape_left //橫屏時，屏幕在home鍵的左邊 landscape_right //橫屏時，屏幕在home鍵的右邊 auto //屏幕根據重力感應在橫豎屏間自動切換 auto_portrait //屏幕根據重力感應在豎屏間自動切換 auto_landscape //屏幕根據重力感應在橫屏間自動切換 ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 上傳狀態 上傳狀態，數字類型 用于 ajax() 方法上傳文件時返回值中的 status 字段 ### 取值范圍 ```js 0 //上傳中 1 //上傳完成 2 //上傳失敗 ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 鍵盤彈出頁面調整方式 指定鍵盤彈出時，頁面如何調整其內容，字符串類型 ### 取值范圍 ```js resize //若鍵盤蓋住輸入框，頁面會自動上移 pan //若鍵盤蓋住輸入框，頁面不會自動上移 auto //默認值，由系統決定如何處理，iOS平臺該字段等同于resize ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 緩存策略 緩存策略，字符串類型 用于 imageCache() 方法中的 policy 字段 ### 取值范圍 ```js default //默認為 cache_else_network cache_else_network //若服務器上沒有更新，則使用緩存 no_cache //不使用緩存，始終從服務器獲取 cache_only //當緩存存在時，只從緩存中讀取 ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## batterylow 設備電池電量低事件，字符串類型 ### callback(ret, err) ret： - 描述：返回電池電量和充電狀態，不能為空 內部字段： ```js { level:100, //電池電量（0-100） isPlugged:true //是否連接電源 } ``` ### 示例代碼 ```js api.addEventListener({ name:'batterylow' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## batterystatus 設備電池狀態改變事件，如電量變化或正在充電，字符串類型 ### callback(ret, err) ret: - 描述：返回電池電量和充電狀態，不能為空 內部字段： ```js { level:100, //電池電量（0-100） isPlugged:true //是否連接電源 } ``` ### 示例代碼 ```js api.addEventListener({ name:'batterystatus' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## keyback 設備 back 鍵被點擊事件，僅 Android 平臺有效，字符串類型 該事件必須在 Window 中注冊才有效，Frame 中注冊無效，并且只在當前屏幕上的 window 才能收到回調。 ### callback(ret, err) ret: - 描述：被點擊的鍵值 內部字段： ```js { keyCode:0 //被點擊的按鍵 longPress:false //是否是長按 } ``` ### 示例代碼 ```js api.addEventListener({ name:'keyback' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 可用性 Android系統 可提供的1.0.0及更高版本 ## keymenu 設備 menu 鍵被點擊事件，僅 Android 平臺有效 該事件必須在 Window 中注冊才有效，Frame 中注冊無效，并且只在當前屏幕上的 window 才能收到回調。 ### callback(ret, err) ret: - 描述：被點擊的按鍵 內部字段： ```js { keyCode:0 //被點擊的按鍵 longPress:false //是否是長按 } ``` ### 示例代碼 ```js api.addEventListener({ name:'keymenu' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 可用性 Android系統 可提供的1.0.0及更高版本 ## volumeup 設備音量加鍵被點擊事件，僅 Android 平臺有效 該事件必須在 Window 中注冊才有效，Frame 中注冊無效，并且只在當前屏幕上的 window 才能收到回調。 ### callback(ret, err) ret: - 描述：被點擊的按鍵 內部字段： ```js { keyCode:0 //被點擊的按鍵 longPress:false //是否是長按 } ``` ### 示例代碼 ```js api.addEventListener({ name:'volumeup' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 可用性 Android系統 可提供的1.2.0及更高版本 ## volumedown 設備音量減鍵被點擊事件，僅 Android 平臺有效 該事件必須在 Window 中注冊才有效，Frame 中注冊無效，并且只在當前屏幕上的 window 才能收到回調。 ### callback(ret, err) ret: - 描述：被點擊的按鍵 內部字段： ```js { keyCode:0 //被點擊的按鍵 longPress:false //是否是長按 } ``` ### 示例代碼 ```js api.addEventListener({ name:'volumedown' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 可用性 Android系統 可提供的1.2.0及更高版本 ## offline 監聽設備斷開網絡的事件，字符串類型 ### callback(ret, err) 不能為空 ### 示例代碼 ```js api.addEventListener({ name:'offline' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## online 監聽設備連接到網絡的事件，字符串類型 ### callback(ret, err) ret: - 描述：監聽到網絡連接時的返回數據 內部字段： ```js { connectionType:'' //當前網絡連接類型，如2g、3g、4g、wifi等 } ``` ### 示例代碼 ```js api.addEventListener({ name:'online' }, function(ret, err){ if( ret ){ var connectionType = ret.connectionType; alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## pause 應用進入后臺事件，字符串類型 ### callback(ret, err) 不能為空 ### 示例代碼 ```js api.addEventListener({ name:'pause' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## resume 應用從后臺回到前臺事件，字符串類型 ### callback(ret, err) 不能為空 ### 示例代碼 ```js api.addEventListener({ name:'resume' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## scrolltobottom Window 或者 Frame 頁面滑動到底部事件，字符串類型 可用于實現滾動到底部，加載更多功能 ### callback(ret, err) 不能為空 ### 示例代碼 ```js api.addEventListener({ name:'scrolltobottom', extra:{ threshold:0 //設置距離底部多少距離時觸發，默認值為0，數字類型 } }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## shake 設備搖動事件，字符串類型。設置該監聽后，當前 APP 將立即開啟搖動檢測功能。 可用于實現搖一搖功能 ### callback(ret, err) 不能為空 ### 示例代碼 ```js api.addEventListener({ name:'shake' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## takescreenshot 應用在前臺運行期間，用戶屏幕截圖事件（比如同時按下了 home 鍵和電源鍵），只支持 iOS。 ### callback(ret, err) 不能為空 ### 示例代碼 ```js api.addEventListener({ name:'takescreenshot' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 可用性 iOS系統 可提供的1.2.0及更高版本 ## swipedown Window 或者 Frame 的頁面全局向下輕掃事件，字符串類型 ### callback(ret, err) 不能為空 ### 示例代碼 ```js api.addEventListener({ name:'swipedown' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## swipeleft Window 或者 Frame 的頁面全局向左輕掃事件，字符串類型 ### callback(ret, err) 不能為空 ### 示例代碼 ```js api.addEventListener({ name:'swipeleft' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## swiperight Window 或者 Frame 的頁面全局向右輕掃事件，字符串類型 ### callback(ret, err) 不能為空 ### 示例代碼 ```js api.addEventListener({ name:'swiperight' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## swipeup Window 或者 Frame 的頁面全局向上輕掃事件，字符串類型 ### callback(ret, err) 不能為空 ### 示例代碼 ```js api.addEventListener({ name:'swipeup' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## tap Window 或者 Frame 的頁面全局單擊事件，字符串類型。監聽該事件后，點擊 window 或者 frame 的任意位置，都將收到 tap 回調。 ### callback(ret, err) 不能為空 ### 示例代碼 ```js api.addEventListener({ name:'tap' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## longpress Window 或者 Frame 的頁面全局長按事件，字符串類型。 ### callback(ret, err) 不能為空 ### 示例代碼 ```js api.addEventListener({ name:'longpress' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 可用性 iOS系統，Android系統 可提供的1.2.0及更高版本 ## viewappear Window 顯示到屏幕的事件，字符串類型。收到 viewappear 事件回調，即標識當前 Window 已經動畫結束，并且完全顯示到屏幕上。 該事件的作用對象為 Window，Frame 的顯示不會收到事件 ### callback(ret, err) 不能為空 ### 示例代碼 ```js api.addEventListener({ name:'viewappear' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## viewdisappear Window 離開屏幕的事件，字符串類型。收到 viewdisappear 事件回調，即標識當前 Window 已經動畫結束，并且完全從屏幕上移除。 該事件的作用對象為 Window，Frame 的隱藏不會收到事件 若是 Window 被關閉，此事件不會再回調 ### callback(ret, err) 不能為空 ### 示例代碼 ```js api.addEventListener({ name:'viewdisappear' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## noticeclicked 狀態欄通知被用戶點擊后的回調，字符串類型 ### callback(ret, err) ret: - 描述：通知被點擊后的回調 內部字段： ```js { type:0, //內容來源類型。取值范圍：0-APICloud 收到的推送內容，1-開發者自定義的 value:'' //內容，收到的推送內容或者由開發者發送通知時自行傳入的，見notification接口中extra } ``` ### 示例代碼 ```js api.addEventListener({ name:'noticeclicked' },function(ret,err){ var value = ret.value; if(ret.type == 0){ //APICloud推送內容 } else if(ret.type == 1){ //開發者自定義消息 } }); ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## appintent 本應用被其他應用調起來時（Android 平臺也可以通過 Activity 打開），收到相關數據的回調，字符串類型 在任意頁面中注冊該監聽后，如果本應用被其他應用調起，將觸發該監聽函數，同時將傳給該應用的數據回調給網頁 ### callback(ret, err) ret: - 描述：其他應用或 Activity 傳給本應用的數據 內部字段： ```js { iosUrl:'' //其他應用打開本應用的url，只iOS有效，字符串類型 sourceAppId:'' //其他應用的包名，iOS平臺有可能為空字符串，字符串類型 appParam:{} //其他應用傳遞過來的參數，JSON或字符串類型 } ``` ### 示例代碼 ```js api.addEventListener({ name:'appintent' },function(ret,err){ var appParam = ret.appParam; if(api.systemType == 'ios'){ var iosUrl = ret.iosUrl; } else { var sourceAppId = ret.sourceAppId; } }); ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## smartupdatefinish 云修復使用靜默修復時，更新完畢事件。可通過監聽此事件來通知用戶做是否強制重啟應用等操作或者提示，以使更新生效，字符串類型 如果是提示修復，則不會觸發該事件 ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { value:[{ extra:'' //在控制臺云修復里面進行靜默修復時填寫的附加信息，字符串類型 }] } ``` 不能為空 ### 示例代碼 ```js api.addEventListener({ name:'smartupdatefinish' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## openWin 打開window 若 window 已存在，則會把該 window 顯示到最前面，如果 url 和之前的 url 有變化，或者 reload 為 true 時，頁面會刷新，但是該 window 里面已經打開的 frame 等不會移除 若當前正在進行 openWin、closeWin 等帶動畫過渡的 window 操作，調用此方法會失效 openWin({params}) ### params name： - 類型：字符串 - 默認值：無 - 描述：window 名字，不能為空字符串 url： - 類型：字符串 - 默認值：無 - 描述：頁面地址，可以為本地文件路徑，支持相對路徑和絕對路徑，以及 widget://、fs://等協議路徑，也可以為遠程地址 pageParam： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）頁面參數，新頁面中可以通過 api.pageParam 獲取 bounces： - 類型：布爾 - 默認值：若在 [config.xml](/APICloud/技術專題/app-config-manual) 里面配置了pageBounce，則默認值為配置的值，否則為 false - 描述：（可選項）頁面是否彈動 bgColor： - 類型：字符串 - 默認值：若在 [config.xml](/APICloud/技術專題/app-config-manual) 里面配置了 windowBackground，則默認值為配置的值，否則透明 - 描述：（可選項）背景色，支持圖片和顏色，格式為 #fff、#ffffff、rgba(r,g,b,a)等，圖片路徑支持 fs://、widget://等 APICloud 自定義文件路徑協議，同時支持相對路徑 scrollToTop： - 類型：布爾 - 默認值：false - 描述：（可選項）當點擊狀態欄，頁面是否滾動到頂部。若當前屏幕上不止一個頁面的 scrollToTop 屬性為 true，則所有的都不會起作用。只 iOS 有效 vScrollBarEnabled： - 類型：布爾 - 默認值：true - 描述：（可選項）是否顯示垂直滾動條 hScrollBarEnabled： - 類型：布爾 - 默認值：true - 描述：（可選項）是否顯示水平滾動條 scaleEnabled： - 類型：布爾 - 默認值：false - 描述：（可選項）頁面是否可以縮放 slidBackEnabled： - 類型：布爾 - 默認值：true - 描述：（可選項）是否支持滑動返回。iOS7.0及以上系統中，在新打開的頁面中向右滑動，可以返回到上一個頁面，該字段只 iOS 有效 slidBackType： - 類型：字符串 - 默認值：full - 描述：（可選項）當支持滑動返回時，設置手指在頁面右滑的有效作用區域。取值范圍（full:整個頁面范圍都可以右滑返回，edge:在頁面左邊緣右滑才可以返回），該字段只iOS有效 animation： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）動畫參數，不傳時使用默認動畫，type：[動畫類型](!Constant#b6)，subType：[動畫子類型](!Constant#b8)。 內部字段： ```js { type:"none", //動畫類型（詳見動畫類型常量） subType:"from_right", //動畫子類型（詳見動畫子類型常量） duration:300 //動畫過渡時間，默認300毫秒 } ``` showProgress： - 類型：布爾 - 默認值：false - 描述：（可選項）是否顯示等待框，此參數即將廢棄，使用 progress 參數代替。若傳了 progress 參數，此參數將忽略 progress： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）頁面加載進度配置信息，若不傳則無加載進度效果 內部字段： ```js { type:"", //加載進度效果類型，默認值為 default，取值范圍為 default|page，default 等同于 showProgress 參數效果；為 page 時，進度效果為仿瀏覽器類型，固定在頁面的頂部 title:"", //type 為 default 時顯示的加載框標題 text:"", //type 為 default 時顯示的加載框內容 color:"" //type 為 page 時進度條的顏色，默認值為 #45C01A，支持#FFF，#FFFFFF，rgb(255,255,255)，rgba(255,255,255,1.0)等格式 } ``` delay： - 類型：數字 - 默認值：0 - 描述：（可選項）window 顯示延遲時間，適用于將被打開的 window 中可能需要打開有耗時操作的模塊時，可延遲 window 展示到屏幕的時間，保持 UI 的整體性 reload： - 類型：布爾 - 默認值：false - 描述：（可選項）頁面已經打開時，是否重新加載頁面，重新加載頁面后 apiready 方法將會被執行 allowEdit： - 類型：布爾 - 默認值：false - 描述：（可選項）是否允許長按頁面時彈出選擇菜單 softInputMode： - 類型：字符串 - 默認值：auto - 描述：（可選項）當鍵盤彈出時，輸入框被蓋住時，當前頁面的調整方式，詳見[鍵盤彈出頁面調整方式](!Constant#b26)常量；只iOS有效，Android請在 [config.xml](/APICloud/技術專題/app-config-manual) 里面配置并云編譯使用 customRefreshHeader： - 類型：字符串 - 默認值：無 - 描述：（可選項）設置使用自定義下拉刷新模塊的名稱，設置后可以使用 api.setCustomRefreshHeaderInfo 方法來使用自定義下拉刷新組件 ### 示例代碼 ```js api.openWin({ name: 'page1', url: './page1.html', pageParam: { name: 'test' } }); ``` ### 補充說明 窗口操作 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## closeWin 關閉 window 若當前正在進行 openWin、closeWin 等帶動畫過渡的 window 操作，調用此方法會失效 closeWin({params}) ### params name： - 類型：字符串 - 默認值：無 - 描述：（可選項）window 名字，不傳時關閉當前 window，為 root 時無效 animation： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）動畫參數，不傳時使用默認動畫，type：[動畫類型](!Constant#b6)，subType：[動畫子類型](!Constant#b8)。 內部字段： ```js { type:"none", //動畫類型（詳見動畫類型常量） subType:"from_right", //動畫子類型（詳見動畫子類型常量） duration:300 //動畫過渡時間，默認300毫秒 } ``` ### 示例代碼 ```js //關閉當前window，使用默認動畫 api.closeWin(); //關閉指定window，若待關閉的window不在最上面，則無動畫 api.closeWin({ name: 'page1' }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## closeToWin 關閉到指定 window，最上面顯示的 window 到指定 name 的 window 間的所有 window 都會被關閉 若當前正在進行 openWin、closeWin 等帶動畫過渡的 window 操作，調用此方法會失效 closeToWin({params}) ### params name： - 類型：字符串 - 默認值：無 - 描述：window 名字 animation： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）動畫參數，不傳時使用默認動畫，type：[動畫類型](!Constant#b6)，subType：[動畫子類型](!Constant#b8)。 內部字段： ```js { type:"none", //動畫類型（詳見動畫類型常量） subType:"from_right", //動畫子類型（詳見動畫子類型常量） duration:300 //動畫過渡時間，默認300毫秒 } ``` ### 示例代碼 ```js api.closeToWin({ name: 'root' }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## setWinAttr 設置 window 屬性 setWinAttr({params}) ### params bounces： - 類型：布爾 - 默認值：無 - 描述：（可選項）頁面是否彈動 bgColor： - 類型：字符串 - 默認值：無 - 描述：（可選項）背景色，支持圖片和顏色，格式為#fff、#ffffff、rgba(r,g,b,a)等，圖片路徑支持fs://、widget://等APICloud自定義文件路徑協議，同時支持相對路徑 scrollToTop： - 類型：布爾 - 默認值：無 - 描述：（可選項）當點擊狀態欄，頁面是否滾動到頂部。若當前屏幕上不止一個頁面的scrollToTop屬性為true，則所有的都不會起作用。只iOS有效 vScrollBarEnabled： - 類型：布爾 - 默認值：無 - 描述：（可選項）是否顯示垂直滾動條 hScrollBarEnabled： - 類型：布爾 - 默認值：無 - 描述：（可選項）是否顯示水平滾動條 scaleEnabled： - 類型：布爾 - 默認值：無 - 描述：（可選項）頁面是否可以縮放 slidBackEnabled： - 類型：布爾 - 默認值：無 - 描述：（可選項）是否支持滑動返回。iOS7.0及以上系統中，在新打開的頁面中向右滑動，可以返回到上一個頁面，該字段只iOS有效 softInputMode： - 類型：字符串 - 默認值：無 - 描述：（可選項）當鍵盤彈出時，輸入框被蓋住時，當前頁面的調整方式，詳見[鍵盤彈出頁面調整方式](!Constant#b26)常量；只iOS有效，Android請在 [config.xml](/APICloud/技術專題/app-config-manual) 里面配置并云編譯使用 ### 示例代碼 ```js api.setWinAttr({ bounces: true, bgColor: '#fff', vScrollBarEnabled: true, hScrollBarEnabled: true, scaleEnabled: true, slidBackEnabled: true }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## openFrame 打開 frame 若 frame 已存在，則會把該窗口顯示到最前面并顯示，如果 url 和之前的 url 有變化，或者 reload 為 true 時，頁面會刷新 此方法對 frameGroup 里面的 frame 不起作用 openFrame({params}) ### params name： - 類型：字符串 - 默認值：無 - 描述：frame 名字 url： - 類型：字符串 - 默認值：無 - 描述：頁面地址，可以為本地文件路徑，支持相對路徑和絕對路徑，以及widget://、fs://等協議路徑，也可以為遠程地址 pageParam： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）頁面參數，在新頁面通過 api.pageParam 獲取 bounces： - 類型：布爾 - 默認值：若在 [config.xml](/APICloud/技術專題/app-config-manual) 里面配置了 pageBounce，則默認值為配置的值，否則為 true - 描述：（可選項）頁面是否彈動 bgColor： - 類型：字符串 - 默認值：若在 [config.xml](/APICloud/技術專題/app-config-manual) 里面配置了 frameBackgroundColor，則默認值為配置的值，否則透明 - 描述：（可選項）背景色，支持圖片和顏色，格式為#fff、#ffffff、rgba(r,g,b,a)等，圖片路徑支持fs://、widget://等 APICloud 自定義文件路徑協議，同時支持相對路徑 scrollToTop： - 類型：布爾 - 默認值：true - 描述：（可選項）當點擊狀態欄，頁面是否滾動到頂部。若當前屏幕上不止一個頁面的 scrollToTop 屬性為 true，則所有的都不會起作用。只iOS有效 vScrollBarEnabled： - 類型：布爾 - 默認值：true - 描述：（可選項）是否顯示垂直滾動條 hScrollBarEnabled： - 類型：布爾 - 默認值：true - 描述：（可選項）是否顯示水平滾動條 scaleEnabled： - 類型：布爾 - 默認值：false - 描述：（可選項）頁面是否可以縮放 rect： - 類型：JSON 對象 - 默認值：充滿整個父頁面 - 描述：（可選項）frame 的位置和大小，設置 margin 后，在不同手機上面會保持與父頁面的各方向邊距一致，而中間區域會自動擴充。 內部字段： ```js { x:0, //左上角x坐標 y:0, //左上角y坐標 w:320, //寬度，若傳'auto'，頁面從x位置開始自動充滿父頁面寬度 h:480 //高度，若傳'auto'，頁面從y位置開始自動充滿父頁面高度 marginLeft:0, //相對父 window 左外邊距的距離 marginTop:0, //相對父 window 上外邊距的距離 marginBottom:0, //相對父 window 下外邊距的距離 marginRight:0 //相對父 window 右外邊距的距離 } ``` showProgress： - 類型：布爾 - 默認值：false - 描述：（可選項）是否顯示等待框，此參數即將廢棄，使用 progress 參數代替。若傳了 progress 參數，此參數將忽略 progress： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）頁面加載進度配置信息，若不傳則無加載進度效果 內部字段： ```js { type:"", //加載進度效果類型，默認值為default，取值范圍為default|page，default等同于showProgress參數效果；為page時，進度效果為仿瀏覽器類型，固定在頁面的頂部 title:"", //type為default時顯示的加載框標題 text:"", //type為default時顯示的加載框內容 color:"" //type為page時進度條的顏色，默認值為#45C01A，支持#FFF，#FFFFFF，rgb(255,255,255)，rgba(255,255,255,1.0)等格式 } ``` reload： - 類型：布爾 - 默認值：false - 描述：（可選項）頁面已經打開時，是否重新加載頁面 allowEdit： - 類型：布爾 - 默認值：false - 描述：（可選項）是否允許長按頁面時彈出選擇菜單 softInputMode： - 類型：字符串 - 默認值：auto - 描述：（可選項）當鍵盤彈出時，輸入框被蓋住時，當前頁面的調整方式，詳見[鍵盤彈出頁面調整方式](!Constant#b26)常量；只iOS有效，Android請在 [config.xml](/APICloud/技術專題/app-config-manual) 里面配置并云編譯使用 animation： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）動畫參數，不傳時無動畫，type：[動畫類型](!Constant#b6)，subType：[動畫子類型](!Constant#b8)。 內部字段： ```js { type:"none", //動畫類型（詳見動畫類型常量） subType:"from_right", //動畫子類型（詳見動畫子類型常量） duration:300 //動畫過渡時間，默認300毫秒 } ``` customRefreshHeader： - 類型：字符串 - 默認值：無 - 描述：（可選項）設置使用自定義下拉刷新模塊的名稱，設置后可以使用 api.setCustomRefreshHeaderInfo 方法來使用自定義下拉刷新組件 ### 示例代碼 ```js api.openFrame({ name: 'page2', url: './page2.html', rect: { x: 0, y: 0, w: 320, h: 480 }, pageParam: { name: 'test' }, bounces: true, bgColor: 'rgba(0,0,0,0)', vScrollBarEnabled: true, hScrollBarEnabled: true }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## closeFrame 關閉frame closeFrame({params}) ### params name： - 類型：字符串 - 默認值：無 - 描述：（可選項）frame 名字，不傳時關閉當前 frame ### 示例代碼 ```js api.closeFrame({ name: 'page2' }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## setFrameAttr 設置frame屬性 setFrameAttr({params}) ### params name： - 類型：字符串 - 默認值：無 - 描述：frame 名稱 bounces： - 類型：布爾 - 默認值：無 - 描述：（可選項）頁面是否彈動 hidden： - 類型：布爾 - 默認值：無 - 描述：（可選項）本 frame 是否隱藏（隱藏即從屏幕上移除，但不銷毀） bgColor： - 類型：字符串 - 默認值：無 - 描述：（可選項）背景色，支持圖片和顏色，格式為#fff、#ffffff、rgba(r,g,b,a)等，圖片路徑支持fs://、widget://等 APICloud 自定義文件路徑協議，同時支持相對路徑 scrollToTop： - 類型：布爾 - 默認值：無 - 描述：（可選項）當點擊狀態欄，頁面是否滾動到頂部。若當前屏幕上不止一個頁面的 scrollToTop 屬性為 true，則所有的都不會起作用。只iOS有效 vScrollBarEnabled： - 類型：布爾 - 默認值：無 - 描述：（可選項）是否顯示垂直滾動條 hScrollBarEnabled： - 類型：布爾 - 默認值：無 - 描述：（可選項）是否顯示水平滾動條 scaleEnabled： - 類型：布爾 - 默認值：無 - 描述：（可選項）頁面是否可以縮放 rect： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）窗口區域 內部字段： ```js { x:0, //左上角x坐標 y:0, //左上角y坐標 w:320, //寬度，若傳'auto'，頁面從x位置開始自動充滿父頁面寬度 h:480 //高度，若傳'auto'，頁面從y位置開始自動充滿父頁面高度 } ``` softInputMode： - 類型：字符串 - 默認值：無 - 描述：（可選項）當鍵盤彈出時，輸入框被蓋住時，當前頁面的調整方式，詳見[鍵盤彈出頁面調整方式](!Constant#b26)常量；只iOS有效，Android請在 [config.xml](/APICloud/技術專題/app-config-manual) 里面配置并云編譯使用 ### 示例代碼 ```js api.setFrameAttr({ name: 'page2', rect: { x: 0, y: 0, w: 320, h: 480 }, bounces: true, bgColor: '#fff', vScrollBarEnabled: true, hScrollBarEnabled: true }); ``` ### 補充說明 設置 frame 屬性 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## bringFrameToFront 調整 frame 到前面 bringFrameToFront({params}) ### params from： - 類型：字符串 - 默認值：無 - 描述：待調整顯示順序的 frame 名字 to： - 類型：字符串 - 默認值：無 - 描述：（可選項）frame 名字，不傳時調整 from 對應 frame 到最前面，否則調整 from 對應 frame 到此 frame 前面 ### 示例代碼 ```js api.bringFrameToFront({ from: 'page1', to: 'page2' }); ``` ### 補充說明 調整 frame 到前面 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## sendFrameToBack 調整 frame 到后面 sendFrameToBack({params}) ### params from： - 類型：字符串 - 默認值：無 - 描述：frame 名字 to： - 類型：字符串 - 默認值：無 - 描述：（可選項）frame 名字，不傳時調整 from 對應 frame 到最后面，否則調整 from 對應 frame 到此 frame 后面 ### 示例代碼 ```js api.sendFrameToBack ({ from: 'page1', to: 'page2' }); ``` ### 補充說明 調整 frame 到后面 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## setFrameClient 設置指定 frame 的頁面加載監聽，僅在 window 中調用生效，可以對多個 frame 進行監聽。 setFrameClient({params}, callback(ret, err)) ### params frameName： - 類型：字符串 - 默認值：無 - 描述：frame 名字 ### callback(ret, err) ret： - 類型：JSON 對象 - 描述：frame 加載狀態、加載進度等發生變化時的回調 內部字段： ```js { state:0, //加載狀態，數字類型，取值范圍：0-開始加載；1-加載進度發生變化；2-結束加載；3-title發生變化；4-url發生變化 progress:0, //state為1時，頁面的加載進度，數字類型，取值范圍 0-100 title:'', //state為3時，頁面當前的title，字符串類型 url:'' //state為0|2|4時，頁面當前的url，字符串類型 } ``` ### 示例代碼 ```js api.setFrameClient({ frameName:'webpage' }, function(ret, err){ switch (ret.state) { case 0: break; case 1: break; case 2: break; case 3: break; case 4: break; default: break; } }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.2.0及更高版本 ## animation frame 動畫，支持平移，縮放，旋轉和透明度變化 僅支持 frame，不支持 window 以及 frameGroup 里面的 frame animation({params}, callback(ret, err)) ### params name： - 類型：字符串 - 默認值：當前 frame - 描述：frame 名字 delay： - 類型：數字 - 默認值：0 - 描述：（可選項）動畫延遲時間，單位毫秒，默認立即開始 duration： - 類型：數字 - 默認值：0 - 描述：（可選項）動畫過渡時間，單位毫秒 curve： - 類型：字符串 - 默認值：ease_in_out - 描述：（可選項）動畫曲線類型，指定動畫開始和結束時的快慢，詳見動畫曲線類型 repeatCount： - 類型：數字 - 默認值：0 - 描述：（可選項）動畫次數，默認不重復，為-1時無限重復 autoreverse： - 類型：布爾 - 默認值：false - 描述：（可選項）一次動畫結束后是否自動反轉動畫 alpha： - 類型：數字 - 默認值：無 - 描述：（可選項）整個頁面的透明度，介于0 1之間，Android 不支持 translation： - 類型：JSON - 默認值：無 - 描述：（可選項）位置平移參數 內部字段： ```js { x: 0, //x軸方向上的平移距離，默認為0 y: 0, //y軸方向上的平移距離，默認為0 z: 0 //z軸方向上的平移距離，默認為0，Android不支持 } ``` scale： - 類型：JSON - 默認值：無 - 描述：（可選項）頁面縮放參數，Android 不支持 內部字段： ```js { x: 1, //x軸方向上的放大倍率，默認為1 y: 1, //y軸方向上的放大倍率，默認為1 z: 1 //z軸方向上的放大倍率，默認為1 } ``` rotation： - 類型：JSON - 默認值：無 - 描述：（可選項）頁面旋轉參數，Android 不支持 內部字段： ```js { degree:0, //旋轉角度，默認0 x: 0, //繞x軸旋轉，默認為0 y: 0, //繞y軸旋轉，默認為0 z: 1 //繞z軸旋轉，默認為1 } ``` ### callback(ret, err) 動畫結束后的回調 ### 示例代碼 ```js api.animation ({ name: 'page1', delay: 1000, duration: 3000, curve: 'ease_in', repeatCount: 2, autoreverse: true, alpha: 0.6, translation: { x: 0, y: 100, z: 0 }, scale: { x: 1.2, y: 1, z: 1 }, rotation: { degree: 45, x: 0, y: 0, z: 1 } }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## openFrameGroup 打開 frame 組 frame 組打開后，當前頁面加載完成后，頁面會預加載后面指定個數頁面 openFrameGroup({params}, callback(ret, err)) ### params name： - 類型：字符串 - 默認值：無 - 描述：frame 組名字 background： - 類型：字符串 - 默認值：無 - 描述：（可選項）frame 組背景，顏色（#fff,#ffffff,rgba(r,g,b,a)）或圖片（支持文件路徑協議和相對路徑） scrollEnabled： - 類型：布爾 - 默認值：true - 描述：（可選項）frame 組是否能夠左右滾動 rect： - 類型：JSON 對象 - 默認值：充滿整個父頁面 - 描述：（可選項）frameGroup 的位置和大小，設置 margin 后，在不同手機上面會保持與父頁面的各方向邊距一致，而中間區域會自動擴充。 內部字段： ```js { x:0, //左上角x坐標 y:0, //左上角y坐標 w:320, //寬度，若傳'auto'，頁面從x位置開始自動充滿父頁面寬度 h:480， //高度，若傳'auto'，頁面從y位置開始自動充滿父頁面高度 marginLeft:0, //相對父window左外邊距的距離 marginTop:0, //相對父window上外邊距的距離 marginBottom:0, //相對父window下外邊距的距離 marginRight:0 //相對父window右外邊距的距離 } ``` index： - 類型：數字 - 默認值：0 - 描述：（可選項）默認顯示的頁面索引 preload： - 類型：數字 - 默認值：1 - 描述：（可選項）預加載的 frame 個數，默認加載當前頁后面一個 frames： - 類型：數組 - 默認值：無 - 描述：frame 數組 內部字段： ```js [{ name:'', //frame名字，字符串類型，不能為空字符串 url:'', //頁面地址，可以為本地文件路徑，支持相對路徑和絕對路徑，以及widget://、fs://等協議路徑，也可以為遠程地址，字符串類型 pageParam:{}, //（可選項）頁面參數，頁面中可以通過api.pageParam獲取，JSON對象 bounces:true, //（可選項）是否彈動，布爾型，默認值：若在 config.xml 里面配置了pageBounce，則默認值為配置的值，否則為false bgColor:'#fff', //（可選項）背景色，支持圖片和顏色，格式為#fff、#ffffff、rgba(r,g,b,a)等，圖片路徑支持fs://、widget://等APICloud自定義文件路徑協議，同時支持相對路徑 scrollToTop:true //（可選項）當點擊狀態欄，頁面是否滾動到頂部。若當前屏幕上不止一個頁面的scrollToTop屬性為true，則所有的都不會起作用。默認值：true。只iOS有效 vScrollBarEnabled:true, //（可選項）是否顯示垂直滾動條，布爾型，默認值：true hScrollBarEnabled:false, //（可選項）是否顯示水平滾動條，布爾型，默認值：false scaleEnabled:true, //（可選項）頁面是否可以縮放，布爾型，默認值：false allowEdit:false, //（可選項）是否允許長按頁面時彈出選擇菜單 softInputMode:'auto' //（可選項）當鍵盤彈出時，輸入框被蓋住時，當前頁面的調整方式，參考鍵盤彈出頁面調整方式常量，只iOS有效 customRefreshHeader:'' //（可選項）設置使用自定義下拉刷新模塊的名稱，設置后可以使用api.setCustomRefreshHeaderInfo方法來使用自定義下拉刷新組件 }] ``` ### callback(ret, err) ret： - 類型：JSON 對象 - 描述：當前顯示在屏幕上的 frame 變化時會回調 內部字段： ```js { name:'', //當前 frame 名稱 index:0 //當前 frame 索引 } ``` ### 示例代碼 ```js api.openFrameGroup ({ name: 'group1', background: '#fff', scrollEnabled: false, rect: { x: 0, y: 0, w: 'auto', h: 'auto' }, index: 1, frames: [{ name: 'frame1', url: 'frame1.html', bgColor: '#fff' },{ name: 'frame2', url: 'frame2.html', bgColor: '#fff' }] }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## closeFrameGroup 關閉frame組 closeFrameGroup({params}) ### params name： - 類型：字符串 - 默認值：無 - 描述：frame 組名字 ### 示例代碼 ```js api.closeFrameGroup({ name: 'group1' }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## setFrameGroupAttr 設置 frame 組屬性 setFrameGroupAttr({params}) ### params name： - 類型：字符串 - 默認值：無 - 描述：frame 組名字 hidden： - 類型：布爾 - 默認值：無 - 描述：（可選項）frame 組是否隱藏 scrollEnabled： - 類型：布爾 - 默認值：無 - 描述：（可選項）frame 組是否能夠左右滾動 rect： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）frame 組區域 內部字段： ```js { x:0, //左上角x坐標 y:0, //左上角y坐標 w:320, //寬度，若傳'auto'，frame組從x位置開始自動充滿父頁面寬度 h:240 //高度，若傳'auto'，frame組從y位置開始自動充滿父頁面高度 } ``` ### 示例代碼 ```js api.setFrameGroupAttr({ name: 'group1', hidden: true }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## setFrameGroupIndex 設置 frame 組當前可見 frame setFrameGroupIndex({params}) ### params name： - 類型：字符串 - 默認值：無 - 描述：frame 組名字 index： - 類型：數字 - 默認值：無 - 描述：frame 索引 scroll： - 類型：布爾 - 默認值：false - 描述：（可選項）是否平滑滾動至目標窗口，即是否帶有動畫 reload： - 類型：布爾 - 默認值：false - 描述：（可選項）是否刷新 frame ### 示例代碼 ```js api.setFrameGroupIndex({ name: 'group1', index: 2, scroll: true }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## openPopoverWin iPad 上面打開彈出層窗口，彈出層從底部往上彈出，然后顯示在屏幕中間一片指定區域，周圍為黑色半透明，只 iPad 上面有效 彈出層是模態的，彈出層后面的界面將不可操作，在彈出層窗口里面不能再打開彈出窗口 彈出層里面頁面可以使用所有的 window 和 frame 相關操作，如 openWin、openFrame 等 使用 execScript() 方法時，引擎只會在整個彈出層里面的窗口中去尋找要執行腳本的窗口，如果要和彈出層下面的窗口間進行通信，可以使用 sendEvent() 方法代替實現 openPopoverWin({params}) ### params width： - 類型：數字 - 默認值：540 - 描述：（可選項）彈出窗口在屏幕中間顯示的寬度 height： - 類型：數字 - 默認值：620 - 描述：（可選項）彈出窗口在屏幕中間顯示的高度 name： - 類型：字符串 - 默認值：無 - 描述：彈出層的第一個 window 的名字，不能為空字符串 url： - 類型：字符串 - 默認值：無 - 描述：彈出層的第一個 window 頁面地址，可以為本地文件路徑，支持相對路徑和絕對路徑，以及 widget://、fs:// 等協議路徑，也可以為遠程地址，不能為空字符串 pageParam： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）頁面參數，新頁面中可以通過 api.pageParam 獲取 bounces： - 類型：布爾 - 默認值：若在 [config.xml](/APICloud/技術專題/app-config-manual) 里面配置了 pageBounce，則默認值為配置的值，否則為 false - 描述：（可選項）頁面是否彈動 bgColor： - 類型：字符串 - 默認值：若在 [config.xml](/APICloud/技術專題/app-config-manual) 里面配置了 windowBackground，則默認值為配置的值，否則透明 - 描述：（可選項）背景色，支持圖片和顏色，格式為 #fff、#ffffff、rgba(r,g,b,a) 等，圖片路徑支持 fs://、widget:// 等 APICloud 自定義文件路徑協議，同時支持相對路徑 scrollToTop： - 類型：布爾 - 默認值：false - 描述：（可選項）當點擊狀態欄，頁面是否滾動到頂部。若當前屏幕上不止一個頁面的 scrollToTop 屬性為 true，則所有的都不會起作用。只 iOS 有效 vScrollBarEnabled： - 類型：布爾 - 默認值：true - 描述：（可選項）是否顯示垂直滾動條 hScrollBarEnabled： - 類型：布爾 - 默認值：true - 描述：（可選項）是否顯示水平滾動條 scaleEnabled： - 類型：布爾 - 默認值：false - 描述：（可選項）頁面是否可以縮放 showProgress： - 類型：布爾 - 默認值：false - 描述：（可選項）是否顯示等待框，此參數即將廢棄，使用 progress 參數代替。若傳了 progress 參數，此參數將忽略 progress： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）頁面加載進度配置信息，若不傳則無加載進度效果 內部字段： ```js { type:"", //加載進度效果類型，默認值為default，取值范圍為default|page，default等同于showProgress參數效果；為page時，進度效果為仿瀏覽器類型，固定在頁面的頂部 title:"", //type為default時顯示的加載框標題 text:"", //type為default時顯示的加載框內容 color:"" //type為page時進度條的顏色，默認值為#45C01A，支持#FFF，#FFFFFF，rgb(255,255,255)，rgba(255,255,255,1.0)等格式 } ``` allowEdit： - 類型：布爾 - 默認值：false - 描述：（可選項）是否允許長按頁面時彈出選擇菜單 softInputMode： - 類型：字符串 - 默認值：auto - 描述：（可選項）當鍵盤彈出時，輸入框被蓋住時，當前頁面的調整方式，詳見[鍵盤彈出頁面調整方式](!Constant#b26)常量；只iOS有效，Android請在 [config.xml](/APICloud/技術專題/app-config-manual) 里面配置并云編譯使用 customRefreshHeader： - 類型：字符串 - 默認值：無 - 描述：（可選項）設置使用自定義下拉刷新模塊的名稱，設置后可以使用 api.setCustomRefreshHeaderInfo 方法來使用自定義下拉刷新組件 ### 示例代碼 ```js api.openPopoverWin({ width: 480, height: 400, name: 'page1', url: './page1.html' }); ``` ### 補充說明 無 ### 可用性 iOS系統 可提供的1.0.0及更高版本 ## closePopoverWin 關閉整個彈出層窗口，只 iPad 上面有效 在當前彈出層里面的任意頁面里面調用都會關閉整個彈出層 closePopoverWin() ### 示例代碼 ```js api.closePopoverWin(); ``` ### 補充說明 無 ### 可用性 iOS系統 可提供的1.0.0及更高版本 ## openSlidLayout 打開側滑式布局 打開后，其所在 window 的 name 默認為 slidLayout，所以關閉整個側滑布局可以通過 api.closeWin({name:'slidLayout'}) 實現，同時可以通過 api.openWin({name:'slidLayout'})來把整個側滑顯示到最前面 openSlidLayout({params}, callback(ret, err)) ### params type： - 類型：字符串 - 默認值：all - 描述：（可選項）側滑類型（left：左側滑、right：右側滑、all：左右側滑）。安卓暫只支持left。 leftEdge： - 類型：數字 - 默認值：60 - 描述：（可選項）左側滑時，側滑 window 停留時露出的寬度。即將廢棄，用 slidPaneStyle 中 leftEdge 參數代替 rightEdge： - 類型：數字 - 默認值：60 - 描述：（可選項）右側滑時，側滑 window 停留時露出的寬度。即將廢棄，用 slidPaneStyle 中 rightEdge 參數代替 slidPaneStyle： - 類型：JSON 對象 - 默認值：無 - 描述：側滑層 window 樣式 內部字段： ```js { leftEdge: //（可選項）左側滑時，側滑window停留時露出的寬度，默認60，數字類型 rightEdge: //（可選項）右側滑時，側滑window停留時露出的寬度，默認60，數字類型 leftScale: //（可選項）左側滑時，側滑window移動時能縮放的最小倍數，0-1.0，默認1.0，數字類型，只支持iOS rightScale: //（可選項）右側滑時，側滑window移動時能縮放的最小倍數，0-1.0，默認1.0，數字類型，只支持iOS } ``` fixedPaneStyle： - 類型：JSON 對象 - 默認值：無 - 描述：底部固定層 window 樣式 內部字段： ```js { leftEdge: //（可選項）左側滑時，固定window能向左移動的最大寬度，默認0，數字類型，只支持iOS rightEdge: //（可選項）右側滑時，固定window能向右移動的最大寬度，默認0，數字類型，只支持iOS leftScale: //（可選項）左側滑時，固定window向左移動時能縮放的最小倍數，0-1.0，默認1.0，數字類型，只支持iOS rightScale: //（可選項）右側滑時，固定window向右移動時能縮放的最小倍數，0-1.0，默認1.0，數字類型，只支持iOS leftMaskBg: //（可選項）左側滑時，固定window上面的遮罩層背景，支持顏色和圖片，默認rgba(0,0,0,0)，字符串類型，只支持iOS rightMaskBg: //（可選項）右側滑時，固定window上面的遮罩層背景，支持顏色和圖片，默認rgba(0,0,0,0)，字符串類型，只支持iOS leftBg: //（可選項）左側滑時，固定window后面的背景，縮放過程中后面的背景將會顯示出來，支持顏色和圖片，默認rgba(0,0,0,0)，字符串類型，只支持iOS rightBg: //（可選項）右側滑時，固定window后面的背景，縮放過程中后面的背景將會顯示出來，支持顏色和圖片，默認rgba(0,0,0,0)，字符串類型，只支持iOS } ``` fixedPane： - 類型：JSON 對象 - 默認值：無 - 描述：底部固定層 window 內部字段： ```js { name:'', // window名字（字符串類型） url:'', // 頁面地址，可以為本地文件路徑，支持相對路徑和絕對路徑，以及widget://、fs://等協議路徑，也可以為遠程地址 pageParam:{}, //（可選項）頁面參數，頁面中可以通過api.pageParam獲取，JSON對象 bgColor:'', //（可選項）背景色，支持圖片和顏色，格式為#fff、#ffffff、rgba(r,g,b,a)等，圖片路徑支持fs://、widget://等APICloud自定義文件路徑協議，同時支持相對路徑 bounces:false, //（可選項）是否彈動，默認值：若在 config.xml 里面配置了pageBounce，則默認值為配置的值，否則為false scrollToTop:false //（可選項）當點擊狀態欄，頁面是否滾動到頂部。若當前屏幕上不止一個頁面的scrollToTop屬性為true，則所有的都不會起作用。默認值：true。只iOS有效 vScrollBarEnabled:true, //（可選項）是否顯示垂直滾動條，默認true hScrollBarEnabled:true, //（可選項）是否顯示水平滾動條，默認true scaleEnabled:true, //（可選項）頁面是否可以縮放，布爾型，默認值：false allowEdit:false, //（可選項）是否允許長按頁面時彈出選擇菜單 softInputMode:'auto' //（可選項）當鍵盤彈出時，輸入框被蓋住時，當前頁面的調整方式，參考鍵盤彈出頁面調整方式常量，只iOS有效 customRefreshHeader:'' //（可選項）設置使用自定義下拉刷新模塊的名稱，設置后可以使用api.setCustomRefreshHeaderInfo方法來使用自定義下拉刷新組件 } ``` slidPane： - 類型：JSON 對象 - 默認值：無 - 描述：側滑層window 內部字段： ```js { name:'', // window名字（字符串類型） url:'', // 頁面地址，可以為本地文件路徑，支持相對路徑和絕對路徑，以及widget://、fs://等協議路徑，也可以為遠程地址 pageParam:{}, //（可選項）頁面參數，頁面中可以通過api.pageParam獲取，JSON對象 bgColor:'', //（可選項）背景色，支持圖片和顏色，格式為#fff、#ffffff、rgba(r,g,b,a)等，圖片路徑支持fs://、widget://等APICloud自定義文件路徑協議，同時支持相對路徑 bounces:false, //（可選項）是否彈動，默認值：若在 config.xml 里面配置了pageBounce，則默認值為配置的值，否則為false scrollToTop:false //（可選項）當點擊狀態欄，頁面是否滾動到頂部。若當前屏幕上不止一個頁面的scrollToTop屬性為true，則所有的都不會起作用。默認值：true。只iOS有效 vScrollBarEnabled:true, //（可選項）是否顯示垂直滾動條，默認true hScrollBarEnabled:true, //（可選項）是否顯示水平滾動條，默認true scaleEnabled:true, //（可選項）頁面是否可以縮放，布爾型，默認值：false allowEdit:false, //（可選項）是否允許長按頁面時彈出選擇菜單 softInputMode:'auto' //（可選項）當鍵盤彈出時，輸入框被蓋住時，當前頁面的調整方式，參考鍵盤彈出頁面調整方式常量，只iOS有效 customRefreshHeader:'' //（可選項）設置使用自定義下拉刷新模塊的名稱，設置后可以使用api.setCustomRefreshHeaderInfo方法來使用自定義下拉刷新組件 } ``` ### callback(ret, err) ret： - 類型：JSON 對象 - 描述：手指頭觸摸屏幕，引起開始側滑時的回調，左右側滑時應該在這里面判斷顯示左邊頁面還是右邊頁面 內部字段： ```js { type: 'left' //側滑方向，left或right event: 'slide' //側滑事件，（slide-當前處于滑動狀態、open-側滑打開狀態、close-側滑關閉狀態 } ``` ### 示例代碼 ```js api.openSlidLayout ({ type: 'all', leftEdge: 80, rightEdge: 60, fixedPane: { name: 'win1', url: 'win1.html', bgColor: '#fff', bounces: true, vScrollBarEnabled: true, hScrollBarEnabled: false }, slidPane: { name: 'win2', url: 'win2.html', bgColor: '#fff', bounces: true, vScrollBarEnabled: true, hScrollBarEnabled: false } }, function(ret, err){ }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## openSlidPane 向左或右進行側滑 openSlidPane({params}) ### params type： - 類型：字符串 - 默認值：無 - 描述：側滑類型，left 或 right ### 示例代碼 ```js api.openSlidPane({ type: 'left' }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## closeSlidPane 當 SlidPane 處于左或右側滑狀態時，將其收起 closeSlidPane() ### 示例代碼 ```js api.closeSlidPane(); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## lockSlidPane 鎖住 SlidPane，使其不能跟隨手指滑動而移動 lockSlidPane() ### 示例代碼 ```js api.lockSlidPane(); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## unlockSlidPane 解鎖 SlidPane，使其能跟隨手指滑動而移動 unlockSlidPane() ### 示例代碼 ```js api.unlockSlidPane(); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## openDrawerLayout 打開一個抽屜式側滑 window，可以從當前 window 的左右邊緣滑動拉出側滑 window。 此方法在 openWin 方法的基礎上增加了 leftPane、rightPane 參數，所以可以通過 api.closeWin()方法來關閉整個抽屜式側滑。 openDrawerLayout({params}) ### params name： - 類型：字符串 - 默認值：無 - 描述：window 名字，不能為空字符串 url： - 類型：字符串 - 默認值：無 - 描述：頁面地址，可以為本地文件路徑，支持相對路徑和絕對路徑，以及 widget://、fs://等協議路徑，也可以為遠程地址 pageParam： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）頁面參數，新頁面中可以通過 api.pageParam 獲取 bounces： - 類型：布爾 - 默認值：若在 [config.xml](/APICloud/技術專題/app-config-manual) 里面配置了 pageBounce，則默認值為配置的值，否則為 false - 描述：（可選項）頁面是否彈動 bgColor： - 類型：字符串 - 默認值：若在 [config.xml](/APICloud/技術專題/app-config-manual) 里面配置了 windowBackground，則默認值為配置的值，否則透明 - 描述：（可選項）背景色，支持圖片和顏色，格式為 #fff、#ffffff、rgba(r,g,b,a) 等，圖片路徑支持 fs://、widget:// 等 APICloud 自定義文件路徑協議，同時支持相對路徑 scrollToTop： - 類型：布爾 - 默認值：false - 描述：（可選項）當點擊狀態欄，頁面是否滾動到頂部。若當前屏幕上不止一個頁面的scrollToTop屬性為true，則所有的都不會起作用。只iOS有效 vScrollBarEnabled： - 類型：布爾 - 默認值：true - 描述：（可選項）是否顯示垂直滾動條 hScrollBarEnabled： - 類型：布爾 - 默認值：true - 描述：（可選項）是否顯示水平滾動條 scaleEnabled： - 類型：布爾 - 默認值：false - 描述：（可選項）頁面是否可以縮放 slidBackEnabled： - 類型：布爾 - 默認值：true - 描述：（可選項）是否支持滑動返回。iOS7.0及以上系統中，在新打開的頁面中向右滑動，可以返回到上一個頁面，該字段只iOS有效 slidBackType： - 類型：字符串 - 默認值：full - 描述：（可選項）當支持滑動返回時，設置手指在頁面右滑的有效作用區域。取值范圍（full:整個頁面范圍都可以右滑返回，edge:在頁面左邊緣右滑才可以返回），該字段只iOS有效 animation： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）動畫參數，不傳時使用默認動畫，type：[動畫類型](!Constant#b6)，subType：[動畫子類型](!Constant#b8)。 內部字段： ```js { type:"none", //動畫類型（詳見動畫類型常量） subType:"from_right", //動畫子類型（詳見動畫子類型常量） duration:300 //動畫過渡時間，默認300毫秒 } ``` showProgress： - 類型：布爾 - 默認值：false - 描述：（可選項）是否顯示等待框，此參數即將廢棄，使用 progress 參數代替。若傳了 progress 參數，此參數將忽略 progress： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）頁面加載進度配置信息，若不傳則無加載進度效果 內部字段： ```js { type:"", //加載進度效果類型，默認值為default，取值范圍為default|page，default等同于showProgress參數效果；為page時，進度效果為仿瀏覽器類型，固定在頁面的頂部 title:"", //type為default時顯示的加載框標題 text:"", //type為default時顯示的加載框內容 color:"" //type為page時進度條的顏色，默認值為#45C01A，支持#FFF，#FFFFFF，rgb(255,255,255)，rgba(255,255,255,1.0)等格式 } ``` delay： - 類型：數字 - 默認值：0 - 描述：（可選項）window 顯示延遲時間，適用于將被打開的 window 中可能需要打開有耗時操作的模塊時，可延遲 window 展示到屏幕的時間，保持UI的整體性 reload： - 類型：布爾 - 默認值：false - 描述：（可選項）頁面已經打開時，是否重新加載頁面，重新加載頁面后 apiready 方法將會被執行 allowEdit： - 類型：布爾 - 默認值：false - 描述：（可選項）是否允許長按頁面時彈出選擇菜單 softInputMode： - 類型：字符串 - 默認值：auto - 描述：（可選項）當鍵盤彈出時，輸入框被蓋住時，當前頁面的調整方式，詳見[鍵盤彈出頁面調整方式](!Constant#b26)常量；只iOS有效，Android請在 [config.xml](/APICloud/技術專題/app-config-manual) 里面配置并云編譯使用 customRefreshHeader： - 類型：字符串 - 默認值：無 - 描述：（可選項）設置使用自定義下拉刷新模塊的名稱，設置后可以使用 api.setCustomRefreshHeaderInfo 方法來使用自定義下拉刷新組件 leftPane： - 類型：JSON 對象 - 默認值：無 - 描述：左邊側滑 window 內部字段： ```js { edge:60, // 左邊側滑打開后，漏出的半透明區域寬度，默認值為60。此時左邊側滑window的寬度為屏幕寬度減去edge name:'', // window名字（字符串類型） url:'', // 頁面地址，可以為本地文件路徑，支持相對路徑和絕對路徑，以及widget://、fs://等協議路徑，也可以為遠程地址 pageParam:{}, //（可選項）頁面參數，頁面中可以通過api.pageParam獲取，JSON對象 bgColor:'', //（可選項）背景色，支持圖片和顏色，格式為#fff、#ffffff、rgba(r,g,b,a)等，圖片路徑支持fs://、widget://等APICloud自定義文件路徑協議，同時支持相對路徑 bounces:false, //（可選項）是否彈動，默認值：若在 config.xml 里面配置了pageBounce，則默認值為配置的值，否則為false scrollToTop:false //（可選項）當點擊狀態欄，頁面是否滾動到頂部。若當前屏幕上不止一個頁面的scrollToTop屬性為true，則所有的都不會起作用。默認值：true。只iOS有效 vScrollBarEnabled:true, //（可選項）是否顯示垂直滾動條，默認true hScrollBarEnabled:true, //（可選項）是否顯示水平滾動條，默認true scaleEnabled:true, //（可選項）頁面是否可以縮放，布爾型，默認值：false allowEdit:false, //（可選項）是否允許長按頁面時彈出選擇菜單 softInputMode:'auto' //（可選項）當鍵盤彈出時，輸入框被蓋住時，當前頁面的調整方式，參考鍵盤彈出頁面調整方式常量，只iOS有效 customRefreshHeader:'' //（可選項）設置使用自定義下拉刷新模塊的名稱，設置后可以使用api.setCustomRefreshHeaderInfo方法來使用自定義下拉刷新組件 } ``` rightPane： - 類型：JSON 對象 - 默認值：無 - 描述：右邊側滑 window 內部字段： ```js { edge:60, // 右邊側滑打開后，漏出的半透明區域寬度，默認值為60。此時右邊側滑window的寬度為屏幕寬度減去edge name:'', // window名字（字符串類型） url:'', // 頁面地址，可以為本地文件路徑，支持相對路徑和絕對路徑，以及widget://、fs://等協議路徑，也可以為遠程地址 pageParam:{}, //（可選項）頁面參數，頁面中可以通過api.pageParam獲取，JSON對象 bgColor:'', //（可選項）背景色，支持圖片和顏色，格式為#fff、#ffffff、rgba(r,g,b,a)等，圖片路徑支持fs://、widget://等APICloud自定義文件路徑協議，同時支持相對路徑 bounces:false, //（可選項）是否彈動，默認值：若在 config.xml 里面配置了pageBounce，則默認值為配置的值，否則為false scrollToTop:false //（可選項）當點擊狀態欄，頁面是否滾動到頂部。若當前屏幕上不止一個頁面的scrollToTop屬性為true，則所有的都不會起作用。默認值：true。只iOS有效 vScrollBarEnabled:true, //（可選項）是否顯示垂直滾動條，默認true hScrollBarEnabled:true, //（可選項）是否顯示水平滾動條，默認true scaleEnabled:true, //（可選項）頁面是否可以縮放，布爾型，默認值：false allowEdit:false, //（可選項）是否允許長按頁面時彈出選擇菜單 softInputMode:'auto' //（可選項）當鍵盤彈出時，輸入框被蓋住時，當前頁面的調整方式，參考鍵盤彈出頁面調整方式常量，只iOS有效 customRefreshHeader:'' //（可選項）設置使用自定義下拉刷新模塊的名稱，設置后可以使用api.setCustomRefreshHeaderInfo方法來使用自定義下拉刷新組件 } ``` ### 示例代碼 ```js api.openDrawerLayout({ name: 'main', url: './main.html', animation:{ type:'none' }, leftPane:{ name: 'leftPane', url: 'leftPane.html' } }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.2.0及更高版本 ## openDrawerPane 打開抽屜式側滑Pane openDrawerPane({params}) ### params type： - 類型：字符串 - 默認值：無 - 描述：側滑類型，left 或 right ### 示例代碼 ```js api.openDrawerPane({ type: 'left' }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.2.0及更高版本 ## closeDrawerPane 關閉抽屜式側滑Pane closeDrawerPane() ### 示例代碼 ```js api.closeDrawerPane(); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.2.0及更高版本 ## execScript 在指定 window 或者 frame 中執行腳本，對于 frameGroup 里面的 frame 也有效，若 name 和 frameName 都未指定，則在當前 window 中執行腳本，具體執行邏輯見補充說明。 execScript({params}) ### params name： - 類型：字符串 - 默認值：無 - 描述：（可選項）window 名稱，若要跨 window 執行腳本，該字段必須指定，首頁的名稱為 root frameName： - 類型：字符串 - 默認值：無 - 描述：（可選項）frame名稱 script： - 類型：字符串 - 默認值：無 - 描述：js代碼 ### 示例代碼 ```js //在名為winName的window中執行jsfun腳本 var jsfun = 'funcGoto();'; api.execScript({ name: 'winName', script: jsfun }); //在名為winName的window中找到 //名為frmName的frame，并在該frame中執行jsfun腳本 var jsfun = 'funcGoto();'; api.execScript({ name: 'winName', frameName: 'frmName', script: jsfun }); //在當前window中找到 //名為frmName的frame，并在該frame中執行jsfun腳本 var jsfun = 'funcGoto();'; api.execScript({ frameName: 'frmName', script: jsfun }); ``` ### 補充說明 統一處理邏輯為：exec->window->frame name 參數： 當 name 不傳值，或者傳空字符串的情況下，execScript 對象為調用 execScript 的window（該 window 可能位于屏幕或者后臺），在該 window 中繼續 frameName 的邏輯； 當 name 傳值且非空字符串，但并未找到名為 name 的 window，則直接返回不處理（不論 frameName 是否有值）。若找到了對應的 window，則在該 window 中繼續 frameName 的邏輯； frameName 參數： 當 frameName 不傳值，或者傳空字符串的情況下，execScript 對象為調用 execScript 的 window（該 window 可能位于屏幕或者后臺），在該 window 中執行 script； 當 frameName 傳值且非空字符串，但并未找到名為 frameName 的 frame，則直接返回不處理。若找到了該 frame，則在該 frame 中執行 script。 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## historyBack 歷史記錄后退一頁 historyBack({params}, callback(ret, err)) ### params frameName： - 類型：字符串 - 默認值：無 - 描述：（可選項）frame 名稱，若不傳則表示對當前頁面進行操作 ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { status:true //后退是否成功，失敗時說明不能再后退了 } ``` ### 示例代碼 ```js api.historyBack({ frameName:'detail' },function(ret,err){ if(!ret.status){ api.closeWin(); } }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## historyForward 歷史記錄前進一頁 historyForward({params}, callback(ret, err)) ### params frameName： - 類型：字符串 - 默認值：無 - 描述：（可選項）frame 名稱，若不傳則表示對當前頁面進行操作 ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { status:true //前進是否成功，失敗時說明不能再前進了 } ``` ### 示例代碼 ```js api.historyForward({ frameName:'detail' },function(ret,err){ if(!ret.status){ } }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## pageUp 頁面向上滾動一頁 pageUp({params}, callback(ret, err)) ### params top： - 類型：布爾 - 默認值：false - 描述：（可選項）是否直接滾動到最頂部 ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { scrolled:true //是否滾動，為false時說明當前頁面已經到達頂部了 } ``` ### 示例代碼 ```js api.pageUp(function( ret, err ){ if(!ret.scrolled){ //已經滾動到頂部 } }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.1.0及更高版本 ## pageDown 頁面向下滾動一頁 pageDown({params}, callback(ret, err)) ### params bottom： - 類型：布爾 - 默認值：false - 描述：（可選項）是否直接滾動到最底部 ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { scrolled:true //是否滾動，為false時說明當前頁面已經到達底部了 } ``` ### 示例代碼 ```js api.pageDown(function( ret, err ){ if(!ret.scrolled){ //已經滾動到底部 } }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.1.0及更高版本 ## removeLaunchView 移除啟動圖。若 [config.xml](/APICloud/技術專題/app-config-manual) 里面配置 autoLaunch 為 false，則啟動圖不會自動消失，直到調用此方法移除。 removeLaunchView({params}) ### params animation： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）動畫參數，不傳時不使用動畫，type：[動畫類型](!Constant#b6)，subType：[動畫子類型](!Constant#b8)。 內部字段： ```js { type:"fade", //動畫類型（詳見動畫類型常量） subType:"from_right", //動畫子類型（詳見動畫子類型常量） duration:300 //動畫過渡時間，默認300毫秒 } ``` ### 示例代碼 ```js api.removeLaunchView({ animation: { type: 'fade', duration: 500 } }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## parseTapmode 解析元素 tapmode 屬性，優化點擊事件處理 默認頁面加載完成后，引擎會對 dom 里面的元素進行 tapmode 屬性解析，若是之后用代碼創建的 dom 元素，則需要調用該方法后 tapmode 屬性才會生效 parseTapmode() ### 示例代碼 ```js api.parseTapmode(); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## installApp 安裝應用 installApp({params}) ### params appUri： - 類型：字符串 - 默認值：無 - 描述：目標應用的資源文件標識。Android上為apk包的本地路徑，如file://xxx.apk；iOS上為應用安裝包對應的plist文件地址 ### 示例代碼 ```js //Android用法： api.installApp({ appUri: 'file://xxx.apk' }); //iOS用法： api.installApp({ appUri: 'https://list.kuaiapp.cn/list/KuaiAppZv7.1.plist' //安裝包對應plist地址 }); ``` ### 補充說明 安裝應用 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## openApp 打開手機上其它應用，并且可以傳遞參數 openApp({params}, callback(ret, err)) ### params appParam： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）傳給目標應用的參數。iOS 平臺會將 appParam 里面的值拼接到 iosUrl 后面，比如 iosUrl 為 http://www.baidu.com，appParam為{"keyword":"APICloud"}，則最后傳遞給第三方應用的url為http://www.baidu.com?keyword=APICloud iosUrl： - 類型：字符串 - 默認值：無 - 描述：（可選項）目標應用的url（iOS平臺使用），iOS下必傳 androidPkg： - 類型：字符串 - 默認值：無 - 描述：（可選項）目標應用的包名或 action（Android平臺使用），Android下必傳 mimeType： - 類型：字符串 - 默認值：無 - 描述：（可選項）指定目標應用的響應數據類型，如："text/html"（Android平臺使用） uri： - 類型：字符串 - 默認值：無 - 描述：（可選項）指定目標應用響應的uri（Android平臺使用） ### callback(ret, err) ret： - 類型：JSON 對象 - 描述：目標應用關閉后的返回值，只支持Android err： - 類型：JSON 對象 內部字段： ```js { msg:"" //錯誤描述 } ``` ### 示例代碼 ```js //iOS中的使用方法如下： api.openApp({ iosUrl: 'http://www.baidu.com', //例如調用系統瀏覽器Safari打開百度，其中http為Safari的URL Scheme；同理，微信的URL Scheme為weixin，因此可以通過傳weixin://來打開微信 appParam: { appParam: 'app參數' } }); //Android中的使用方法如下： api.openApp({ androidPkg: 'Android.intent.action.VIEW', mimeType: 'text/html', uri: 'http://www.baidu.com' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## appInstalled 判斷設備上面是否已安裝指定應用 appInstalled({params}, callback(ret, err)) ### params appBundle： - 類型：字符串 - 默認值：無 - 描述：Android 平臺為應用包名，iOS 平臺為應用定義的 URL Scheme。iOS 中的 URL Scheme 與包名不一樣，一個應用只有一個包名，但是可以配置多個 URL Scheme ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { installed:true //是否安裝，布爾類型 } ``` ### 示例代碼 ```js api.appInstalled({ appBundle: appBundle },function(ret, err){ if(ret.installed){ //應用已安裝 }else{ //應用未安裝 } }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## 重啟應用 重啟應用，云修復完成后可以調用此方法來重啟應用使云修復生效。 rebootApp() ### 示例代碼 ```js api.rebootApp(); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.2.0及更高版本 ## openWidget 打開 Widget，若此 widget 已經被打開，則會把其調整到最前面顯示 openWidget({params}, callback(ret, err)) ### params id： - 類型：字符串 - 默認值：無 - 描述：widget 的 ID wgtParam： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）widget 參數，在新打開的 widget 里面的頁面中通過 api.wgtParam 獲取 animation： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）動畫參數，不傳時使用默認動畫，type：[動畫類型](!Constant#b6)，subType：[動畫子類型](!Constant#b8)。 內部字段： ```js { type:"none", //動畫類型（詳見動畫類型常量） subType:"from_right", //動畫子類型（詳見動畫子類型常量） duration:300 //動畫過渡時間，默認300毫秒 } ``` ### callback(ret, err) ret： - 類型：JSON 對象 - 描述：新 widget 關閉時候的返回值 ### 示例代碼 ```js api.openWidget({ id: 'A00000001', animation: { type: 'flip', subType: 'from_bottom', duration: 500 } }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## closeWidget 關閉指定 widget closeWidget({params}) ### params id： - 類型：字符串 - 默認值：無 - 描述：（可選項）widget 的 ID retData： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）返回給上個 widget 的返回值 silent： - 類型：布爾型 - 默認值：false - 描述：（可選項）是否靜默退出應用，只在主 widget 中有效。當為 false 時，引擎會彈出對話框詢問是否退出應用 animation： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）動畫參數，不傳時使用默認動畫，type：[動畫類型](!Constant#b6)，subType：[動畫子類型](!Constant#b8)。 內部字段： ```js { type:"none", //動畫類型（詳見動畫類型常量） subType:"from_right", //動畫子類型（詳見動畫子類型常量） duration:300 //動畫過渡時間，默認300毫秒 } ``` ### 示例代碼 ```js api.closeWidget({ id: 'A00000001', retData: { name: 'closeWidget' }, animation: { type: 'flip', subType: 'from_bottom', duration: 500 } }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## ajax 跨域異步請求，支持文件上傳 ajax({params}, callback(ret, err)) ### params url： - 類型：字符串 - 默認值：無 - 描述：請求地址 tag： - 類型：字符串 - 默認值：無 - 描述：（可選項）請求標識，可以傳遞此字段給 cancelAjax 方法來取消請求 method： - 類型：字符串 - 默認值：get - 描述：（可選項）異步請求方法類型（詳見[異步請求方法類型](!Constant#b22)常量） cache： - 類型：布爾 - 默認值：false - 描述：（可選項）是否緩存，若緩存，下次沒網絡時請求則會使用緩存 timeout： - 類型：數字 - 默認值：30 - 描述：（可選項）超時時間，單位秒 dataType： - 類型：字符串 - 默認值：json - 描述：（可選項）返回數據類型（詳見[異步請求返回數據類型](!Constant#b22)常量） charset： - 類型：字符串 - 默認值：utf-8 - 描述：（可選項）當響應頭里面沒有返回字符集編碼時，使用此編碼來解析數據 headers： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）請求頭 report： - 類型：布爾 - 默認值：false - 描述：（可選項）是否實時返回上傳文件進度 returnAll： - 類型：布爾 - 默認值：false - 描述：（可選項）是否需要返回所有 response 信息，為 true 時，返回的頭信息獲取方法(ret.headers)，消息體信息獲取方法(ret.body)，狀態碼獲取方法(ret.statusCode) data： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）POST 數據，method 為 get 時不傳。以下字段除了 values 和 files 可以同時使用，其它參數都不能同時使用。 內部字段： ```js { stream："", //文件路徑（字符串類型） body："", //請求體（字符串類型）如: JSON.stringify({"name1": "value1", "name2": "value2"}) (將JSON對像轉為JSON字符串再賦值給body) values：{}, //以表單方式提交參數（JSON對象）, 如 {"field1": "value1", "field1": "value2"} (直接傳JSON對像.) files：{} //以表單方式提交文件，支持多文件上傳（JSON對象）,如 {"file": "path"}，也支持同一字段對應多文件：{"file":["path1","path2"]}。路徑支持絕對路徑，以及fs://、widget://、cache://等文件路徑協議. } ``` certificate： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）https 安全證書設置。 內部字段： ```js { path:'', //p12證書路徑，支持fs://、widget://、cache://等文件路徑協議，字符串類型 password:'' //證書密碼，字符串類型 } ``` ### callback(ret, err) ret： - 類型：JSON 對象或字符串 - 描述：類型依賴于傳入的 dataType 和 returnAll 返回上傳進度時，原服務器返回數據會被放在body字段里面，內部字段為： ```js { progress: 100, //上傳進度，0.00-100.00 status: '', //上傳狀態，詳見上傳狀態常量 body: '' //上傳完成時，服務器返回的數據 } ``` err： - 類型：JSON 對象 內部字段： ```js { statusCode: 400, //網絡請求狀態碼，數字類型 code:0, //錯誤碼（詳見異步請求錯誤碼常量），數字類型 msg:'' //錯誤描述，字符串類型 body: //當請求失敗如需要權限時，此時服務器返回的數據會通過該參數返回；當要求返回的數據格式為json，而返回的數據不是json格式時，數據通過該參數返回 } ``` ### 示例代碼 ```js api.ajax({ url: 'http://192.168.1.101:3101/upLoad', method: 'post', data: { values: { name: 'haha' }, files: { file: 'fs://a.gif' } } },function(ret, err){ if (ret) { api.alert({msg:JSON.stringify(ret)}); } else { api.alert({msg:JSON.stringify(err)}); } }); ``` ### 補充說明 異步請求q ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## cancelAjax 取消異步請求 cancelAjax({params}) ### params tag： - 類型：字符串 - 默認值：無 - 描述：請求標識 ### 示例代碼 ```js api.cancelAjax({ tag: 'publish' }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.1.0及更高版本 ## download 下載文件 download({params}, callback(ret, err)) ### params url： - 類型：字符串 - 默認值：無 - 描述：下載地址 savePath： - 類型：字符串 - 默認值：無 - 描述：（可選項）存儲路徑，不傳時使用自動創建的路徑 report： - 類型：布爾類型 - 默認值：false - 描述：（可選項）下載過程是否上報 cache： - 類型：布爾類型 - 默認值：true - 描述：（可選項）是否使用本地緩存 allowResume： - 類型：布爾類型 - 默認值：false - 描述：（可選項）是否允許斷點續傳 ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { fileSize:0, //文件大小，數字類型 percent:0, //下載進度（0-100），數字類型 state:0, //下載狀態（詳見下載狀態常量） savePath:'' //存儲路徑（字符串類型） } ``` err： - 類型：JSON 對象 內部字段： ```js { msg:"" //錯誤描述 } ``` ### 示例代碼 ```js api.download({ url: url, savePath: 'fs://test.rar', report: true, cache: true, allowResume: true },function(ret, err){ if(ret.state == 1){ //下載成功 }else{ } }); ``` ### 補充說明 通過返回的 state 來判斷文件是否下載完成，不要通過 percent 來判斷 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## cancelDownload 取消文件下載 cancelDownload({params}) ### params url： - 類型：字符串 - 默認值：無 - 描述：下載地址 ### 示例代碼 ```js api.cancelDownload({ url: url }); ``` ### 補充說明 取消文件下載 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## imageCache 圖片緩存 imageCache({params}, callback(ret, err)) ### params url： - 類型：字符串 - 默認值：無 - 描述：圖片遠程地址 policy： - 類型：字符串 - 默認值：default - 描述：（可選項）緩存策略（詳見[緩存策略](!Constant#b27)常量） thumbnail： - 類型：布爾類型 - 默認值：true - 描述：（可選項）使用縮略圖，底層將根據當前系統及設備性能，返回最優的縮略圖，有利于提高應用運行及渲染效率 ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { status:true, //是否成功，布爾類型 url:'' //圖片本地存儲路徑，若下載失敗，則返回傳入的url，字符串類型 } ``` ### 示例代碼 ```js api.imageCache({ url: 'http://a.hiphotos.baidu.com/image/w%3D400/sign=2abe1c77d4ca7bcb7d7bc62f8e086b3f/64380cd7912397ddf9f4bdb05a82b2b7d1a287f0.jpg' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.1.0及更高版本 ## readFile 讀取文本文件內容，只支持utf-8編碼文本類型文件 readFile({params}, callback(ret, err)) ### params path： - 類型：字符串 - 默認值：無 - 描述：文件路徑，支持絕對路徑和文件路徑協議如fs://、widget://等 ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { status:true, //操作成功狀態值 data:"" //文件內容，字符串類型 } ``` err： - 類型：JSON 對象 內部字段： ```js { code:0, //錯誤碼（詳見文件操作錯誤碼常量） msg:"" //錯誤描述 } ``` ### 示例代碼 ```js api.readFile({ path: 'fs://a.txt' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ } }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## writeFile 寫入內容到文本文件 writeFile({params}, callback(ret, err)) ### params path： - 類型：字符串 - 默認值：無 - 描述：文件路徑，支持絕對路徑和文件路徑協議如fs://、cache://等，不支持widget://目錄，該目錄只讀 data： - 類型：字符串 - 默認值：無 - 描述：文件內容 append： - 類型：布爾 - 默認值：false - 描述：是否以追加方式寫入數據，默認會清除之前文件內容 ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { status:true //操作成功狀態值 } ``` err： - 類型：JSON 對象 內部字段： ```js { code:0, //錯誤碼（詳見文件操作錯誤碼常量） msg:"" //錯誤描述 } ``` ### 示例代碼 ```js api.writeFile({ path: 'fs://a.txt', data: 'writeFile測試內容' }, function(ret, err){ if(ret.status){ //成功 }else{ } }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## setPrefs 設置偏好數據 setPrefs({params}) ### params key： - 類型：字符串 - 默認值：無 - 描述：鍵 value： - 類型：字符串 - 默認值：無 - 描述：值 ### 示例代碼 ```js api.setPrefs({ key: 'k', value: '1' }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## getPrefs 獲取偏好設置值 getPrefs({params}, callback(ret, err)) ### params key： - 類型：字符串 - 默認值：無 - 描述：鍵 ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { value:"" //值 } ``` ### 示例代碼 ```js api.getPrefs({ key: 'k' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 補充說明 獲取偏好設置值 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## removePrefs 刪除偏好設置值 removePrefs({params}) ### params key： - 類型：字符串 - 默認值：無 - 描述：鍵 ### 示例代碼 ```js api.removePrefs({ key: 'k' }); ``` ### 補充說明 刪除偏好設置值 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## clearCache 清除緩存，包括下載的文件、拍照臨時文件、網頁緩存文件等，清除時可能需要消耗一定時間。 clearCache({params}, callback(ret, err)) ### params timeThreshold： - 類型：數字 - 默認值：0 - 描述：（可選項）清除多少天前的緩存 ### callback(ret, err) - 描述：清除完成后的回調 ### 示例代碼 ```js api.clearCache(function(){ api.toast({ msg:'清除完成' }); }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## getCacheSize 獲取緩存占用空間大小，緩存包括下載的緩存文件、拍照臨時文件以及網頁緩存文件等，計算可能需要花費一些時間 getCacheSize(callback(ret, err)) ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { size: //緩存大小，單位為Byte，數字類型。（-1：無存儲設備、-2：正在準備USB存儲設備、-3：無法訪問存儲設備） } ``` ### 示例代碼 ```js api.getCacheSize(function(ret){ var size = ret.size; }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.1.0及更高版本 ## getFreeDiskSpace 獲取剩余存儲空間大小 getFreeDiskSpace(callback(ret, err)) ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { size: //剩余存儲空間大小，單位為Byte，數字類型。（-1：無存儲設備、-2：正在準備USB存儲設備、-3：無法訪問存儲設備） } ``` ### 示例代碼 ```js api.getFreeDiskSpace(function( ret, err ){ var size = ret.size; }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.1.0及更高版本 ## loadSecureValue 從加密的key.xml文件中讀取指定數據，key.xml文件放置于網頁包里面的res目錄，配置方式： ```js <?xml version="1.0" encoding="UTF-8"?> <security> <item name="appKey" value="1111111"/> </security> ``` loadSecureValue({params}, callback(ret, err)) ### params key： - 類型：字符串 - 默認值：無 - 描述：鍵 ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { value:"" //值 } ``` ### 示例代碼 ```js api.loadSecureValue({ key:'appKey' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## addEventListener 監聽事件，支持系統事件和自定義事件 addEventListener({params}, callback(ret, err)) ### params name： - 類型：字符串 - 默認值：無 - 描述：自定義事件或系統事件名稱（詳見[事件](!Event)） extra： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）附加字段。一些特定事件可能需要提供額外的參數。 內部字段： ```js { threshold: //當事件為scrolltobottom時，設置距離底部多少距離時觸發事件，默認值為0，數字類型 } ``` ### callback(ret, err) ret： - 類型：JSON 對象 - 描述：事件發生時傳遞的參數，可能為空 ### 示例代碼 ```js //如監聽網絡連接事件 api.addEventListener({ name: 'online' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 補充說明 監聽事件 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## removeEventListener 移除事件監聽 removeEventListener({params}) ### params name： - 類型：字符串 - 默認值：無 - 描述：自定義事件或系統事件名稱（詳見[事件](!Event)） ### 示例代碼 ```js api.removeEventListener({ name: 'online' }); ``` ### 補充說明 停止監聽事件 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## sendEvent 將任意一個自定義事件廣播出去，該事件可在任意頁面通過 addEventListener 監聽收到。 sendEvent({params}) ### params name - 類型：字符串 - 默認值：無 - 描述：任意自定義事件的名稱，比如：apprunning、appover等 extra - 類型：字符串或 JSON 對象 - 默認值：無 - 描述：（可選項）附帶的參數。在監聽頁面的回調里面通過 ret.value 獲取。 ### 示例代碼 ```js api.sendEvent({ name: 'myEvent', extra: { key1: 'value1', key2: 'value2' } }); //html頁面a： api.addEventListener({ name: 'myEvent' }, function(ret, err){ alert(JSON.stringify(ret.value)); }); //html頁面b： api.addEventListener({ name: 'myEvent' }, function(ret, err){ alert(JSON.stringify(ret.value)); }); //a、b頁面都將收到 myEvent 事件 ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## accessNative 使用 SuperWebView 時，js 向原生發送消息。此方法只在使用 SuperWebView 時有效。 accessNative({params}, callback(ret, err)) ### params name - 類型：字符串 - 默認值：無 - 描述：消息名稱。 extra - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）附帶的參數。 ### callback(ret, err) ret： - 類型：JSON 對象 err： - 類型：JSON 對象 ### 示例代碼 ```js api.accessNative({ name: 'showMenu', extra: { key: 'value' } }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.2.0及更高版本 ## notification 向用戶發出震動、聲音提示、燈光閃爍、狀態欄消息等通知，以及鬧鐘功能 狀態欄消息點擊后，頁面可以通過監聽 noticeclicked 事件得到內容 notification({params}, callback(ret, err)) ### params vibrate： - 類型：數組 - 默認值：[500,500] - 描述：（可選項）伴隨節奏的震動，時間數組，時間單位為毫秒，iOS上面震動時間為固定值 sound： - 類型：字符串 - 默認值：default - 描述：（可選項）提示音，默認為系統提示音。當實現鬧鐘功能時，iOS只支持widget://路徑協議 light： - 類型：布爾型 - 默認值：false - 描述：（可選項）設備提示燈是否閃爍 notify： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）彈出通知到狀態欄 內部字段： ```js { title:'' //標題，默認值為應用名稱，只Android有效 content:'' //內容，默認值為'有新消息' extra:'' //傳遞給通知的數據，在通知被點擊后，該數據將通過監聽函數回調給網頁 updateCurrent: false //是否覆蓋更新已有的通知，取值范圍true|false。只Android有效 } ``` alarm： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）如果本次通知設置了鬧鈴，那么該通知將在設定的鬧鈴時間彈出 內部字段： ```js { hour: //小時，數字類型，取值范圍（0-23），默認值為當前系統時 minutes: //分鐘，數字類型，取值范圍（0-59），默認值為當前系統分 daysOfWeek: //通知循環時間，以周為單位，數組類型，如[1,2,3,4,5,6,7]代表周日、周一、周二、周三、周四、周五、周六。若不傳則不循環，只在當天或隔天的指定時間通知一次 time: //鬧鈴目標時間，數字類型，1970年至今的毫秒數，只在設定的時間執行一次，若設置了time，那么hour、minutes、daysOfWeek將被忽略 } ``` ### callback(ret, err) 如果 notification 時傳入了 notify，那么將收到 callback，返回本次狀態欄通知的 id，該 id 可用于取消狀態欄通知。 ret： - 類型：JSON 對象 內部字段： ```js { id:1 //彈出到狀態欄通知的id，可用于取消通知 } ``` ### 示例代碼 ```js api.notification({ notify: { content: '鬧鐘' }, alarm: { hour: 7, minutes: 30, daysOfWeek: [2,3,4,5,6] } }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## cancelNotification 取消本應用彈出到狀態欄的某個或所有通知，也可以清除設定的鬧鈴 cancelNotification({params}) ### params id： - 類型：字符串 - 默認值：0。如果傳入-1，則取消本應用彈到狀態欄的所有通知，iOS只支持清除所有彈到狀態欄的通知。 - 描述：（可選項）調用 notification 方法時返回的 id ### 示例代碼 ```js api.cancelNotification({ id: 1 }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## startLocation 調用系統自帶定位功能，開始定位 startLocation({params}, callback(ret, err)) ### params accuracy： - 類型：字符串 - 默認值：100m - 描述：（可選項）定位精度（詳見[定位精度](!Constant#b5)常量） filter： - 類型：數字 - 默認值：1.0 - 描述：（可選項）位置更新所需最小距離（單位米） autoStop： - 類型：布爾 - 默認值：true - 描述：（可選項）獲取到位置信息后是否自動停止定位 ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { longitude:116.213, //經度 latitude:39.213, //緯度 timestamp:1396068155591, //時間戳 status: true //定位成功 } ``` err： - 類型：JSON 對象 內部字段： ```js { msg:"" //錯誤描述 } ``` ### 示例代碼 ```js api.startLocation({ accuracy: '100m', filter: 1, autoStop: true }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ //定位失敗 } }); ``` ### 補充說明 本API使用系統自身定位能力進行定位。 Android 上使用的是 Google 的定位服務，因法規政策的原因，在中國基本無法提供服務，因此建議國內開發者使用百度定位模塊（baiduLocation）進行定位操作。 iOS上使用的是蘋果的定位服務，不受影響。 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## stopLocation 停止定位 stopLocation() ### 示例代碼 ```js api.stopLocation(); ``` ### 補充說明 停止定位 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## getLocation 獲取位置信息，獲取成功后自動停止獲取。 若之前已通過 startLocation() 方法進行定位，則直接返回上次定位的數據，否則使用默認設置進行定位 getLocation(callback(ret, err)) ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { longitude:116.213, //經度 latitude:39.213, //緯度 timestamp:1396068155591, //時間戳 status:true //定位成功 } ``` err： - 類型：JSON 對象 內部字段： ```js { msg:"" //錯誤描述 } ``` ### 示例代碼 ```js api.getLocation(function(ret, err){ if(ret.status){ //獲取位置信息成功 }else{ alert( JSON.stringify( err ) ); } }); ``` ### 補充說明 本API使用系統自身定位能力進行定位。 Android 上使用的是 Google 的定位服務，因法規政策的原因，在中國基本無法提供服務，因此建議國內開發者使用百度定位模塊（baiduLocation）進行定位操作。 IOS上使用的是蘋果的定位服務，不受影響。 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## startSensor 開啟傳感器 startSensor({params}, callback(ret, err)) ### params type： - 類型：字符串 - 默認值：無 - 描述：傳感器類型（詳見[傳感器類型](!Constant#b2)常量） ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { x:0, //x軸分量值 y:0, //y軸分量值 z:0, //z軸分量值 proximity:true, //是否接近設備 status:true //操作成功狀態值 } ``` err： - 類型：JSON 對象 內部字段： ```js { msg:"" //錯誤描述 } ``` ### 示例代碼 ```js api.startSensor({ type: 'accelerometer' }, function(ret, err){ if(ret.status){ }else{ } }); ``` ### 補充說明 開啟傳感器 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## stopSensor 停止傳感器 stopSensor({params}) ### params type： - 類型：字符串 - 默認值：無 - 描述：傳感器類型（詳見[傳感器類型](!Constant#b2)常量） ### 示例代碼 ```js api.stopSensor({ type: 'accelerometer' }); ``` ### 補充說明 停止傳感器 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## call 撥打電話或進行faceTime call({params}) ### params type： - 類型：字符串 - 默認值：tel_prompt - 描述：（可選項）打電話類型（詳見[電話類型](!Constant#b4)常量） number： - 類型：字符串 - 默認值：無 - 描述：電話號碼 ### 示例代碼 ```js api.call({ type: 'tel_prompt', number: '10086' }); ``` ### 補充說明 撥打電話，需要設備有電話功能 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## sms 調用系統短信界面發送短信，或者后臺直接發送短信 sms({params}, callback(ret, err)) ### params numbers： - 類型：字符串數組 - 默認值：無 - 描述：電話號碼 - 備注：當調用系統短信界面進行短信發送時，僅支持傳入一個號碼，且發送是否成功的狀態值依賴于系統短信界面的返回值 text： - 類型：字符串 - 默認值：無 - 描述：文本內容 silent： - 類型：布爾型 - 默認值：false - 描述：（可選項）是否后臺發送，iOS不支持 - 備注：后臺發送時，numbers 支持多個，可同時將一條信息發送給多個號碼 ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { status:true //發送狀態 } ``` ### 示例代碼 ```js api.sms({ numbers: ['10086'], text: '測試短信' },function(ret, err){ if(ret.status){ //已發送 }else{ //發送失敗 } }); ``` ### 補充說明 發送短信，需要設備有短信功能 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## mail 發送郵件 mail({params}, callback(ret, err)) ### params recipients： - 類型：字符串數組 - 默認值：無 - 描述：收件人 subject： - 類型：字符串 - 默認值：無 - 描述：郵件主題 body： - 類型：字符串 - 默認值：無 - 描述：（可選項）郵件內容 attachments： - 類型：數組 - 默認值：無 - 描述：（可選項）附件地址 ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { status:true //發送狀態 } ``` ### 示例代碼 ```js api.mail({ recipients: ['test@163.com'], subject: '郵件測試', body: '這是一封測試用的郵件', attachments: ['widget://a.txt'] }, function(ret, err){ if(ret.status){ //已發送 }else{ } }); ``` ### 補充說明 需要在手機上面已經配置好郵件賬戶 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## openContacts 在應用內打開系統通訊錄界面選擇聯系人 openContacts(callback(ret, err)) ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { status:true, //操作成功狀態值 name:"", //姓名 phone:"" //電話號碼 } ``` err： - 類型：JSON 對象 內部字段： ```js { msg:"" //錯誤描述 } ``` ### 示例代碼 ```js api.openContacts(function(ret, err){ if(ret.status){ var name = ret.name; var phone = ret.phone; }else{ } }); ``` ### 補充說明 打開通訊錄界面 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## setFullScreen 設置是否全屏 setFullScreen({params}) ### params fullScreen： - 類型：布爾 - 默認值：無 - 描述：是否全屏 ### 示例代碼 ```js api.setFullScreen({ fullScreen: true }); ``` ### 補充說明 設置是否全屏 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## setStatusBarStyle 設置狀態欄樣式為白色（適用于深色背景）或黑色（適用于淺色背景），以及設置狀態欄背景顏色 setStatusBarStyle({params}) ### params style： - 類型：字符串 - 默認值：無 - 描述：（可選項）狀態欄樣式（詳見[狀態欄樣式](!Constant#b23)常量），只支持iOS color： - 類型：字符串 - 默認值：#000 - 描述：（可選項）狀態欄背景顏色，只 Android 5.0 及以上有效 ### 示例代碼 ```js api.setStatusBarStyle({ style: 'light' }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## setScreenOrientation 設置屏幕旋轉方向 setScreenOrientation({params}) ### params orientation： - 類型：字符串 - 默認值：無 - 描述：旋轉屏幕到指定方向，或根據重力感應自動旋轉；當前為橫屏時，若想只在橫屏間根據重力切換，則可以傳 auto_landscape，豎屏間切換則傳 auto_portrait。詳見[屏幕旋轉方向](!Constant#b24)常量 ### 示例代碼 ```js api.setScreenOrientation({ orientation: 'landscape_left' }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## setKeepScreenOn 設置是否禁止屏幕休眠 setKeepScreenOn({params}) ### params keepOn - 類型：布爾 - 默認值：無 - 描述：是否禁止屏幕休眠 ### 示例代碼 ```js api.setKeepScreenOn({ keepOn: true }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## toLauncher 回到系統桌面 toLauncher() ### 示例代碼 ```js api.toLauncher(); ``` ### 補充說明 該接口僅Android平臺支持。 ### 可用性 Android系統 可提供的1.0.0及更高版本 ## setScreenSecure 設置是否禁止截屏，只支持Android setScreenSecure({params}) ### params secure - 類型：布爾 - 默認值：無 - 描述：是否禁止截屏 ### 示例代碼 ```js api.setScreenSecure({ secure: true }); ``` ### 補充說明 無 ### 可用性 Android系統 可提供的1.1.0及更高版本 ## setAppIconBadge 設置應用圖標右上角數字，支持所有 iOS 手機，以及部分 Android 手機，如小米和三星的某些型號，不支持的設備，表現結果為調用該接口無任何效果 setAppIconBadge({params}) ### params badge - 類型：數字 - 默認值：無 - 描述：顯示在應用圖標右上角的數字。為0時表示清除應用圖標上顯示的數字 ### 示例代碼 ```js api.setAppIconBadge({ badge: 1 }); ``` ### 補充說明 無 ### 可用性 iOS系統 可提供的1.1.0及更高版本 ## getPhoneNumber 獲取本機電話號碼，只支持 Android 部分手機 getPhoneNumber(callback(ret, err)) ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { value:"" //電話號碼，字符串類型 } ``` ### 示例代碼 ```js api.getPhoneNumber(function( ret, err ){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 補充說明 無 ### 可用性 Android系統 可提供的1.2.0及更高版本 ## alert 彈出帶一個按鈕的對話框，更多按鈕的對話框請使用confirm方法 alert({params}, callback(ret, err)) ### params title： - 類型：字符串 - 默認值：無 - 描述：（可選項）標題 msg： - 類型：字符串 - 默認值：無 - 描述：（可選項）內容 buttons： - 類型：數組 - 默認值：["確定"] - 描述：（可選項）按鈕 ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { buttonIndex:1 //按鈕點擊序號，從1開始 } ``` ### 示例代碼 ```js api.alert({ title: 'testtitle', msg: 'testmsg', }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 補充說明 對話框 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## confirm 彈出帶兩個或三個按鈕的confirm對話框 confirm({params}, callback(ret, err)) ### params title： - 類型：字符串 - 默認值：無 - 描述：（可選項）標題 msg： - 類型：字符串 - 默認值：無 - 描述：（可選項）內容 buttons： - 類型：數組 - 默認值：["取消","確定"] - 描述：（可選項）按鈕標題，若小于兩個按鈕，會補齊兩個按鈕；若大于三個按鈕，則使用前三個按鈕 ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { buttonIndex:1 //按鈕點擊序號，從1開始 } ``` ### 示例代碼 ```js api.confirm({ title: 'testtitle', msg: 'testmsg', buttons: ['確定', '取消'] }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 補充說明 多個按鈕的對話框 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## prompt 彈出帶兩個或三個按鈕和輸入框的對話框 prompt({params}, callback(ret, err)) ### params title： - 類型：字符串 - 默認值：無 - 描述：（可選項）標題 msg： - 類型：字符串 - 默認值：無 - 描述：（可選項）內容 text： - 類型：字符串 - 默認值：無 - 描述：（可選項）輸入框里面的默認內容 type： - 類型：字符串 - 默認值：text - 描述：（可選項）輸入類型，不同輸入類型彈出鍵盤類型不同，取值范圍（text、password、number、email、url） buttons： - 類型：數組 - 默認值：["取消","確定"] - 描述：（可選項）按鈕標題，若小于兩個按鈕，會補齊兩個按鈕；若大于三個按鈕，則使用前三個按鈕 ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { buttonIndex:1, //按鈕點擊序號，從1開始 text:"" //輸入文字 } ``` ### 示例代碼 ```js api.prompt({ buttons: ['確定', '取消'] }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 補充說明 帶輸入框的對話框 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## actionSheet 底部彈出框 ```js actionSheet({params}, callback(ret, err)) ``` ### params title： - 類型：字符串 - 默認值：無 - 描述：（可選項）標題 cancelTitle： - 類型：字符串 - 默認值：取消 - 描述：（可選項）取消按鈕標題 destructiveTitle： - 類型：字符串 - 默認值：無 - 描述：（可選項）紅色警示按鈕標題，一般用于做一些刪除之類操作 buttons： - 類型：數組 - 默認值：無 - 描述：（可選項）其它按鈕 style： - 類型：JSON 對象 - 默認值：無 - 描述：（可選項）樣式設置，不傳時使用默認樣式 內部字段： ```js { layerColor:'', //遮蔽層顏色，僅支持 rgba顏色，默認值：rgba（0, 0, 0, 0.4） itemNormalColor:'', //選項按鈕正常狀態背景顏色，支持#000、#000000、rgb、rgba，默認值：#F1F1F1 itemPressColor:'', //選項按鈕按下時背景顏色，支持#000、#000000、rgb、rgba，默認值：#E6E6E6 fontNormalColor:'', //選項按鈕正常狀態文字顏色，支持#000、#000000、rgb、rgba，默認值：#007AFF fontPressColor:'', //選項按鈕按下時文字顏色，支持#000、#000000、rgb、rgba，默認值：#0060F0 titleFontColor:'' //標題文字顏色，支持#000、#000000、rgb、rgba，默認值：#8F8F8F } ``` ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { buttonIndex:1 //按鈕點擊序號，從1開始 } ``` ### 示例代碼 ```js api.actionSheet({ title: '底部彈出框測試', cancelTitle: '這里是取消按鈕', destructiveTitle: '紅色警告按鈕', buttons: ['1','2','3'] }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 補充說明 底部彈出框 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## showProgress 顯示進度提示框 showProgress({params}) ### params style： - 類型：字符串 - 默認值：default - 描述：（可選項）進度提示框風格（詳見[進度提示框風格](!Constant#b10)常量） animationType： - 類型：字符串 - 默認值：fade - 描述：（可選項）進度提示框動畫類型（詳見[進度提示框動畫類型](!Constant#b9)常量） title： - 類型：字符串 - 默認值：加載中 - 描述：（可選項）標題 text： - 類型：字符串 - 默認值：請稍后... - 描述：（可選項）內容 modal： - 類型：布爾 - 默認值：true - 描述：（可選項）是否模態，模態時整個頁面將不可交互 ### 示例代碼 ```js api.showProgress({ style: 'default', animationType: 'fade', title: '努力加載中...', text: '先喝杯茶...', modal: false }); ``` ### 補充說明 顯示進度提示框 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## hideProgress 隱藏進度提示框 hideProgress() ### 示例代碼 ```js api.hideProgress(); ``` ### 補充說明 隱藏進度提示框 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## toast 彈出一個定時自動關閉的提示框 toast({params}) ### params msg： - 類型：字符串 - 默認值：無 - 描述：提示消息 duration： - 類型：字符串 - 默認值：2000 - 描述：（可選項）持續時長，單位：毫秒 location： - 類型：字符串 - 默認值：bottom - 描述：（可選項）彈出位置，頂部、中間或底部（詳見[toast位置](!Constant#b1)常量） ### 示例代碼 ```js api.toast({ msg: '網絡錯誤', duration: 2000, location: 'bottom' }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## openPicker 打開時間選擇器 openPicker({params}, callback(ret, err)) ### params type： - 類型：字符串 - 默認值：無 - 描述：拾取器類型（詳見[拾取器類型](!Constant#b12)常量） date： - 類型：字符串 - 默認值：當前時間 - 描述：（可選項）時間格式化字符串，格式yyyy-MM-dd HH:mm title： - 類型：字符串 - 默認值：無 - 描述：（可選項）顯示在拾取器上面的標題 ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { year:2000, //年 month:1, //月 day:1, //日 hour:12, //時 minute:00 //分 } ``` ### 示例代碼 ```js api.openPicker({ type: 'date_time', date: '2014-05-01 12:30', title: '選擇時間' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 補充說明 時間選擇器 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## setRefreshHeaderInfo 顯示頂部下拉刷新組件，頁面必須設置為彈動。 setRefreshHeaderInfo({params}, callback(ret, err)) ### params visible： - 類型：布爾 - 默認值：true - 描述：（可選項）是否可見 loadingImg： - 類型：字符串 - 默認值：旋轉箭頭圖片 - 描述：（可選項）上拉下拉時的圖片地址 bgColor： - 類型：字符串 - 默認值：rgba(187, 236, 153, 1.0) - 描述：（可選項）背景顏色 textColor： - 類型：字符串 - 默認值：rgba(109, 128, 153, 1.0) - 描述：（可選項）文本顏色 textDown： - 類型：字符串 - 默認值：下拉可以刷新... - 描述：（可選項）下拉文字描述 textUp： - 類型：字符串 - 默認值：松開可以刷新... - 描述：（可選項）松開時文字描述 textLoading： - 類型：字符串 - 默認值：加載中... - 描述：（可選項）加載狀態文字描述 textTime： - 類型：字符串 - 默認值：最后更新加日期時間 - 描述：（可選項）更新時間文字描述 showTime： - 類型：布爾 - 默認值：true - 描述：（可選項）是否顯示更新時間 ### callback(ret, err) ret： - 描述：可以為空 err： - 描述：可以為空 ### 示例代碼 ```js api.setRefreshHeaderInfo({ visible: true, loadingImg: 'widget://image/refresh.png', bgColor: '#ccc', textColor: '#fff', textDown: '下拉刷新...', textUp: '松開刷新...', showTime: true }, function(ret, err){ //在這里從服務器加載數據，加載完成后調用api.refreshHeaderLoadDone()方法恢復組件到默認狀態 }); ``` ### 補充說明 下拉刷新 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## setCustomRefreshHeaderInfo 顯示頂部自定義下拉刷新組件，頁面必須設置為彈動。 可以在[config.xml](/APICloud/技術專題/app-config-manual)里面配置要使用的自定義下拉刷新模塊名稱，如： ```js <preference name="customRefreshHeader" value="UIPullRefresh"/> ``` 或者在使用openWin、openFrame等方法打開頁面時傳入customRefreshHeader參數來指定。 setCustomRefreshHeaderInfo({params}, callback(ret, err)) ### params 由對應的自定義下拉刷新模塊提供 ### callback(ret, err) 由對應的自定義下拉刷新模塊提供 ### 示例代碼 ```js api.setCustomRefreshHeaderInfo({ bgColor: '#C0C0C0', images: { pull: 'widget://image/refresh/pulling.png', transform: [ 'widget://image/refresh/transform0.png', 'widget://image/refresh/transform1.png', 'widget://image/refresh/transform2.png', 'widget://image/refresh/transform3.png', 'widget://image/refresh/transform4.png', 'widget://image/refresh/transform5.png', 'widget://image/refresh/transform6.png' ], load: [ 'widget://image/refresh/loading0.png', 'widget://image/refresh/loading1.png', 'widget://image/refresh/loading2.png', 'widget://image/refresh/loading3.png', 'widget://image/refresh/loading4.png', ] } }, function(ret, err){ //在這里從服務器加載數據，加載完成后調用api.refreshHeaderLoadDone()方法恢復組件到默認狀態 }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.2.0及更高版本 ## refreshHeaderLoading 設置下拉刷新組件為刷新中狀態 refreshHeaderLoading() ### 示例代碼 ```js api.refreshHeaderLoading(); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.1.0及更高版本 ## refreshHeaderLoadDone 通知頂部下拉刷新數據加載完畢，組件會恢復到默認狀態 refreshHeaderLoadDone() ### 示例代碼 ```js api.refreshHeaderLoadDone(); ``` ### 補充說明 通知頂部刷新數據加載完畢 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## showFloatBox 展示一個懸浮框，浮動在屏幕上，點擊時關閉當前widget showFloatBox({params}) ### params iconPath： - 類型：字符串 - 默認值：應用圖標 - 描述：（可選項）展示在懸浮框中的圖片地址 duration： - 類型：字符串 - 默認值：5000毫秒 - 描述：（可選項）自動消隱時長。在該時長內不發生觸摸懸浮框行為，懸浮框自動消隱至半透狀態 ### 示例代碼 ```js api.showFloatBox({ iconPath: 'widget://image/icon.png', duration: 3000 }); ``` ### 補充說明 對主widget無效 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## getPicture 通過系統相冊或拍照獲取圖片和視頻 getPicture({params}, callback(ret, err)) ### params sourceType： - 類型：字符串 - 默認值：library - 描述：（可選項）圖片源類型，從相冊、圖片庫或相機獲取圖片（詳見[圖片源類型](!Constant#b15)常量） encodingType： - 類型：字符串 - 默認值：png - 描述：（可選項）返回圖片類型，jpg或png（詳見[圖片編碼類型](!Constant#b13)常量） mediaValue： - 類型：字符串 - 默認值：pic - 描述：（可選項）媒體類型，圖片或視頻（詳見[媒體類型](!Constant#b11)常量） destinationType： - 類型：字符串 - 默認值：url - 描述：（可選項）返回數據類型，指定返回圖片地址或圖片經過base64編碼后的字符串（詳見[圖片數據格式](!Constant#b14)常量） allowEdit： - 類型：布爾 - 默認值：false - 描述：（可選項）是否可以選擇圖片后進行編輯，支持iOS及部分安卓手機 quality： - 類型：數字 - 默認值：50 - 描述：（可選項）圖片質量，只針對jpg格式圖片（0-100整數） videoQuality： - 類型：字符串 - 默認值：medium - 描述：（可選項）視頻質量，取值范圍(low、medium、high)，只支持iOS targetWidth： - 類型：數字 - 默認值：原圖寬度 - 描述：（可選項）壓縮后的圖片寬度，圖片會按比例適配此寬度 targetHeight： - 類型：數字 - 默認值：原圖高度 - 描述：（可選項）壓縮后的圖片高度，圖片會按比例適配此高度 saveToPhotoAlbum： - 類型：布爾 - 默認值：false - 描述：（可選項）拍照或錄制視頻后是否保存到相冊 ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { data:"", //圖片路徑 base64Data:"", //base64數據，destinationType為base64時返回 duration:0 //視頻時長（數字類型） } ``` err： - 類型：JSON 對象 內部字段： ```js { msg:"" //錯誤描述 } ``` ### 示例代碼 ```js api.getPicture({ sourceType: 'camera', encodingType: 'jpg', mediaValue: 'pic', destinationType: 'url', allowEdit: true, quality: 50, targetWidth: 100, targetHeight: 100, saveToPhotoAlbum: false }, function(ret, err){ if(ret){ alert(JSON.stringify(ret)); }else{ alert(JSON.stringify(err)); } }); ``` ### 補充說明 獲取圖片 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## saveMediaToAlbum 保存圖片和視頻到系統相冊 saveMediaToAlbum({params}, callback(ret, err)) ### params path： - 類型：字符串 - 默認值：無 - 描述：本地文件路徑，支持fs://、widget://等文件路徑協議，必須帶有擴展名 ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { status:true //是否保存成功 } ``` err： - 類型：JSON 對象 內部字段： ```js { msg:"" //錯誤描述 } ``` ### 示例代碼 ```js api.saveMediaToAlbum({ path: 'fs://1.png' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 補充說明 無 ### 可用性 iOS系統，Android系統 可提供的1.1.0及更高版本 ## startRecord 錄制amr格式音頻 startRecord({params}) ### params path： - 類型：字符串 - 默認值：無 - 描述：（可選項）文件路徑，不傳時自動創建路徑 ### 示例代碼 ```js api.startRecord({ path: 'fs://a.amr' }); ``` ### 補充說明 錄音格式為amr ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## stopRecord 停止錄音 stopRecord(callback(ret, err)) ### callback(ret, err) ret： - 類型：JSON 對象 內部字段： ```js { path:'', //字符串，返回的音頻地址 duration:0 //數字類型，音頻的時長 } ``` ### 示例代碼 ```js api.stopRecord(function(ret, err){ if(ret){ var path = ret.path; var duration = ret.duration; } }); ``` ### 補充說明 停止錄音 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## startPlay 開始播放音頻 startPlay({params}, callback(ret, err)) ### params path： - 類型：字符串 - 默認值：無 - 描述：文件路徑，支持fs://、widget://等文件路徑協議 ### callback(ret, err) 播放完成的回調 ### 示例代碼 ```js api.startPlay({ path: 'widget://res/1.mp3' }, function(ret, err){ if( ret ){ alert( JSON.stringify( ret ) ); }else{ alert( JSON.stringify( err ) ); } }); ``` ### 補充說明 播放音頻 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## stopPlay 停止播放音頻 stopPlay() ### 示例代碼 ```js api.stopPlay(); ``` ### 補充說明 停止播放音頻 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本 ## openVideo 打開系統視頻播放器 openVideo({params}) ### params url： - 類型：字符串 - 默認值：無 - 描述：本地文件路徑（支持fs://、widget://等文件路徑協議）或者網絡資源地址 ### 示例代碼 ```js api.openVideo({ url: 'widget://res/1.mp4' }); ``` ### 補充說明 打開系統視頻播放器 ### 可用性 iOS系統，Android系統 可提供的1.0.0及更高版本