API对象

appId appName appVersion systemType systemVersion version deviceId deviceToken deviceModel deviceName uiMode operator connectionType fullScreen screenWidth screenHeight winName winWidth winHeight frameName frameWidth frameHeight safeArea pageParam wgtParam appParam statusBarAppearance wgtRootDir fsDir cacheDir boxDir debug channel jailbreak isRecoveryMode

概述

api 对象是您入门 APICloud 必须了解和熟练掌握的一个基础对象。api 对象提供了构建应用程序所需要的一些基本的方法[Method]，如窗口操作、相册和网络数据访问等；以及一些常见的属性[Attribute]，如屏幕宽度（screenWidth），系统类型（systemType）等；还有一些常用事件[Event]，如电量低（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            //iOS系统
android        //Android系统
win            //Windows系统
wp             //Windows Phone系统

示例代码

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

设备唯一标识，字符串类型

由于系统限制，iOS系统上面无法获取设备唯一标识udid、IMEI号、Mac地址等信息，这里返回的是与证书相关联的uuid，即使应用卸载了重新安装值也不会变化。而安卓部分系统也有限制，一些设备上也无法获取到IMEI号、Mac地址等信息。

示例代码

var deviceId = api.deviceId;  //比如： FC408F8B-9598-48B6-A740-B9037ADCXXXE

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

deviceToken

iOS中用于推送的DeviceToken，如果未添加相关推送模块，或者云编译的mobileprovision证书未开启推送功能，则可能会返回空字符串，字符串类型

示例代码

var deviceToken = api.deviceToken;  //比如： a22241adab6c68b3687a9f0f086c540341f4b3f010546d4af4834ada32281615

可用性

iOS系统

可提供的1.1.0及更高版本

deviceModel

设备型号，字符串类型

注：对于2017年秋之前发布的iOS设备，引擎对原始的型号值做了映射，比如iPhone 7上面会直接返回iPhone 7；而对于2017年秋及之后发布的iOS设备，返回的值则是原始的设备型号值，比如在iPhone 8上面返回的可能是iPhone10,1而不是iPhone 8。可以在https://www.theiphonewiki.com/wiki/Models查询iOS设备型号。

示例代码

var deviceModel = api.deviceModel;  // 比如iPhone X的型号： iPhone10,3

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

deviceName

设备名称，字符串类型

示例代码

var deviceName = api.deviceName;  // 比如：“柚子”的 iPhone

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

uiMode

设备类型，字符串类型

取值范围:

pad
phone
tv
car
desk
watch

示例代码

var uiMode = api.uiMode;  // 比如：phone

可用性

iOS系统，Android系统

可提供的1.2.10及更高版本

operator

运营商名称，若未获取到则返回none，字符串类型

示例代码

var operator = api.operator;  // 比如：中国移动

可用性

iOS系统，Android系统

可提供的1.1.0及更高版本

connectionType

当前网络连接类型，如 2g、3g、4g、wifi 等，字符串类型

取值范围：

unknown            //未知
ethernet        //以太网
wifi            //wifi
2g                //2G网络
3g                //3G网络
4g                //4G网络
none            //无网络

示例代码

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及更高版本

safeArea

页面不被其它内容（如状态栏）遮住的区域，JSON对象

通过safeArea能够知道当前页面哪些地方被遮住，从而做出相应的调整，保证页面重要元素不被遮挡住。

比如应对顶部header被状态栏遮住一部分，可以为header增加一个paddingTop，如：

header.style.paddingTop = api.safeArea.top + 'px';

在比如在iPhone X上面，底部的导航菜单会被虚拟Home键遮住一部分，可以为footer增加一个paddingBottom，如：

footer.style.paddingBottom = api.safeArea.bottom + 'px';

内部字段：

{
    top:            // 安全区域上边缘，对于沉浸式下window中该值通常为状态栏高度，全屏或非沉浸式下为0（iPhone X竖屏时全屏状态下也为44）
    left:            // 安全区域左边缘，通常为0（iPhone X横屏时为44）
    bottom:            // 安全区域下边缘，通常为0（iPhone X竖屏时为34，横屏时为21）
    right:            // 安全区域右边缘，通常为0（iPhone X横屏时为44）
}

示例代码

var safeArea = api.safeArea;        // JSON对象，如{top:20, left:0, bottom:0, right:0}

可用性

iOS系统，Android系统

可提供的1.2.33及更高版本

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

当应用被第三方应用打开时，传递过来的参数，字符串类型

建议通过appintent事件监听应用被第三方应用调起，并在事件回调里面获取参数进行处理。

示例代码

var appParam = api.appParam;  //比如： {"name": "API Demo"}

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

statusBarAppearance

当前应用状态栏是否支持沉浸式效果，布尔类型

示例代码

var statusBarAppearance = api.statusBarAppearance; // 比如： true

可用性

iOS系统，Android系统

可提供的1.2.0及更高版本

wgtRootDir

widget: //协议对应的真实目录，即 widget 网页包的根目录，字符串类型

注意该目录为只读，不要往该目录下面写文件

示例代码

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: //协议对应地真实目录，字符串类型

示例代码

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 审核时可能会不通过，且此目录下的内容在手机备份时不会被备份

示例代码

var cacheDir = api.cacheDir; 
/* 
比如： 
/var/mobile/Containers/Data/Application/4E376FDE-D595-4E08-B0A4-A06561B31000/Library/Caches/APICloud/Cache/XXXXXX
*/

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

boxDir

box://协议对应的真实目录，字符串类型

iOS上面在应用Documents下，安卓上面在系统为app分配的沙箱下，root或者越狱的手机可看到。

示例代码

var boxDir = api.boxDir; 
/* 
比如： 
/var/mobile/Containers/Data/Application/4E376FDE-D595-4E08-B0A4-A06561B31000/Documents/uzfs/box
*/

可用性

iOS系统，Android系统

可提供的1.2.0及更高版本

debug

获取config.xml配置的debug字段的值。

示例代码

var debug = api.debug;                 // 比如： true

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

channel

渠道号，字符串类型

示例代码

var channel = api.channel;         //如：Apple App Store

可用性

iOS系统，Android系统

可提供的1.2.0及更高版本

jailbreak

设备是否越狱，布尔类型

示例代码

var jailbreak = api.jailbreak;         //如：false

isRecoveryMode

使用WKWebView加载页面时，若配置了WKWebView渲染进程崩溃后刷新当前页面，则刷新后该属性值为true。只支持iOS，布尔类型

示例代码

if (api.isRecoveryMode) {
    // to do
}

可用性

iOS系统，Android系统

可提供的1.2.9及更高版本

toast位置 传感器类型 错误码 电话类型 定位精度 动画类型 动画曲线类型 动画子类型 进度提示框动画类型 进度提示框风格 媒体类型 拾取器类型 图片编码类型 图片数据格式 图片源类型 网络类型 文件操作错误码 系统类型 下载状态 异步请求错误类型 异步请求返回数据类型 异步请求方法类型 状态栏样式 屏幕旋转方向 上传状态 键盘弹出页面调整方式 缓存策略

toast位置

toast 位置，字符串类型

用于 toast() 方法中 location 字段

取值范围

top          //顶部
middle       //中间
bottom       //底部

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

传感器类型

传感器类型，字符串类型

用于 startSensor() 方法中 type 字段

取值范围

accelerometer        //加速计
gyroscope            //陀螺仪
magnetic_field       //地磁传感器
proximity            //近接传感器

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

错误码

错误码，数字类型

取值范围

0        //错误
1        //没有指定模块
2        //没有指定方法
3        //参数不匹配
4        //没有权限

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

电话类型

电话类型，字符串类型

用于 call() 方法中 type 字段

取值范围

tel              //直接拨打电话。注：由于系统限制，iOS 10.2以上系统仍会弹出提示框
tel_prompt       //拨打电话之前会弹出提示框
facetime         //facetime通话，Android不支持

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

定位精度

定位精度，字符串类型

根据需要来选择适当的精度来进行定位，用于 startLocation() 方法中 accuracy 字段

取值范围

10m      //精度在10米范围内
100m     //精度在100米范围内
1km      //精度在1千米范围内
3km      //精度在3千米范围内

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

动画类型

打开 window 或打开 widget 时的动画类型，Android 部分动画不支持，字符串类型

取值范围

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 字段

取值范围

ease_in_out      //开始和结束时慢
ease_in          //开始时慢
ease_out         //结束时慢
linear           //整个动画过程速率一样

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

动画子类型

动画子类型，字符串类型

部分动画如 fade 可能没有过渡方向

取值范围

from_right       //从右边开始动画
from_left        //从左边开始动画
from_top         //从顶部开始动画
from_bottom      //从底部开始动画

可用性

iOS系统，Android系统（仅限于from_right，from_left）

可提供的1.0.0及更高版本

进度提示框动画类型

进度提示框动画类型，字符串类型

用于 showProgress() 方法中 animationType 字段

取值范围

fade         //渐隐渐现
zoom         //缩放

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

进度提示框风格

进度提示框风格，字符串类型

用于 showProgress() 方法中 style 字段

取值范围

default        //默认

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

媒体类型

媒体类型，字符串类型

用于 getPicture() 方法中 mediaValue 字段

取值范围

pic          //图片
video        //视频
all          //图片和视频，Android不支持

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

拾取器类型

拾取器类型，字符串类型

用于 openPicker() 方法中 type 字段

取值范围

date             //日期
time             //时间
date_time        //日期和时间，Android不支持

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

图片编码类型

图片编码类型，字符串类型

用于 getPicture() 方法中 encodingType 字段

取值范围

jpg       //指定图片格式为jpg
png       //指定图片格式为png

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

图片数据格式

图片数据格式，字符串类型

用于 getPicture() 方法中 destinationType 字段

取值范围

base64       //指定返回数据为base64编码后内容
url          //指定返回数据为选取的图片地址

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

图片源类型

图片源类型，字符串类型

用于 getPicture() 方法中 sourceType 字段

取值范围

library          //图片库
camera           //相机
album            //相册

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

网络类型

网络类型，字符串类型

用于 connectionType 属性

取值范围

unknown          //未知
ethernet         //以太网
wifi             //wifi
2g               //2G网络
3g               //3G网络
4g               //4G网络
none             //无网络

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

文件操作错误码

文件操作错误码，数字类型

指定 readFile()、writeFile() 方法返回错误时的错误类型

取值范围

0            //没有错误
1            //找不到文件错误
2            //不可读取错误
3            //编码格式错误
4            //无效操作错误
5            //无效修改错误
6            //磁盘溢出错误
7            //文件已存在错误

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

系统类型

系统类型，字符串类型

用于 systemType 属性

取值范围

ios          //iOS系统
android      //Android系统
win          //Windows系统
wp           //Windows Phone系统

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

下载状态

下载状态，数字类型

用于 download() 方法返回值中的 state 字段

取值范围

0            //下载中
1            //下载完成
2            //下载失败

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

异步请求错误类型

异步请求错误类型，数字类型

用于 ajax() 方法返回错误时的 code 字段

取值范围

0        //连接错误
1        //超时
2        //授权错误
3        //数据类型错误

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

异步请求返回数据类型

异步请求返回数据类型，字符串类型

用于 ajax() 方法中 dataType 字段

取值范围

json        //返回数据为 JSON 对象
text        //返回数据为字符串类型

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

异步请求方法类型

异步请求方法类型，字符串类型

用于 ajax() 方法中 method 字段

取值范围

get
post
put
delete
head

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

状态栏样式

状态栏样式，字符串类型

用于 setStatusBarStyle() 方法中 style 字段

取值范围

dark         //状态栏字体为黑色，适用于浅色背景
light        //状态栏字体为白色，适用于深色背景

可用性

iOS系统

可提供的1.0.0及更高版本

屏幕旋转方向

指定屏幕旋转到特定方向，或根据重力感应自动旋转，字符串类型

用于 setScreenOrientation() 方法中 orientation 字段

取值范围

portrait_up             //竖屏时，屏幕在home键的上面
portrait_down           //竖屏时，屏幕在home键的下面，部分手机不支持
landscape_left          //横屏时，屏幕在home键的左边
landscape_right         //横屏时，屏幕在home键的右边
auto                    //屏幕根据重力感应在横竖屏间自动切换
auto_portrait           //屏幕根据重力感应在竖屏间自动切换
auto_landscape          //屏幕根据重力感应在横屏间自动切换

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

上传状态

上传状态，数字类型

用于 ajax() 方法上传文件时返回值中的 status 字段

取值范围

0            //上传中
1            //上传完成
2            //上传失败

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

键盘弹出页面调整方式

指定键盘弹出时，页面如何调整其内容，字符串类型

取值范围

resize           //若键盘盖住输入框，页面会自动上移
pan              //若键盘盖住输入框，页面不会自动上移
auto             //默认值，由系统决定如何处理，iOS平台该字段等同于resize

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

缓存策略

缓存策略，字符串类型

用于 imageCache() 方法中的 policy 字段

取值范围

default                     //默认为 cache_else_network
cache_else_network          //若服务器上没有更新，则使用缓存
no_cache                    //不使用缓存，始终从服务器获取
cache_only                  //当缓存存在时，只从缓存中读取

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

apiready batterylow batterystatus keyback keymenu volumeup volumedown offline online pause resume scrolltobottom shake takescreenshot appidle swipedown swipeleft swiperight swipeup tap longpress viewappear viewdisappear noticeclicked appintent smartupdatefinish launchviewclicked keyboardshow keyboardhide safeareachanged interfacestylechanged navtitle navbackbtn navitembtn tabitembtn tabframe

apiready

此事件是在api对象准备完毕后产生，在每个Window或Frame的HTML代码中都需要监听此事件，以确定APICloud扩展对象已经准备完毕，可以调用了。

示例代码

apiready = function() {
    bMap = api.require("bMap");        
}

可用性

iOS系统，Android系统

batterylow

设备电池电量低事件，字符串类型

callback(ret, err)

ret：

  • 描述：返回电池电量和充电状态，不能为空
  • 内部字段：
{
    level:100,          //电池电量（0-100）
    isPlugged:true      //是否连接电源
}

示例代码

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:

  • 描述：返回电池电量和充电状态，不能为空
  • 内部字段：
{
    level:100,          //电池电量（0-100）
    isPlugged:true      //是否连接电源
}

示例代码

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:

  • 描述：被点击的键值
  • 内部字段：
{
    keyCode:0               //被点击的按键
    longPress:false         //是否是长按
}

示例代码

api.addEventListener({
    name: 'keyback'
}, function(ret, err) {
    alert('按了返回键');
});

可用性

Android系统

可提供的1.0.0及更高版本

keymenu

设备 menu 键被点击事件，仅 Android 平台有效

该事件必须在 Window 中注册才有效，Frame 中注册无效，并且只在当前屏幕上的 window 才能收到回调。

callback(ret, err)

ret:

  • 描述：被点击的按键
  • 内部字段：
{
    keyCode:0               //被点击的按键
    longPress:false         //是否是长按
}

示例代码

api.addEventListener({
    name: 'keymenu'
}, function(ret, err) {
    alert('按了菜单键');
});

可用性

Android系统

可提供的1.0.0及更高版本

volumeup

设备音量加键被点击事件，仅 Android 平台有效

该事件必须在 Window 中注册才有效，Frame 中注册无效，并且只在当前屏幕上的 window 才能收到回调。

callback(ret, err)

ret:

  • 描述：被点击的按键
  • 内部字段：
{
    keyCode:0               //被点击的按键
    longPress:false         //是否是长按
}

示例代码

api.addEventListener({
    name: 'volumeup'
}, function(ret, err) {
    alert('按了音量加键');
});

可用性

Android系统

可提供的1.2.0及更高版本

volumedown

设备音量减键被点击事件，仅 Android 平台有效

该事件必须在 Window 中注册才有效，Frame 中注册无效，并且只在当前屏幕上的 window 才能收到回调。

callback(ret, err)

ret:

  • 描述：被点击的按键
  • 内部字段：
{
    keyCode:0               //被点击的按键
    longPress:false         //是否是长按
}

示例代码

api.addEventListener({
    name:'volumedown'
}, function(ret, err){        
    alert('按了音量减键');
});

可用性

Android系统

可提供的1.2.0及更高版本

offline

监听设备断开网络的事件，字符串类型

callback(ret, err)

不能为空

示例代码

api.addEventListener({
    name:'offline'
}, function(ret, err){        
    alert('断网了');
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

online

监听设备连接到网络的事件，字符串类型

callback(ret, err)

ret:

  • 描述：监听到网络连接时的返回数据
  • 内部字段：
{
    connectionType:''            //当前网络连接类型，如2g、3g、4g、wifi等
}

示例代码

api.addEventListener({
    name:'online'
}, function(ret, err){        
    alert('已连接到网络');
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

pause

应用进入后台事件，字符串类型

callback(ret, err)

不能为空

示例代码

api.addEventListener({
    name:'pause'
}, function(ret, err){        
    alert('应用进入后台');
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

resume

应用从后台回到前台事件，字符串类型

callback(ret, err)

不能为空

示例代码

api.addEventListener({
    name:'resume'
}, function(ret, err){        
    alert('应用回到后台');
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

scrolltobottom

Window 或者 Frame 页面滑动到底部事件，字符串类型

可用于实现滚动到底部，加载更多功能

callback(ret, err)

不能为空

示例代码

api.addEventListener({
    name:'scrolltobottom',
    extra:{
        threshold:0            //设置距离底部多少距离时触发，默认值为0，数字类型
    }
}, function(ret, err){        
    alert('已滚动到底部');
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

shake

设备摇动事件，字符串类型。设置该监听后，当前 APP 将立即开启摇动检测功能。

可用于实现摇一摇功能

callback(ret, err)

不能为空

示例代码

api.addEventListener({
    name:'shake'
}, function(ret, err){        
   alert('触发了摇一摇事件');
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

takescreenshot

应用在前台运行期间，用户屏幕截图事件（比如同时按下了 home 键和电源键），只支持 iOS。

callback(ret, err)

不能为空

示例代码

api.addEventListener({
    name:'takescreenshot'
}, function(ret, err){        
   alert('用户截屏了');
});

可用性

iOS系统

可提供的1.2.0及更高版本

appidle

应用多长时间不操作屏幕后触发的事件，字符串类型

callback(ret, err)

不能为空

示例代码

api.addEventListener({
    name:'appidle',
    extra:{
        timeout:300            //设置经过多长时间不操作屏幕时触发，单位秒，数字类型
    }
}, function(ret, err){
    alert('已闲置');
});

可用性

iOS系统，Android系统

可提供的1.2.34及更高版本

swipedown

Window 或者 Frame 的页面全局向下轻扫事件，字符串类型

callback(ret, err)

不能为空

示例代码

api.addEventListener({
    name:'swipedown'
}, function(ret, err){        
   alert('向下轻扫');
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

swipeleft

Window 或者 Frame 的页面全局向左轻扫事件，字符串类型

callback(ret, err)

不能为空

示例代码

api.addEventListener({
    name:'swipeleft'
}, function(ret, err){        
   alert('向左轻扫');
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

swiperight

Window 或者 Frame 的页面全局向右轻扫事件，字符串类型

callback(ret, err)

不能为空

示例代码

api.addEventListener({
    name:'swiperight'
}, function(ret, err){        
   alert('向右轻扫');
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

swipeup

Window 或者 Frame 的页面全局向上轻扫事件，字符串类型

callback(ret, err)

不能为空

示例代码

api.addEventListener({
    name:'swipeup'
}, function(ret, err){        
   alert('向上轻扫');
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

tap

Window 或者 Frame 的页面全局单击事件，字符串类型。监听该事件后，点击 window 或者 frame 的任意位置，都将收到 tap 回调。

callback(ret, err)

不能为空

示例代码

api.addEventListener({
    name:'tap'
}, function(ret, err){        
   alert('点击了页面');
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

longpress

Window 或者 Frame 的页面全局长按事件，字符串类型。

callback(ret, err)

不能为空

示例代码

api.addEventListener({
    name:'longpress'
}, function(ret, err){        
   alert('长按了页面');
});

可用性

iOS系统，Android系统

可提供的1.2.0及更高版本

viewappear

Window 显示到屏幕的事件，字符串类型。收到 viewappear 事件回调，即标识当前 Window 已经动画结束，并且完全显示到屏幕上。

该事件的作用对象为 Window，Frame 的显示不会收到事件

callback(ret, err)

不能为空

示例代码

api.addEventListener({
    name:'viewappear'
}, function(ret, err){        
   alert('window显示');
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

viewdisappear

Window 离开屏幕的事件，字符串类型。收到 viewdisappear 事件回调，即标识当前 Window 已经动画结束，并且完全从屏幕上移除。

该事件的作用对象为 Window，Frame 的隐藏不会收到事件

若是 Window 被关闭，此事件不会再回调

callback(ret, err)

不能为空

示例代码

api.addEventListener({
    name:'viewdisappear'
}, function(ret, err){        
   alert('window消失');
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

noticeclicked

状态栏通知被用户点击后的回调，字符串类型。注意：该事件仅针对api.notification以及官方push模块发出的状态栏通知有效，无法接收第三方模块或者SDK发出的状态栏通知。

callback(ret, err)

ret:

  • 描述：通知被点击后的回调
  • 内部字段：
{
    type:0,         //内容来源类型。取值范围：0-收到APICloud push的推送内容，1-开发者自定义的
    value:''        //内容，收到的推送内容或者由开发者发送通知时自行传入的，见notification接口中extra
}

示例代码

api.addEventListener({
    name:'noticeclicked'
},function(ret,err){
    alert(ret.value);
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

appintent

本应用被其他应用调起来时（Android 平台也可以通过 Activity 打开），收到相关数据的回调，字符串类型

在任意页面中注册该监听后，如果本应用被其他应用调起，将触发该监听函数，同时将传给该应用的数据回调给网页

callback(ret, err)

ret:

  • 描述：其他应用或 Activity 传给本应用的数据
  • 内部字段：
{
    iosUrl:''           //其他应用打开本应用的url，只iOS有效，字符串类型
    sourceAppId:''      //其他应用的包名，iOS平台有可能为空字符串，字符串类型
    appParam:{}         //其他应用传递过来的参数，JSON或字符串类型
}

示例代码

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 对象
  • 内部字段：
{
    value:[{
        extra:''            //在控制台云修复里面进行静默修复时填写的附加信息，字符串类型
    }]
}

不能为空

示例代码

api.addEventListener({
    name:'smartupdatefinish'
}, function(ret, err){        
    alert('云修复完成');
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

launchviewclicked

闪屏广告被用户点击后的回调，字符串类型

callback(ret, err)

ret:

  • 描述：启动页被点击后的回调
  • 内部字段：
{
    value:''        //附加信息，字符串类型
}

示例代码

api.addEventListener({
    name:'launchviewclicked'
},function(ret,err){
    api.alert({
        msg:ret.value
    });
});

可用性

iOS系统，Android系统

可提供的1.2.0及更高版本

keyboardshow

系统键盘弹出的回调，只支持iOS，字符串类型

callback(ret, err)

ret:

  • 描述：键盘弹出的回调
  • 内部字段：
{
    h:260        //键盘高度，数字类型
}

示例代码

api.addEventListener({
    name:'keyboardshow'
},function(ret, err){
    api.alert({
        msg:ret.h
    });
});

可用性

iOS系统

可提供的1.2.23及更高版本

keyboardhide

系统键盘隐藏的回调，只支持iOS，字符串类型

callback(ret, err)

示例代码

api.addEventListener({
    name:'keyboardhide'
},function(ret, err){
    api.alert({
        msg:'键盘隐藏'
    });
});

可用性

iOS系统

可提供的1.2.23及更高版本

safeareachanged

页面安全区域发生变化的回调，可以在回调里根据需要调整页面，只iOS 11及以上系统有效，字符串类型

callback(ret, err)

ret:

  • 描述：安全区域发生变化的回调
  • 内部字段：
{
     safeArea: {
        top:             // 安全区域上边缘，数字类型
        left:            // 安全区域左边缘，数字类型
        bottom:          // 安全区域下边缘，数字类型
        right:           // 安全区域右边缘，数字类型
    }
}

示例代码

api.addEventListener({
    name:'safeareachanged'
},function(ret, err){
    var top = ret.safeArea.top;
    api.alert({
        msg: top
    });
});

可用性

iOS系统

可提供的1.2.33及更高版本

interfacestylechanged

用户外观设置发生变化事件，例如用户在系统设置开启了深色模式。只iOS 13及以上系统有效，字符串类型

callback(ret, err)

ret:

  • 描述：用户外观设置发生变化的回调
  • 内部字段：
{
     style:        // 变化后的用户外观设置，取值范围dark、light
}

示例代码

api.addEventListener({
    name:'interfacestylechanged'
},function(ret, err){
    var msg = '当前设置为：' + ret.style;
    api.alert({
        msg: msg
    });
});

可用性

iOS系统

可提供的1.3.29及更高版本

navtitle

监听tabLayout中导航栏标题点击事件。

示例代码

api.addEventListener({
    name:'navtitle'
},function(){
    alert('点击了标题');
});

可用性

iOS系统，Android系统

可提供的1.3.37及更高版本

navbackbtn

监听tabLayout中导航栏默认返回按钮点击事件。点击返回按钮时默认会关闭当前window，如果监听了此事件则不会自动关闭。

示例代码

api.addEventListener({
    name:'navbackbtn'
},function(){
    alert('点击了返回按钮');
});

可用性

iOS系统，Android系统

可提供的1.2.99及更高版本

navitembtn

监听tabLayout中导航栏左右两边自定义按钮点击事件，字符串类型

callback(ret, err)

ret:

  • 描述：按钮点击事件的回调
  • 内部字段：
{
     index:         //点击的按钮的索引，从0开始，数字类型
     type:          //点击的是左边还是右边的按钮，取值范围left|right，字符串类型
}

示例代码

api.addEventListener({
    name:'navitembtn'
},function(ret, err){
    alert('点击了'+ret.type+'按钮');
});

可用性

iOS系统，Android系统

可提供的1.2.99及更高版本

tabitembtn

监听tabLayout中tabBar项的点击事件。默认点击每一项时会切换到对应的页面，如果监听了此事件则页面不会自动切换过去，可以通过setTabBarAttr设置选中项，字符串类型

callback(ret, err)

ret:

  • 描述：tabBar项点击事件的回调
  • 内部字段：
{
     index:        //点击的项的索引，从0开始，数字类型
}

示例代码

api.addEventListener({
    name:'tabitembtn'
},function(ret, err){
    var index = ret.index + 1;
    alert('点击了第'+index+'项');
});

可用性

iOS系统，Android系统

可提供的1.2.99及更高版本

tabframe

监听tabLayout中有tabBar时frame项的切换事件。字符串类型

callback(ret, err)

ret:

  • 描述：frame切换的回调
  • 内部字段：
{
     name:       //当前显示frame名称，字符串类型
     index:      //当前显示frame索引，数字类型
}

示例代码

api.addEventListener({
    name:'tabframe'
},function(ret, err){
    alert('当前显示frame：'+ret.name);
});

可用性

iOS系统，Android系统

可提供的1.3.9及更高版本

窗口系统

openWin closeWin closeToWin windows setWinAttr openFrame closeFrame frames setFrameAttr bringFrameToFront sendFrameToBack setFrameClient animation openFrameGroup closeFrameGroup setFrameGroupAttr setFrameGroupIndex openPopoverWin closePopoverWin openSlidLayout openSlidPane closeSlidPane lockSlidPane unlockSlidPane openDrawerLayout openDrawerPane closeDrawerPane loadData execScript setBlurEffect removeLaunchView showLaunchView parseTapmode

高级窗口

openTabLayout setTabLayoutAttr setNavBarAttr setTabBarAttr setTabBarItemAttr

应用管理

installApp uninstallApp openApp appInstalled rebootApp openWidget closeWidget

网络通信

ajax cancelAjax download cancelDownload imageCache applyCertificates

数据存储

readFile writeFile setPrefs getPrefs removePrefs setGlobalData getGlobalData clearCache getCacheSize getTotalSpace getFreeDiskSpace loadSecureValue

消息事件

addEventListener removeEventListener sendEvent accessNative notification cancelNotification

设备访问

startLocation stopLocation getLocation startSensor stopSensor call sms mail openContacts setFullScreen setStatusBarStyle setScreenOrientation setKeepScreenOn toLauncher setScreenSecure setAppIconBadge getPhoneNumber hasPermission requestPermission getInterfaceStyle setInterfaceStyle

UI组件

alert confirm prompt actionSheet showProgress hideProgress toast openPicker setRefreshHeaderInfo setCustomRefreshHeaderInfo refreshHeaderLoading refreshHeaderLoadDone showFloatBox setMenuItems

多媒体

getPicture saveMediaToAlbum startRecord stopRecord startPlay stopPlay openVideo

模块加载

require

WebApp历史

historyBack historyForward

其它

pageUp pageDown setFocus

openWin

打开window

若window已存在，则会把该window显示到最前面，同时若url有变化或者reload参数为true时，页面会重新加载。

openWin({params})

params

name：

  • 类型：字符串
  • 默认值：无
  • 描述：window名字

url：

  • 类型：字符串
  • 默认值：无
  • 描述：页面地址，可以为本地文件路径，支持相对路径和绝对路径，以及 widget://、fs://等协议路径，也可以为远程地址。 当data参数不为空时，url将做为baseUrl，data中的html引用的资源文件根路径以该url为基础。

data：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）页面加载的数据内容，可以为html片段或者整张html文件的数据

headers：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）请求头

singleInstance：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）设置该window是否为单例对象。若设置为单例对象，当调用closeWin方法关闭时，window将只是从屏幕移除而不会被销毁，下次再打开时将直接使用已存在的window，而不会再重新创建。

avm：

  • 类型：布尔
  • 默认值：若在config.xml里面配置了avm字段，则默认值为配置的值，否则为false
  • 描述：（可选项）是否使用原生引擎来加载页面，页面必须是使用avm框架语法生成。

useWKWebView：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）是否使用WKWebView来加载页面。参考WKWebView介绍。

historyGestureEnabled：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）是否可以通过手势来进行历史记录前进后退，只在useWKWebView参数为true时有效。

syncCookie：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）是否自动同步WKWebView外部如ajax产生的Cookie到WKWebView中，只在useWKWebView参数为true时有效。

pageParam：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）页面参数，新页面中可以通过 api.pageParam 获取

bounces：

  • 类型：布尔
  • 默认值：若在 config.xml 里面配置了pageBounce，则默认值为配置的值，否则为 false
  • 描述：（可选项）页面是否弹动。注意如果页面使用了上拉、下拉刷新等功能，该属性可能会被刷新组件重新设置。

bgColor：

  • 类型：字符串
  • 默认值：若在 config.xml 里面配置了 windowBackground，则默认值为配置的值，否则透明
  • 描述：（可选项）背景色，支持图片和颜色，格式为 #fff、#ffffff、rgba(r,g,b,a)等，图片路径支持 fs://、widget://等 APICloud 自定义文件路径协议，同时支持相对路径

scrollToTop：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）当点击状态栏，页面是否滚动到顶部。若当前屏幕上不止一个页面的 scrollToTop 属性为 true，则所有的都不会起作用。只 iOS 有效

scrollEnabled：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）页面内容超出后是否可以滚动，只支持iOS

vScrollBarEnabled：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）是否显示垂直滚动条

hScrollBarEnabled：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）是否显示水平滚动条

scaleEnabled：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）页面是否可以缩放

hideTopBar：

  • 类型：布尔
  • 默认值：无
  • 描述：（可选项）是否隐藏原生navigationBar控件，该字段只 iOS 有效

hideBottomBar：

  • 类型：布尔
  • 默认值：无
  • 描述：（可选项）是否隐藏原生tabBar控件，该字段只 iOS 有效

slidBackEnabled：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）是否支持滑动返回。iOS7.0及以上系统中，在新打开的页面中向右滑动，可以返回到上一个页面，该字段只 iOS 有效

slidBackType：

  • 类型：字符串
  • 默认值：full
  • 描述：（可选项）当支持滑动返回时，设置手指在页面右滑的有效作用区域。取值范围（full:整个页面范围都可以右滑返回，edge:在页面左边缘右滑才可以返回），该字段只iOS有效

animation：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）动画参数，不传时使用默认动画
  • 内部字段：
{
    type:"none",                //动画类型（详见动画类型常量）
    subType:"from_right",       //动画子类型（详见动画子类型常量）
    duration:300                //动画过渡时间，默认300毫秒
}

type 取值范围：

none            //无动画效果
push            //新视图将旧视图推开
movein          //新视图移到旧视图上面
fade            //交叉淡化过渡（不支持过渡方向）
flip            //翻转效果
reveal          //将旧视图移开,显示下面的新视图
ripple          //滴水效果（不支持过渡方向）
curl            //向上翻一页
un_curl         //向下翻一页
suck            //收缩效果（不支持过渡方向）
cube            //立方体翻滚效果

subType 取值范围：

from_right      //从右边开始动画
from_left       //从左边开始动画
from_top        //从顶部开始动画
from_bottom     //从底部开始动画

（Android系统flip，ripple，curl，un_curl，suck，cube 类型不支持）

progress：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）页面加载进度配置信息，若不传则无加载进度效果
  • 内部字段：
{
    type:            //加载进度效果类型，默认值为 default，取值范围为 default|page，为 page 时，进度效果为仿浏览器类型，固定在页面的顶部
    title:           //type 为 default 时显示的加载框标题，字符串类型
    text:            //type 为 default 时显示的加载框内容，字符串类型
    color:           //type 为 page 时进度条的颜色，默认值为 #45C01A，支持#FFF，#FFFFFF，rgb(255,255,255)，rgba(255,255,255,1.0)等格式
    height:          //type 为 page 时进度条高度，默认值为3，数字类型
}

delay：

  • 类型：数字
  • 默认值：0
  • 描述：（可选项）window 显示延迟时间，适用于将被打开的 window 中可能需要打开有耗时操作的模块时，可延迟 window 展示到屏幕的时间，保持 UI 的整体性

reload：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）页面已经打开时，是否重新加载页面，重新加载页面后 apiready 方法将会被执行

allowEdit：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）是否允许长按页面时弹出选择菜单

softInputMode：

  • 类型：字符串
  • 默认值：auto
  • 描述：（可选项）当键盘弹出时，输入框被盖住时，当前页面的调整方式，只iOS有效，Android请在 config.xml 里面配置并云编译使用
  • 取值范围：
resize            //若键盘盖住输入框，页面会自动上移
pan               //若键盘盖住输入框，页面不会自动上移
auto              //默认值，由系统决定如何处理，iOS平台该字段等同于resize

softInputDismissMode：

  • 类型：字符串数组
  • 默认值：['tap']
  • 描述：（可选项）收起键盘的方式，只iOS有效。
  • 取值范围：
tap               //点击页面收起键盘，可以和drag或interactive同时使用
drag              //拖拽页面时收起键盘，可以和tap同时使用
interactive       //在键盘和页面交界处上下滑动收起键盘，可以和tap同时使用

softInputBarEnabled：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）是否显示键盘上方的工具条。只支持iOS

overScrollMode:

  • 类型：字符串
  • 默认值：never
  • 描述：（可选项）设置页面滚动到头部或尾部时，显示回弹阴影效果的模式，仅Android有效。
  • 取值范围：
never            //永远不显示
always           //总是显示
scrolls          //只有当页面内容超出设备屏幕大小，发生滚动行为时显示，建议设置为该模式。

dragAndDrop：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）是否允许iOS 11及以上系统中页面元素默认的拖拽行为。只支持iOS

hideHomeIndicator：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）是否隐藏虚拟home键。设置为true时，虚拟home键会在屏幕没有触摸操作时自动隐藏，触摸后又会显示出来。只支持iOS

defaultRefreshHeader：

  • 类型：字符串
  • 默认值：pull
  • 描述：（可选项）设置使用默认下拉刷新类型，取值范围：pull、swipe

customRefreshHeader：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）设置使用自定义下拉刷新模块的名称，设置后可以使用 api.setCustomRefreshHeaderInfo 方法来使用自定义下拉刷新组件

示例代码

api.openWin({
    name: 'page1',
    url: './page1.html',
    pageParam: {
        name: 'test'
    }
});

补充说明

窗口操作

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

closeWin

关闭 window

closeWin({params})

params

name：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）window 名字，不传时关闭当前 window，为 root 时无效

animation：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）动画参数，不传时使用默认动画
  • 内部字段：
{
    type:"none",                //动画类型（详见动画类型常量）
    subType:"from_right",       //动画子类型（详见动画子类型常量）
    duration:300                //动画过渡时间，默认300毫秒
}

type 取值范围：

none            //无动画效果
push            //新视图将旧视图推开
movein          //新视图移到旧视图上面
fade            //交叉淡化过渡（不支持过渡方向）
flip            //翻转效果
reveal          //将旧视图移开,显示下面的新视图
ripple          //滴水效果（不支持过渡方向）
curl            //向上翻一页
un_curl         //向下翻一页
suck            //收缩效果（不支持过渡方向）
cube            //立方体翻滚效果

subType 取值范围：

from_right      //从右边开始动画
from_left       //从左边开始动画
from_top        //从顶部开始动画
from_bottom     //从底部开始动画

示例代码

//关闭当前window，使用默认动画
api.closeWin();

//关闭指定window，若待关闭的window不在最上面，则无动画
api.closeWin({
    name: 'page1'
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

closeToWin

关闭到指定 window，最上面显示的 window 到指定 name 的 window 间的所有 window 都会被关闭。

closeToWin({params})

params

name：

  • 类型：字符串
  • 默认值：无
  • 描述：window 名字

animation：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）动画参数，不传时使用默认动画
  • 内部字段：
{
    type:"none",                //动画类型（详见动画类型常量）
    subType:"from_right",       //动画子类型（详见动画子类型常量）
    duration:300                //动画过渡时间，默认300毫秒
}

type 取值范围：

none            //无动画效果
push            //新视图将旧视图推开
movein          //新视图移到旧视图上面
fade            //交叉淡化过渡（不支持过渡方向）
flip            //翻转效果
reveal          //将旧视图移开,显示下面的新视图
ripple          //滴水效果（不支持过渡方向）
curl            //向上翻一页
un_curl         //向下翻一页
suck            //收缩效果（不支持过渡方向）
cube            //立方体翻滚效果

subType 取值范围：


from_right      //从右边开始动画
from_left       //从左边开始动画
from_top        //从顶部开始动画
from_bottom     //从底部开始动画

示例代码

api.closeToWin({
    name: 'root'
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

windows

获取当前所有打开的window。该方法为同步方法。

windows()

return

  • 类型：JSON对象数组
  • 内部字段
[{
    name:'',               // window名字，字符串类型
    children:[{            // window中的子window，如drawerLayout中的leftPane和rightPane，JSON对象数组类型
        name:''
    }]
}]

示例代码

var windows = api.windows();
api.alert({
    msg:JSON.stringify(windows)
});

可用性

iOS系统，Android系统

可提供的1.2.95及更高版本

setWinAttr

设置 window 属性

setWinAttr({params})

params

bounces：

  • 类型：布尔
  • 默认值：无
  • 描述：（可选项）页面是否弹动

bgColor：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）背景色，支持图片和颜色，格式为#fff、#ffffff、rgba(r,g,b,a)等，图片路径支持fs://、widget://等APICloud自定义文件路径协议，同时支持相对路径

scrollToTop：

  • 类型：布尔
  • 默认值：无
  • 描述：（可选项）当点击状态栏，页面是否滚动到顶部。若当前屏幕上不止一个页面的scrollToTop属性为true，则所有的都不会起作用。只iOS有效

scrollEnabled：

  • 类型：布尔
  • 默认值：无
  • 描述：（可选项）页面内容超出后是否可以滚动，只支持iOS

vScrollBarEnabled：

  • 类型：布尔
  • 默认值：无
  • 描述：（可选项）是否显示垂直滚动条

hScrollBarEnabled：

  • 类型：布尔
  • 默认值：无
  • 描述：（可选项）是否显示水平滚动条

scaleEnabled：

  • 类型：布尔
  • 默认值：无
  • 描述：（可选项）页面是否可以缩放

slidBackEnabled：

  • 类型：布尔
  • 默认值：无
  • 描述：（可选项）是否支持滑动返回。iOS7.0及以上系统中，在新打开的页面中向右滑动，可以返回到上一个页面，该字段只iOS有效

hideHomeIndicator：

  • 类型：布尔
  • 默认值：无
  • 描述：（可选项）是否隐藏虚拟home键。设置为true时，虚拟home键会在屏幕没有触摸操作时自动隐藏，触摸后又会显示出来。只支持iOS

softInputMode：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）当键盘弹出时，输入框被盖住时，当前页面的调整方式；只iOS有效，Android请在 config.xml 里面配置并云编译使用
  • 取值范围
    resize            //若键盘盖住输入框，页面会自动上移
pan               //若键盘盖住输入框，页面不会自动上移
auto              //默认值，由系统决定如何处理，iOS平台该字段等同于resize

示例代码

api.setWinAttr({
    bounces: true
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

openFrame

打开 frame

若 frame 已存在，则会把该窗口显示到最前面并显示，如果 url 和之前的 url 有变化，或者 reload 为 true 时，页面会刷新

此方法对 frameGroup 里面的 frame 不起作用

openFrame({params})

params

name：

  • 类型：字符串
  • 默认值：无
  • 描述：frame 名字

url：

  • 类型：字符串
  • 默认值：无
  • 描述：页面地址，可以为本地文件路径，支持相对路径和绝对路径，以及 widget://、fs://等协议路径，也可以为远程地址。 当data参数不为空时，url将做为baseUrl，data中的html引用的资源文件根路径以该url为基础。

data：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）页面加载的数据内容，可以为html片段或者整张html文件的数据

headers：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）请求头

avm：

  • 类型：布尔
  • 默认值：若在config.xml里面配置了avm字段，则默认值为配置的值，否则为false
  • 描述：（可选项）是否使用原生引擎来加载页面，页面必须是使用avm框架语法生成。

useWKWebView：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）是否使用WKWebView来加载页面。参考WKWebView介绍。

historyGestureEnabled：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）是否可以通过手势来进行历史记录前进后退，只在useWKWebView参数为true时有效。

syncCookie：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）是否自动同步WKWebView外部如ajax产生的Cookie到WKWebView中，只在useWKWebView参数为true时有效。

pageParam：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）页面参数，在新页面通过 api.pageParam 获取

bounces：

  • 类型：布尔
  • 默认值：若在 config.xml 里面配置了 pageBounce，则默认值为配置的值，否则为 true
  • 描述：（可选项）页面是否弹动。注意如果页面使用了上拉、下拉刷新等功能，该属性可能会被刷新组件重新设置。

bgColor：

  • 类型：字符串
  • 默认值：若在 config.xml 里面配置了 frameBackgroundColor，则默认值为配置的值，否则透明
  • 描述：（可选项）背景色，支持图片和颜色，格式为#fff、#ffffff、rgba(r,g,b,a)等，图片路径支持fs://、widget://等 APICloud 自定义文件路径协议，同时支持相对路径

scrollToTop：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）当点击状态栏，页面是否滚动到顶部。若当前屏幕上不止一个页面的 scrollToTop 属性为 true，则所有的都不会起作用。只iOS有效

scrollEnabled：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）页面内容超出后是否可以滚动，只支持iOS

vScrollBarEnabled：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）是否显示垂直滚动条

hScrollBarEnabled：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）是否显示水平滚动条

scaleEnabled：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）页面是否可以缩放

fixedOn：

  • 类型：字符串
  • 默认值：若当前在tabLayout组件中为ui_layout，否则为ui_window
  • 描述：（可选项）frame所要添加到的目标页面。
  • 取值范围：
ui_window    //页面添加到当前window中。若当前在tabLayout组件中，页面只能添加到navigationBar和tabBar之间的区域，无法覆盖在navigationBar、tabBar之上。
ui_layout    //页面添加到当前tabLayout中。此时页面能够添加到tabLayout中任意位置，能够覆盖在navigationBar、tabBar之上，只在tabLayout组件中有效。

rect：

  • 类型：JSON 对象
  • 默认值：充满整个父页面
  • 描述：（可选项）设置页面的位置和大小。如果要固定宽高则使用x、y、w、h等参数；如果要自适应状态栏高度变化、横竖屏切换等，则需要使用margin相关参数，不能使用w、h固定宽高。推荐使用margin相关参数来布局。
  • 内部字段：
{
    x:,             //左上角x坐标，数字类型
    y:,             //左上角y坐标，数字类型
    w:,             //宽度，若传'auto'，页面从x位置开始自动充满父页面宽度，数字或固定值'auto'
    h:,             //高度，若传'auto'，页面从y位置开始自动充满父页面高度，数字或固定值'auto'

    marginLeft:,    //相对父页面左外边距的距离，数字类型
    marginTop:,     //相对父页面上外边距的距离，数字类型
    marginBottom:,  //相对父页面下外边距的距离，数字类型
    marginRight:    //相对父页面右外边距的距离，数字类型
}

progress：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）页面加载进度配置信息，若不传则无加载进度效果
  • 内部字段：
{
    type:            //加载进度效果类型，默认值为 default，取值范围为 default|page，为 page 时，进度效果为仿浏览器类型，固定在页面的顶部
    title:           //type 为 default 时显示的加载框标题，字符串类型
    text:            //type 为 default 时显示的加载框内容，字符串类型
    color:           //type 为 page 时进度条的颜色，默认值为 #45C01A，支持#FFF，#FFFFFF，rgb(255,255,255)，rgba(255,255,255,1.0)等格式
    height:          //type 为 page 时进度条高度，默认值为3，数字类型
}

reload：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）页面已经打开时，是否重新加载页面

allowEdit：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）是否允许长按页面时弹出选择菜单

softInputMode：

  • 类型：字符串
  • 默认值：auto
  • 描述：（可选项）当键盘弹出时，输入框被盖住时，当前页面的调整方式,只iOS有效，Android请在 config.xml 里面配置并云编译使用

softInputDismissMode：

  • 类型：字符串数组
  • 默认值：['tap']
  • 描述：（可选项）收起键盘的方式，只iOS有效。
  • 取值范围：
tap              //点击页面收起键盘，可以和drag或interactive同时使用
drag             //拖拽页面时收起键盘，可以和tap同时使用
interactive      //在键盘和页面交界处上下滑动收起键盘，可以和tap同时使用

softInputBarEnabled：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）是否显示键盘上方的工具条。只支持iOS

overScrollMode:

  • 类型：字符串
  • 默认值：never
  • 描述：（可选项）设置页面滚动到头部或尾部时，显示回弹阴影效果的模式，仅Android有效。
  • 取值范围：
never            //永远不显示
always           //总是显示
scrolls          //只有当页面内容超出设备屏幕大小，发生滚动行为时显示，建议设置为该模式。

dragAndDrop：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）是否允许iOS 11及以上系统中页面元素默认的拖拽行为。只支持iOS

animation：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）动画参数，不传时无动画
  • 内部字段：
{
    type:"none",                //动画类型（详见动画类型常量）
    subType:"from_right",       //动画子类型（详见动画子类型常量）
    duration:300                //动画过渡时间，默认300毫秒
}

type 取值范围：

none            //无动画效果
push            //新视图将旧视图推开
movein          //新视图移到旧视图上面
fade            //交叉淡化过渡（不支持过渡方向）
flip            //翻转效果
reveal          //将旧视图移开,显示下面的新视图
ripple          //滴水效果（不支持过渡方向）
curl            //向上翻一页
un_curl         //向下翻一页
suck            //收缩效果（不支持过渡方向）
cube            //立方体翻滚效果

subType 取值范围：

from_right      //从右边开始动画
from_left       //从左边开始动画
from_top        //从顶部开始动画
from_bottom     //从底部开始动画

defaultRefreshHeader：

  • 类型：字符串
  • 默认值：pull
  • 描述：（可选项）设置使用默认下拉刷新类型，取值范围：pull、swipe

customRefreshHeader：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）设置使用自定义下拉刷新模块的名称，设置后可以使用 api.setCustomRefreshHeaderInfo 方法来使用自定义下拉刷新组件

示例代码

api.openFrame({
    name: 'page2',
    url: './page2.html',
    rect: {
        x: 0,
        y: 0,
        w: 'auto',
        h: 'auto'
    },
    pageParam: {
        name: 'test'
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

closeFrame

关闭frame

closeFrame({params})

params

name：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）frame 名字，不传时关闭当前 frame

示例代码

api.closeFrame({
    name: 'page2'
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

frames

获取当前window中所有打开的frame（包括frameGroup中的frame）。该方法为同步方法。

frames()

return

  • 类型：JSON对象数组
  • 内部字段
[{
    name:'',              // frame名字，字符串类型
    parent:''             // 父窗口的名字，如果是frameGroup中的frame，该值为frameGroup的名字，字符串类型
}]

示例代码

var frames = api.frames();
api.alert({
    msg:JSON.stringify(frames)
});

可用性

iOS系统，Android系统

可提供的1.2.95及更高版本

setFrameAttr

设置frame属性

setFrameAttr({params})

params

name：

  • 类型：字符串
  • 默认值：无
  • 描述：frame 名称

bounces：

  • 类型：布尔
  • 默认值：无
  • 描述：（可选项）页面是否弹动

hidden：

  • 类型：布尔
  • 默认值：无
  • 描述：（可选项）设置本 frame 是否隐藏，设置显示隐藏并不会改变frame在整个窗口系统之间的层级关系。

bgColor：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）背景色，支持图片和颜色，格式为#fff、#ffffff、rgba(r,g,b,a)等，图片路径支持fs://、widget://等 APICloud 自定义文件路径协议，同时支持相对路径

scrollToTop：

  • 类型：布尔
  • 默认值：无
  • 描述：（可选项）当点击状态栏，页面是否滚动到顶部。若当前屏幕上不止一个页面的 scrollToTop 属性为 true，则所有的都不会起作用。只iOS有效

scrollEnabled：

  • 类型：布尔
  • 默认值：无
  • 描述：（可选项）页面内容超出后是否可以滚动，只支持iOS

vScrollBarEnabled：

  • 类型：布尔
  • 默认值：无
  • 描述：（可选项）是否显示垂直滚动条

hScrollBarEnabled：

  • 类型：布尔
  • 默认值：无
  • 描述：（可选项）是否显示水平滚动条

scaleEnabled：

  • 类型：布尔
  • 默认值：无
  • 描述：（可选项）页面是否可以缩放

rect：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）窗口区域
  • 内部字段：
{
    x:0,                 //左上角x坐标
    y:0,                 //左上角y坐标
    w:320,               //宽度，若传'auto'，页面从x位置开始自动充满父页面宽度
    h:480                //高度，若传'auto'，页面从y位置开始自动充满父页面高度
}

softInputMode：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）当键盘弹出时，输入框被盖住时，当前页面的调整方式,只iOS有效，Android请在 config.xml 里面配置并云编译使用
  • 取值范围：
    resize            //若键盘盖住输入框，页面会自动上移
pan               //若键盘盖住输入框，页面不会自动上移
auto              //默认值，由系统决定如何处理，iOS平台该字段等同于resize

    示例代码

api.setFrameAttr({
    name: 'page2',
    bounces: true
});

补充说明

设置 frame 属性

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

bringFrameToFront

调整 frame 到前面

bringFrameToFront({params})

params

from：

  • 类型：字符串
  • 默认值：无
  • 描述：待调整显示顺序的 frame 名字

to：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）frame 名字，不传时调整 from 对应 frame 到最前面，否则调整 from 对应 frame 到此 frame 前面

示例代码

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 后面

示例代码

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 加载状态、加载进度等发生变化时的回调
  • 内部字段：
{
    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，字符串类型
}

示例代码

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
  • 描述：（可选项）动画曲线类型，指定动画开始和结束时的快慢
  • 取值范围
ease_in_out     //开始和结束时慢
ease_in         //开始时慢
ease_out        //结束时慢
linear          //整个动画过程速率一样

repeatCount：

  • 类型：数字
  • 默认值：0
  • 描述：（可选项）动画次数，默认不重复，为-1时无限重复

autoreverse：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）一次动画结束后是否自动反转动画

alpha：

  • 类型：数字
  • 默认值：无
  • 描述：（可选项）整个页面的透明度，介于0 1之间，Android 不支持

translation：

  • 类型：JSON
  • 默认值：无
  • 描述：（可选项）位置平移参数
  • 内部字段：
{
    x: 0,         //x轴方向上的平移距离，默认为0
    y: 0,         //y轴方向上的平移距离，默认为0
    z: 0          //z轴方向上的平移距离，默认为0，Android不支持
}

scale：

  • 类型：JSON
  • 默认值：无
  • 描述：（可选项）页面缩放参数，Android 不支持
  • 内部字段：
{
    x: 1,         //x轴方向上的放大倍率，默认为1
    y: 1,         //y轴方向上的放大倍率，默认为1
    z: 1          //z轴方向上的放大倍率，默认为1
}

rotation：

  • 类型：JSON
  • 默认值：无
  • 描述：（可选项）页面旋转参数，Android 不支持
  • 内部字段：
{
    degree:0,     //旋转角度，默认0
    x: 0,         //绕x轴旋转，默认为0
    y: 0,         //绕y轴旋转，默认为0
    z: 1          //绕z轴旋转，默认为1
}

callback(ret, err)

动画结束后的回调

示例代码

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) {
    alert('动画结束');
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

openFrameGroup

打开frame组

若frame组已存在，则会把该frame组显示到最前面。frame组打开后，当前页面加载完成后，页面会预加载后面指定个数页面

openFrameGroup({params}, callback(ret, err))

params

name：

  • 类型：字符串
  • 默认值：无
  • 描述：frame 组名字

background：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）frame 组背景，颜色（#fff,#ffffff,rgba(r,g,b,a)）或图片（支持文件路径协议和相对路径）

scrollEnabled：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）frame 组是否能够左右滚动

fixedOn：

  • 类型：字符串
  • 默认值：若当前在tabLayout组件中为ui_layout，否则为ui_window
  • 描述：（可选项）frameGroup所要添加到的目标页面。
  • 取值范围：
ui_window    //页面添加到当前window中。若当前在tabLayout组件中，页面只能添加到navigationBar和tabBar之间的区域，无法覆盖在navigationBar、tabBar之上。
ui_layout    //页面添加到当前tabLayout中。此时页面能够添加到tabLayout中任意位置，能够覆盖在navigationBar、tabBar之上，只在tabLayout组件中有效。

rect：

  • 类型：JSON 对象
  • 默认值：充满整个父页面
  • 描述：（可选项）设置frameGroup的位置和大小。如果要固定宽高则使用x、y、w、h等参数；如果要自适应状态栏高度变化、横竖屏切换等，则需要使用margin相关参数，不能使用w、h固定宽高。推荐使用margin相关参数来布局。
  • 内部字段：
{
    x:,             //左上角x坐标，数字类型
    y:,             //左上角y坐标，数字类型
    w:,             //宽度，若传'auto'，页面从x位置开始自动充满父页面宽度，数字或固定值'auto'
    h:,             //高度，若传'auto'，页面从y位置开始自动充满父页面高度，数字或固定值'auto'

    marginLeft:,    //相对父页面左外边距的距离，数字类型
    marginTop:,     //相对父页面上外边距的距离，数字类型
    marginBottom:,  //相对父页面下外边距的距离，数字类型
    marginRight:    //相对父页面右外边距的距离，数字类型
}

index：

  • 类型：数字
  • 默认值：0
  • 描述：（可选项）默认显示的页面索引

preload：

  • 类型：数字
  • 默认值：1
  • 描述：（可选项）预加载的 frame 个数，默认加载当前页后面一个

frames：

  • 类型：数组
  • 默认值：无
  • 描述：frame 数组
  • 内部字段：
[{
    name:'',                                //frame名字，字符串类型，不能为空字符串
    url:'',                                 //页面地址，可以为本地文件路径，支持相对路径和绝对路径，以及 widget://、fs://等协议路径，也可以为远程地址。 当data参数不为空时，url将做为baseUrl，data中的html引用的资源文件根路径以该url为基础。字符串类型
    data:'',                                //（可选项）页面加载的数据内容，可以为html片段或者整张html文件的数据
    headers:{},                             //（可选项）请求头
    avm:false,                              //（可选项）是否使用原生引擎来加载页面，页面必须是使用avm框架语法生成。
    useWKWebView:false,                     //（可选项）是否使用WKWebView来加载页面。参考[WKWebView介绍](https://community.apicloud.com/bbs/thread-151904-1-1.html)。
    historyGestureEnabled:false,            //（可选项）是否可以通过手势来进行历史记录前进后退，只在useWKWebView参数为true时有效。
    pageParam:{},                           //（可选项）页面参数，页面中可以通过api.pageParam获取，JSON对象
    bounces:true,                           //（可选项）是否弹动，布尔型，默认值：若在 config.xml 里面配置了pageBounce，则默认值为配置的值，否则为true。注意如果页面使用了上拉、下拉刷新等功能，该属性可能会被刷新组件重新设置。
    bgColor:'#fff',                         //（可选项）背景色，支持图片和颜色，格式为#fff、#ffffff、rgba(r,g,b,a)等，图片路径支持fs://、widget://等APICloud自定义文件路径协议，同时支持相对路径
    scrollToTop:true                        //（可选项）当点击状态栏，页面是否滚动到顶部。若当前屏幕上不止一个页面的scrollToTop属性为true，则所有的都不会起作用。默认值：true。只iOS有效
    scrollEnabled:true                      //（可选项）页面内容超出后是否可以滚动，默认为true，只支持iOS
    vScrollBarEnabled:true,                 //（可选项）是否显示垂直滚动条，布尔型，默认值：true
    hScrollBarEnabled:false,                //（可选项）是否显示水平滚动条，布尔型，默认值：false
    scaleEnabled:true,                      //（可选项）页面是否可以缩放，布尔型，默认值：false
    allowEdit:false,                        //（可选项）是否允许长按页面时弹出选择菜单
    softInputMode:'auto'                    //（可选项）当键盘弹出时，输入框被盖住时，当前页面的调整方式，只iOS有效。
                                            //取值范围：
                                            //resize    //若键盘盖住输入框，页面会自动上移
                                            //pan       //若键盘盖住输入框，页面不会自动上移
                                            //auto      //默认值，由系统决定如何处理，iOS平台该字段等同于resize
    softInputBarEnabled:false,              //（可选项）是否显示键盘上方的工具条，布尔型，默认值：true，只iOS有效
    overScrollMode,                         //（可选项）设置页面滚动到头部或尾部时，显示回弹阴影效果的模式，仅Android有效。取值范围：never，always，scrolls
    defaultRefreshHeader:''                 //（可选项）设置使用默认下拉刷新类型，取值范围：pull、swipe
    customRefreshHeader:''                  //（可选项）设置使用自定义下拉刷新模块的名称，设置后可以使用api.setCustomRefreshHeaderInfo方法来使用自定义下拉刷新组件
}]

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 描述：当前显示在屏幕上的 frame 变化时会回调
  • 内部字段：
{
    name:'',         //当前 frame 名称
    index:0          //当前 frame 索引
}

示例代码

api.openFrameGroup({
    name: 'group1',
    rect: {
        x: 0,
        y: 0,
        w: 'auto',
        h: 'auto'
    },
    frames: [{
        name: 'frame1',
        url: 'frame1.html',
        bgColor: '#fff'
    }, {
        name: 'frame2',
        url: 'frame2.html',
        bgColor: '#fff'
    }]
}, function(ret, err) {
    var index = ret.index;
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

closeFrameGroup

关闭frame组

closeFrameGroup({params})

params

name：

  • 类型：字符串
  • 默认值：无
  • 描述：frame 组名字

示例代码

api.closeFrameGroup({
    name: 'group1'
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setFrameGroupAttr

设置 frame 组属性

setFrameGroupAttr({params})

params

name：

  • 类型：字符串
  • 默认值：无
  • 描述：frame 组名字

hidden：

  • 类型：布尔
  • 默认值：无
  • 描述：（可选项）frame 组是否隐藏，设置显示隐藏并不会改变frame组在整个窗口系统之间的层级关系。

scrollEnabled：

  • 类型：布尔
  • 默认值：无
  • 描述：（可选项）frame 组是否能够左右滚动

rect：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）frame 组区域
  • 内部字段：
{
    x:0,             //左上角x坐标
    y:0,             //左上角y坐标
    w:320,           //宽度，若传'auto'，frame组从x位置开始自动充满父页面宽度
    h:240            //高度，若传'auto'，frame组从y位置开始自动充满父页面高度
}

示例代码

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

示例代码

api.setFrameGroupIndex({
    name: 'group1',
    index: 2
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

openPopoverWin

打开弹出层窗口，只支持iPad

在弹出层窗口里面不能再打开弹出窗口，页面可以使用所有的 window 和 frame 相关操作，如 openWin、openFrame 等，此方法能够使用openWin方法的所有参数

使用 execScript() 方法时，引擎只会在整个弹出层里面的窗口中去寻找要执行脚本的窗口，如果要和弹出层下面的窗口间进行通信，可以使用 sendEvent() 方法实现

openPopoverWin({params})

params

style：

  • 类型：字符串
  • 默认值：default
  • 描述：（可选项）弹出窗口展示类型
  • 取值范围
default         // 弹出层从底部往上弹出，显示在屏幕中间一片指定区域，周围为黑色半透明
popover         // 弹出层带指示箭头，可设置箭头方向和位置

width：

  • 类型：数字
  • 默认值：540
  • 描述：（可选项）弹出窗口显示的宽度

height：

  • 类型：数字
  • 默认值：620
  • 描述：（可选项）弹出窗口显示的高度

arrowRect：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）当style为popover时，箭头指向的位置
  • 内部字段：
{
    x:0,                  //左上角x坐标，数字类型
    y:0,                  //左上角y坐标，数字类型
    w:0,                  //宽度，数字类型
    h:0,                  //高度，数字类型
}

arrowDirection：

  • 类型：字符串
  • 默认值：any
  • 描述：（可选项）当style为popover时，箭头指向的方向
  • 取值范围
left          // 指向左边
right         // 指向右边
up            // 指向上边
down          // 指向下边
any           // 系统根据页面情况选择合适的方向

示例代码

api.openPopoverWin({
    width: 480,
    height: 400,
    name: 'page1',
    url: './page1.html'
});

可用性

iOS系统

可提供的1.0.0及更高版本

closePopoverWin

关闭整个弹出层窗口，只 iPad 上面有效

在当前弹出层里面的任意页面里面调用都会关闭整个弹出层

closePopoverWin()

示例代码

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 样式
  • 内部字段：
{
    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 样式
  • 内部字段：
{
    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
  • 内部字段：
{
    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有效
    scrollEnabled:true                  //（可选项）页面内容超出后是否可以滚动，默认为true，只支持iOS
    vScrollBarEnabled:true,             //（可选项）是否显示垂直滚动条，默认true 
    hScrollBarEnabled:true,             //（可选项）是否显示水平滚动条，默认true
    scaleEnabled:true,                  //（可选项）页面是否可以缩放，布尔型，默认值：false
    allowEdit:false,                    //（可选项）是否允许长按页面时弹出选择菜单
    softInputMode:'auto'                //（可选项）当键盘弹出时，输入框被盖住时，当前页面的调整方式，只iOS有效
                                        //取值范围：
                                        //resize      //若键盘盖住输入框，页面会自动上移
                                        //pan         //若键盘盖住输入框，页面不会自动上移
                                        //auto        //默认值，由系统决定如何处理，iOS平台该字段等同于resize
    softInputBarEnabled:false,          //（可选项）是否显示键盘上方的工具条，布尔型，默认值：true，只iOS有效
    defaultRefreshHeader:''             //（可选项）设置使用默认下拉刷新类型，取值范围：pull、swipe
    customRefreshHeader:''              //（可选项）设置使用自定义下拉刷新模块的名称，设置后可以使用api.setCustomRefreshHeaderInfo方法来使用自定义下拉刷新组件
}

slidPane：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：侧滑层window
  • 内部字段：
{
    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有效
    scrollEnabled:true                  //（可选项）页面内容超出后是否可以滚动，默认为true，只支持iOS
    vScrollBarEnabled:true,             //（可选项）是否显示垂直滚动条，默认true 
    hScrollBarEnabled:true,             //（可选项）是否显示水平滚动条，默认true
    scaleEnabled:true,                  //（可选项）页面是否可以缩放，布尔型，默认值：false
    allowEdit:false,                    //（可选项）是否允许长按页面时弹出选择菜单
    softInputMode:'auto'                //（可选项）当键盘弹出时，输入框被盖住时，当前页面的调整方式，只iOS有效
                                        //取值范围：
                                        //resize       //若键盘盖住输入框，页面会自动上移
                                        //pan          //若键盘盖住输入框，页面不会自动上移
                                        //auto         //默认值，由系统决定如何处理，iOS平台该字段等同于resize
    softInputBarEnabled:false,          //（可选项）是否显示键盘上方的工具条，布尔型，默认值：true，只iOS有效
    defaultRefreshHeader:''             //（可选项）设置使用默认下拉刷新类型，取值范围：pull、swipe
    customRefreshHeader:''              //（可选项）设置使用自定义下拉刷新模块的名称，设置后可以使用api.setCustomRefreshHeaderInfo方法来使用自定义下拉刷新组件
}

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 描述：手指头触摸屏幕，引起开始侧滑时的回调，左右侧滑时应该在这里面判断显示左边页面还是右边页面
  • 内部字段：
{
    type: 'left'        //侧滑方向，left或right
    event: 'slide'      //侧滑事件，（slide-当前处于滑动状态、open-侧滑打开状态、close-侧滑关闭状态
}

示例代码

api.openSlidLayout({
    type: 'left',
    fixedPane: {
        name: 'win1',
        url: 'win1.html'
    },
    slidPane: {
        name: 'win2',
        url: 'win2.html'
    }
}, function(ret, err) {

});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

openSlidPane

向左或右进行侧滑

openSlidPane({params})

params

type：

  • 类型：字符串
  • 默认值：无
  • 描述：侧滑类型，left 或 right

示例代码

api.openSlidPane({
    type: 'left'
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

closeSlidPane

当 SlidPane 处于左或右侧滑状态时，将其收起

closeSlidPane()

示例代码

api.closeSlidPane();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

lockSlidPane

锁住 SlidPane，使其不能跟随手指滑动而移动

lockSlidPane()

示例代码

api.lockSlidPane();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

unlockSlidPane

解锁 SlidPane，使其能跟随手指滑动而移动

unlockSlidPane()

示例代码

api.unlockSlidPane();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

openDrawerLayout

打开一个抽屉式侧滑 window，可以从当前 window 的左右边缘滑动拉出侧滑 window。

此方法能够使用 openWin 方法的所有参数，在此基础上增加了 leftPane、rightPane 等参数，可以通过 api.closeWin()方法来关闭整个抽屉式侧滑。

实例widget下载地址

openDrawerLayout({params})

params

leftPane：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：左边侧滑 window
  • 内部字段：
{
    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有效
    scrollEnabled:true                  //（可选项）页面内容超出后是否可以滚动，默认为true，只支持iOS
    vScrollBarEnabled:true,             //（可选项）是否显示垂直滚动条，默认true 
    hScrollBarEnabled:true,             //（可选项）是否显示水平滚动条，默认true
    scaleEnabled:true,                  //（可选项）页面是否可以缩放，布尔型，默认值：false
    allowEdit:false,                    //（可选项）是否允许长按页面时弹出选择菜单
    softInputMode:'auto',               //（可选项）当键盘弹出时，输入框被盖住时，当前页面的调整方式，只iOS有效
                                        //取值范围：
                                        //resize      //若键盘盖住输入框，页面会自动上移
                                        //pan         //若键盘盖住输入框，页面不会自动上移
                                        //auto        //默认值，由系统决定如何处理，iOS平台该字段等同于resize
    softInputBarEnabled:false,          //（可选项）是否显示键盘上方的工具条，布尔型，默认值：true，只iOS有效
    defaultRefreshHeader:''             //（可选项）设置使用默认下拉刷新类型，取值范围：pull、swipe
    customRefreshHeader:''              //（可选项）设置使用自定义下拉刷新模块的名称，设置后可以使用api.setCustomRefreshHeaderInfo方法来使用自定义下拉刷新组件
}

rightPane：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：右边侧滑 window
  • 内部字段：
{
    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有效
    scrollEnabled:true                  //（可选项）页面内容超出后是否可以滚动，默认为true，只支持iOS
    vScrollBarEnabled:true,             //（可选项）是否显示垂直滚动条，默认true 
    hScrollBarEnabled:true,             //（可选项）是否显示水平滚动条，默认true
    scaleEnabled:true,                  //（可选项）页面是否可以缩放，布尔型，默认值：false
    allowEdit:false,                    //（可选项）是否允许长按页面时弹出选择菜单
    softInputMode:'auto'                //（可选项）当键盘弹出时，输入框被盖住时，当前页面的调整方式，只iOS有效
                                        //取值范围：
                                        //resize       //若键盘盖住输入框，页面会自动上移
                                        //pan          //若键盘盖住输入框，页面不会自动上移
                                        //auto         //默认值，由系统决定如何处理，iOS平台该字段等同于resize
    softInputBarEnabled:false,          //（可选项）是否显示键盘上方的工具条，布尔型，默认值：true，只iOS有效
    defaultRefreshHeader:''             //（可选项）设置使用默认下拉刷新类型，取值范围：pull、swipe
    customRefreshHeader:''              //（可选项）设置使用自定义下拉刷新模块的名称，设置后可以使用api.setCustomRefreshHeaderInfo方法来使用自定义下拉刷新组件
}

slidToOpenPane：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）是否支持在页面边缘处滑动打开drawerPane

slidToClosePane：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）在打开的drawerPane页面，是否支持滑动关闭drawerPane

tapToClosePane：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）在打开的drawerPane页面，是否支持点击遮罩部分关闭drawerPane

示例代码

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

示例代码

api.openDrawerPane({
    type: 'left'
});

可用性

iOS系统，Android系统

可提供的1.2.0及更高版本

closeDrawerPane

关闭抽屉式侧滑Pane

closeDrawerPane()

示例代码

api.closeDrawerPane();

可用性

iOS系统，Android系统

可提供的1.2.0及更高版本

loadData

在指定 window 或者 frame 中加载HTML数据，对于 frameGroup 里面的 frame 也有效。

loadData({params})

params

name：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）window 名称，若要跨 window ，该字段必须指定，首页的名称为 root

frameName：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）frame名称

url：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）做为baseUrl，data中的html引用的资源文件根路径以该url为基础，可以为本地文件路径，支持相对路径和绝对路径，以及 widget://、fs://等协议路径。

data：

  • 类型：字符串
  • 默认值：无
  • 描述：页面加载的数据内容，可以为html片段或者整张html文件的数据

示例代码

//在当前window中加载HTML数据
var data = 'hello world';
api.loadData({
    data: data
});

//在当前window中找到名为frmName的frame，并在该frame中加载HTML数据
var data = 'hello world';
api.loadData({
    frameName: 'frmName',
    data: data
});

//在名为winName的window中加载HTML数据
var data = 'hello world';
api.loadData({
    name: 'winName',
    data: data
});

//在名为winName的window中找到名为frmName的frame，并在该frame中加载HTML数据
var data = 'hello world';
api.loadData({
    name: 'winName',
    frameName: 'frmName',
    data: data
});

补充说明

无

可用性

iOS系统，Android系统

可提供的1.2.9及更高版本

execScript

在指定 window 或者 frame 中执行脚本，对于 frameGroup 里面的 frame 也有效，若 name 和 frameName 都未指定，则在当前 window 中执行脚本，具体执行逻辑见补充说明。

execScript({params})

params

name：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）window 名称，若要跨 window 执行脚本，该字段必须指定，首页的名称为 root

frameName：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）frame名称

script：

  • 类型：字符串
  • 默认值：无
  • 描述：js代码

示例代码

//在当前window中执行jsfun脚本
var jsfun = 'funcGoto();';
api.execScript({
    script: jsfun
});

//在当前window中找到名为frmName的frame，并在该frame中执行jsfun脚本
var jsfun = 'funcGoto();';
api.execScript({
    frameName: 'frmName',
    script: jsfun
});

//在名为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
});

补充说明

统一处理逻辑为：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及更高版本

setBlurEffect

对当前页面或应用设置模糊效果

该方法只支持iOS 8及以上系统

setBlurEffect({params})

params

style：

  • 类型：字符串
  • 默认值：无
  • 描述：模糊效果风格样式，传none时表示移除模糊效果
  • 取值范围
none            //移除模糊效果
extra_light     //模糊区域比底层视图的颜色更淡
light           //模糊区域与底层视图的色调近似
dark            //模糊区域比底层视图的颜色更深
regular         //适应界面风格的常规模糊样式，只支持iOS 10及以上系统
prominent       //适应界面风格，使内容更加突出，只支持iOS 10及以上系统

global：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）false时表示对当前页面添加模糊效果，true时表示对整个应用窗口添加模糊效果

alpha：

  • 类型：数字
  • 默认值：1
  • 描述：（可选项）模糊区域透明度，介于0和1之间

borderRadius：

  • 类型：数字
  • 默认值：0
  • 描述：（可选项）模糊区域圆角半径

animation：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）动画参数，设置模糊渐变效果，只支持iOS 9及以上系统
  • 内部字段：
{
    delay:               //动画延迟执行时间，单位毫秒，默认值0，数字类型
    duration:            //动画执行时间，单位毫秒，默认值0，数字类型
    curve:               //动画曲线类型，默认值ease_in_out，字符串类型
}

curve 取值范围：

ease_in_out     //开始和结束时慢
ease_in         //开始时慢
ease_out        //结束时慢
linear          //整个动画过程速率一样

rect：

  • 类型：JSON 对象
  • 默认值：页面区域
  • 描述：（可选项）模糊区域
  • 内部字段：
{
    x:,                  //左上角x坐标，数字类型
    y:,                  //左上角y坐标，数字类型
    w:,                  //宽度，数字类型
    h:,                  //高度，数字类型
}

示例代码

// 设置应用模糊效果：
api.addEventListener({
   name: 'pause'
}, function(){
   api.setBlurEffect({
       style: 'light',
       global: true
   });
});

api.addEventListener({
   name: 'resume'
}, function(){
   api.setBlurEffect({
       style: 'none',
       global: true
   });
});

可用性

iOS系统

可提供的1.2.61及更高版本

historyBack

当前window或者frame的a标签历史记录后退一页

historyBack({params}, callback(ret, err))

params

frameName：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）frame 名称，若不传则表示对当前页面进行操作

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    status:true        //后退是否成功，失败时说明不能再后退了
}

示例代码

api.historyBack({
    frameName: 'detail'
}, function(ret, err) {
    if (!ret.status) {
        api.closeWin();
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

historyForward

当前window或者frame的a标签历史记录前进一页

historyForward({params}, callback(ret, err))

params

frameName：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）frame 名称，若不传则表示对当前页面进行操作

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    status:true        //前进是否成功，失败时说明不能再前进了
}

示例代码

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 对象
  • 内部字段：
{
    scrolled:true        //是否滚动，为false时说明当前页面已经到达顶部了
}

示例代码

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 对象
  • 内部字段：
{
    scrolled:true        //是否滚动，为false时说明当前页面已经到达底部了
}

示例代码

api.pageDown(function(ret, err) {
    if (!ret.scrolled) {
        //已经滚动到底部
    }
});

可用性

iOS系统，Android系统

可提供的1.1.0及更高版本

setFocus

设置input是否获取焦点

setFocus({params})

params

inputId：

  • 类型：字符串
  • 默认值：无
  • 描述：input标签id

focus：

  • 类型：布尔
  • 默认值：无
  • 描述：是否获取焦点

示例代码

api.setFocus({
    inputId: 'test',
    focus: true
});

可用性

iOS系统，Android系统

可提供的1.3.35及更高版本

removeLaunchView

移除启动图。若 config.xml 里面配置 autoLaunch 为 false，则启动图不会自动消失，直到调用此方法移除。

removeLaunchView({params})

params

animation：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）动画参数，不传时不使用动画
  • 内部字段：
{
    type:"fade",                //动画类型（详见动画类型常量）
    subType:"from_right",       //动画子类型（详见动画子类型常量）
    duration:300                //动画过渡时间，默认300毫秒
}

type 取值范围：

none            //无动画效果
push            //新视图将旧视图推开
movein          //新视图移到旧视图上面
fade            //交叉淡化过渡（不支持过渡方向）
flip            //翻转效果
reveal          //将旧视图移开,显示下面的新视图
ripple          //滴水效果（不支持过渡方向）
curl            //向上翻一页
un_curl         //向下翻一页
suck            //收缩效果（不支持过渡方向）
cube            //立方体翻滚效果

subType 取值范围：


from_right      //从右边开始动画
from_left       //从左边开始动画
from_top        //从顶部开始动画
from_bottom     //从底部开始动画

示例代码

api.removeLaunchView({
    animation: {
        type: 'fade',
        duration: 500
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

showLaunchView

重新显示闪屏广告，若没有闪屏广告则不显示。

showLaunchView()

示例代码

api.showLaunchView();

可用性

iOS系统，Android系统

可提供的1.2.37及更高版本

parseTapmode

解析元素 tapmode 属性，优化点击事件处理

默认页面加载完成后，引擎会对 dom 里面的元素进行 tapmode 属性解析，若是之后用代码创建的 dom 元素，则需要调用该方法后 tapmode 属性才会生效

parseTapmode()

示例代码

api.parseTapmode();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

openTabLayout

打开tabLayout布局

本方法继承了openWin方法的所有参数，同时在此基础上增加了navigationBar、tabBar等参数，来设置和使用原生的顶部导航栏和底部标签栏，可以通过closeWin方法来关闭页面。为帮助您更好的了解和使用tabLayout，可以参考论坛的示例说明。

如果在首页需要使用tabLayout，可以将相关参数配置在JSON文件中，再在config.xml中将content的值设置成该JSON文件的路径，例如：

// 创建一个app.json文件，放置在widget目录下
{
  "name": "root",
  "tabBar": {
    "frames": [{
      "title": "页面一",
      "name": "page1",
      "url": "widget://html/page1.html"
    }, {
      "title": "页面二",
      "name": "page2",
      "url": "widget://html/page2.html"
    }, {
      "title": "页面三",
      "name": "page3",
      "url": "widget://html/page3.html"
    }],
    "list": [{
      "text": "页面一",
      "iconPath": "widget://image/tab_1.png",
      "selectedIconPath": "widget://image/tab_1_hov.png"
    }, {
      "text": "页面二",
      "iconPath": "widget://image/tab_2.png",
      "selectedIconPath": "widget://image/tab_2_hov.png"
    }, {
      "text": "页面三",
      "iconPath": "widget://image/tab_3.png",
      "selectedIconPath": "widget://image/tab_3_hov.png"
    }]
  }
}

// config.xml中设置content字段的值为JSON文件的路径：
<content src="app.json" />

openTabLayout({params})

params

title：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）显示在顶部navigationBar上面的标题

hideNavigationBar：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）是否隐藏顶部navigationBar导航栏，只在传了navigationBar参数时有效

hideTabBar：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）是否隐藏底部tabBar标签栏，只在传了tabBar参数时有效

navigationBar：

  • 类型：JSON对象
  • 默认值：无
  • 描述：（可选项）顶部navigationBar导航栏配置信息
  • 内部字段：
{
    height:                   //（可选项）导航栏高度。默认值45。数字类型
    background:               //（可选项）导航栏背景。支持颜色值和图片，默认值#fff，字符串类型
    shadow:                   //（可选项）导航栏底部阴影线颜色。默认值#ddd，字符串类型
    color:                    //（可选项）导航栏标题文字颜色。默认值#000，字符串类型
    fontSize:                 //（可选项）导航栏标题字体大小。默认值17，数字类型
    fontWeight:               //（可选项）导航栏标题字体粗细。字符串类型。Android及iOS8.2以下系统只支持normal、bold，iOS8.2及以上系统支持normal、bold、bolder、lighter、100~900。
    hideBackButton:           //（可选项）是否隐藏默认返回按钮。如果传了leftButtons，hideBackButton参数失效。返回按钮由箭头图标和前一个页面的标题组成，若前一个页面未设置标题，则按钮文字为“返回”。可以通过监听navbackbtn或keyback事件来处理返回按钮的点击事件。布尔类型
    leftButtons:              //（可选项）导航栏左边按钮组。左边按钮会替换掉默认的返回按钮，按钮按照数组顺序从左至右显示，按钮建议最多2个，可以通过监听navitembtn事件来处理按钮点击事件，JSON对象数组类型
    [{
        text:                 //（可选项）按钮标题文字，可以和icon同时存在，字符串类型
        color:                //（可选项）按钮标题文字颜色，默认值#000，字符串类型
        fontSize:             //（可选项）按钮标题字体大小。默认值17，数字类型
        fontWeight:           //（可选项）按钮标题字体粗细，默认值normal。字符串类型。Android及iOS8.2以下系统只支持normal、bold，iOS8.2及以上系统支持normal、bold、bolder、lighter、100~900。
        iconPath:             //（可选项）按钮icon图标路径，可以和text同时存在，图片尺寸需要为4倍图，例如设备上面期望显示的图标尺寸为25*25，则图片实际尺寸需要为100*100，字符串类型
    }],
    rightButtons:             //（可选项）导航栏右边按钮组。按钮按照数组顺序从右至左显示，按钮建议最多2个，可以通过监听navitembtn事件来处理按钮点击事件，JSON对象数组类型
    [{
        text:                 //（可选项）按钮标题文字，可以和icon同时存在，字符串类型
        color:                //（可选项）按钮标题文字颜色，默认值#000，字符串类型
        fontSize:             //（可选项）按钮标题字体大小。默认值17，数字类型
        fontWeight:           //（可选项）按钮标题字体粗细，默认值normal。字符串类型。Android及iOS8.2以下系统只支持normal、bold，iOS8.2及以上系统支持normal、bold、bolder、lighter、100~900。
        iconPath:             //（可选项）按钮icon图标路径，可以和text同时存在，图片尺寸需要为4倍图，例如设备上面期望显示的图标尺寸为25*25，则图片实际尺寸需要为100*100，字符串类型
    }]
}

tabBar：

  • 类型：JSON对象
  • 默认值：无
  • 描述：（可选项）底部tabBar标签栏配置信息，可以通过监听tabitembtn事件来处理标签栏每项的点击事件
  • 内部字段：
{
    height:                    //（可选项）标签栏高度。默认值54。数字类型
    background:                //（可选项）标签栏背景。支持颜色值和图片，默认值#fff，字符串类型
    shadow:                    //（可选项）标签栏顶部阴影线颜色。默认值#ddd，字符串类型
    color:                     //（可选项）标签栏各项的文字颜色。默认值#000，字符串类型
    selectedColor:             //（可选项）标签栏各项选中状态的文字颜色。默认值#000，字符串类型
    fontSize:                  //（可选项）标签栏各项文字字体大小。默认值10，数字类型
    fontWeight:                //（可选项）标签栏各项文字字体粗细，默认值normal。字符串类型。Android及iOS8.2以下系统只支持normal、bold，iOS8.2及以上系统支持normal、bold、bolder、lighter、100~900。
    textOffset:                //（可选项）标签栏各项文字距离底部的距离。默认值2，数字类型
    animated:                  //（可选项）选中标签栏每项时，切换对应的页面是否带有动画效果，默认值false。布尔类型
    scrollEnabled:             //（可选项）标签栏每项对应的页面间是否能够左右滚动切换，默认值true。布尔类型
    index:                     //（可选项）默认选中项的索引。默认值0。数字类型
    preload:                   //（可选项）预加载的页面个数。默认值0。数字类型
    list:                      // 标签栏各项配置信息，JSON对象数组类型
    [{
        text:                  //（可选项）标题文字，可以和icon同时存在，字符串类型
        iconPath:              //（可选项）默认状态下icon图标路径，可以和text同时存在，图片尺寸需要为4倍图，例如设备上面期望显示的图标尺寸为25*25，则图片实际尺寸需要为100*100，推荐尺寸108*108，字符串类型
        selectedIconPath:      //（可选项）选中状态下的icon图标路径，可以和text同时存在，图片尺寸需要为4倍图，例如设备上面期望显示的图标尺寸为25*25，则图片实际尺寸需要为100*100，推荐尺寸108*108，字符串类型
    }],
    frames:                    // 标签栏各项对应的页面的信息，JSON对象数组类型
    [{
        title:                 //（可选项）标签栏切换时对应顶部导航栏的标题文字，字符串类型
        ...                    // 同openFrameGroup方法中frames参数里面的参数
    }]
}

示例代码

// 打开只有navigationBar的页面：
api.openTabLayout({
    name: 'help',
    url: 'widget://html/help.html',
    title: '帮助',
    hideNavigationBar: false,
    navigationBar: {
        background: '#5082c2',
        color: '#fff',
        leftButtons: [{
            iconPath: 'widget://image/back.png'
        }]
    }
});

// 打开只有tabBar的页面：
api.openTabLayout({
    name: 'tabLayout',
    url: 'widget://html/tabLayout.html',
    hideTabBar: false,
    tabBar: {
        selectedColor: '#45C01A',
        list: [{
            text: '页面一',
            iconPath: 'widget://image/tab_1.png',
            selectedIconPath: 'widget://image/tab_1_hov.png'
        }, {
            text: '页面二',
            iconPath: 'widget://image/tab_2.png',
            selectedIconPath: 'widget://image/tab_2_hov.png'
        }, {
            text: '页面三',
            iconPath: 'widget://image/tab_3.png',
            selectedIconPath: 'widget://image/tab_3_hov.png'
        }],
        frames: [{
            name: 'page1',
            url: 'widget://html/page1.html'
        }, {
            name: 'page2',
            url: 'widget://html/page2.html'
        }, {
            name: 'page3',
            url: 'widget://html/page3.html'
        }]
    }
});

可用性

iOS系统，Android系统

可提供的1.2.99及更高版本

setTabLayoutAttr

设置tabLayout属性

setTabLayoutAttr({params})

params

title：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）显示在顶部navigationBar上面的标题

hideNavigationBar：

  • 类型：布尔
  • 默认值：无
  • 描述：（可选项）是否隐藏顶部navigationBar导航栏

hideTabBar：

  • 类型：布尔
  • 默认值：无
  • 描述：（可选项）是否隐藏底部tabBar标签栏

animated：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）显示隐藏navigationBar、tabBar时是否有动画效果。

示例代码

api.setTabLayoutAttr({
    title: '首页'
});

可用性

iOS系统，Android系统

可提供的1.2.99及更高版本

setNavBarAttr

设置navigationBar属性

setNavBarAttr({params})

params

background：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）导航栏背景。支持颜色值和图片

shadow：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）导航栏底部阴影线颜色

color：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）导航栏标题文字颜色

fontSize：

  • 类型：数字
  • 默认值：无
  • 描述：（可选项）导航栏标题字体大小

fontWeight：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）导航栏标题文字粗细

hideBackButton：

  • 类型：布尔
  • 默认值：无
  • 描述：（可选项）是否隐藏默认返回按钮。可以通过监听navbackbtn或keyback事件来处理返回按钮的点击事件。

leftButtons：

  • 类型：JSON对象数组
  • 默认值：无
  • 描述：（可选项）导航栏左边按钮组，左边按钮会替换掉默认的返回按钮，按钮按照数组顺序从左至右显示，按钮建议最多2个，可以通过监听navitembtn事件来处理按钮点击事件。
  • 内部字段：
[{
    text:                 //（可选项）按钮标题文字，可以和icon同时存在，字符串类型
    color:                //（可选项）按钮标题文字颜色，默认值#000，字符串类型
    fontSize:             //（可选项）按钮标题字体大小。默认值17，数字类型
    fontWeight:           //（可选项）按钮标题字体粗细，默认值normal。字符串类型。Android及iOS8.2以下系统只支持normal、bold，iOS8.2及以上系统支持normal、bold、bolder、lighter、100~900。
    iconPath:             //（可选项）按钮icon图标路径，可以和text同时存在，图片尺寸需要为4倍图，例如设备上面期望显示的图标尺寸为25*25，则图片实际尺寸需要为100*100，字符串类型
}]

rightButtons：

  • 类型：JSON对象数组
  • 默认值：无
  • 描述：（可选项）导航栏右边按钮组。按钮按照数组顺序从右至左显示，按钮建议最多2个，可以通过监听navitembtn事件来处理按钮点击事件。
  • 内部字段：
[{
    text:                 //（可选项）按钮标题文字，可以和icon同时存在，字符串类型
    color:                //（可选项）按钮标题文字颜色，默认值#000，字符串类型
    fontSize:             //（可选项）按钮标题字体大小。默认值17，数字类型
    fontWeight:           //（可选项）按钮标题字体粗细，默认值normal。字符串类型。Android及iOS8.2以下系统只支持normal、bold，iOS8.2及以上系统支持normal、bold、bolder、lighter、100~900。
    iconPath:             //（可选项）按钮icon图标路径，可以和text同时存在，图片尺寸需要为4倍图，例如设备上面期望显示的图标尺寸为25*25，则图片实际尺寸需要为100*100，字符串类型
}]

示例代码

api.setNavBarAttr({
    rightButtons: [{
        text: '完成'
    }]
});

可用性

iOS系统，Android系统

可提供的1.3.2及更高版本

setTabBarAttr

设置tabBar属性

setTabBarAttr({params})

params

index：

  • 类型：数字
  • 默认值：无
  • 描述：（可选项）设置选中标签栏指定项

background：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）标签栏背景。支持颜色值和图片

shadow：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）标签栏顶部阴影线颜色

color：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）标签栏各项的文字颜色

selectedColor：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）标签栏各项选中状态下的文字颜色

fontSize：

  • 类型：数字
  • 默认值：无
  • 描述：（可选项）标签栏各项文字字体大小

fontWeight：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）标签栏各项文字粗细

textOffset：

  • 类型：数字
  • 默认值：无
  • 描述：（可选项）标签栏各项文字距离底部的距离

示例代码

api.setTabBarAttr({
    index: 1
});

可用性

iOS系统，Android系统

可提供的1.2.99及更高版本

setTabBarItemAttr

设置tabBar指定项的属性

setTabBarItemAttr({params})

params

index：

  • 类型：数字
  • 默认值：无
  • 描述：要设置的指定项的索引

text：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）该项的标题文字

iconPath：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）该项默认状态下icon图标路径。图片尺寸需要为4倍图，例如设备上面期望显示的图标尺寸为2525，则图片实际尺寸需要为100100

selectedIconPath：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）该项选中状态下icon图标路径。图片尺寸需要为4倍图，例如设备上面期望显示的图标尺寸为2525，则图片实际尺寸需要为100100

badge：

  • 类型：JSON对象
  • 默认值：无
  • 描述：（可选项）该项的角标信息
  • 内部字段：
{
    text：              //角标内容。传0时表示隐藏角标，其余任意值表示显示角标，可以为空字符串，字符串类型
    background：        //角标的背景，支持颜色和图片，默认值#f00，字符串类型
    color：             //角标文字颜色，默认值#fff，字符串类型
    radius：            //角标的半径，默认值10，高度固定，宽度根据内容自动增长，数字类型
    x：                 //角标左边相对于所在项顶部中间的位置，默认值5，数字类型
    y：                 //角标顶部相对于所在项顶部的位置，默认值5，数字类型
}

示例代码

api.setTabBarItemAttr({
    index: 4,
    badge: {
        text: 1
    }
});

可用性

iOS系统，Android系统

可提供的1.2.99及更高版本

installApp

安装应用，如果是苹果的AppStore应用地址，将会跳转到AppStore应用详情页面

installApp({params})

params

appUri：

  • 类型：字符串
  • 默认值：无
  • 描述：目标应用的资源文件标识。Android上为apk包的本地路径，如file://xxx.apk；iOS上为应用安装包对应的plist文件地址

示例代码

//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及更高版本

uninstallApp

卸载应用，只支持Android

uninstallApp({params})

params

packageName：

  • 类型：字符串
  • 默认值：无
  • 描述：要卸载的应用的包名

示例代码

api.uninstallApp({
    packageName: 'com.yourcompany.yourapp'
});

可用性

Android系统

可提供的1.2.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 对象
  • 内部字段：
{
    msg:""      //错误描述
}

示例代码

//iOS中的使用方法如下：

api.openApp({
    iosUrl: 'weixin://',     //打开微信，其中weixin为微信的URL Scheme
    appParam: {
        appParam: 'app参数'
    }
});

api.openApp({
    iosUrl: 'app-settings:'  //打开应用设置界面，支持iOS 8及以上系统
});

//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

判断设备上面是否已安装指定应用

注意：iOS9中系统对检测应用是否安装的方法做了限制，若想得到期望的结果，需要在config.xml里面配置可被检测的URL Scheme。

appInstalled({params}, callback(ret, err))

params

sync：

  • 类型：布尔
  • 默认值：false
  • 描述：执行结果的返回方式。为false时通过callback返回，为true时直接返回。

appBundle：

  • 类型：字符串
  • 默认值：无
  • 描述：Android 平台为应用包名，iOS 平台为应用定义的 URL Scheme。iOS 中的 URL Scheme 与包名不一样，一个应用只有一个包名，但是可以配置多个 URL Scheme

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    installed:true            //是否安装，布尔类型
}

示例代码

//异步返回结果：
api.appInstalled({
    appBundle: 'xxx'
}, function(ret, err) {
    if (ret.installed) {
        //应用已安装
    } else {
        //应用未安装
    }
});

//同步返回结果：
var installed = api.appInstalled({
    sync: true,
    appBundle: 'xxx'
});
if (installed) {
    //应用已安装
} else {
    //应用未安装
}

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

rebootApp

重启应用，云修复完成后可以调用此方法来重启应用使云修复生效。

rebootApp()

示例代码

api.rebootApp();

可用性

iOS系统，Android系统

可提供的1.2.0及更高版本

openWidget

打开 Widget，若此 widget 已经被打开，则会把其调整到最前面显示

openWidget({params}, callback(ret, err))

params

id：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）widget的id

path：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）widget的根目录，该目录下面放置有config.xml等文件。通过传入此字段，可以打开放置在任意位置的widget。注意若传了id字段，此字段将被忽略

wgtParam：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）widget 参数，在新打开的 widget 里面的页面中通过 api.wgtParam 获取

longPressToExit：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）在新打开的 widget 里面的页面中是否支持长按退出，只支持iOS。

animation：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）动画参数，不传时使用默认动画
  • 内部字段：
{
    type:"none",                 //动画类型（详见动画类型常量）
    subType:"from_right",        //动画子类型（详见动画子类型常量）
    duration:300                 //动画过渡时间，默认300毫秒
}

type 取值范围：

none            //无动画效果
push            //新视图将旧视图推开
movein          //新视图移到旧视图上面
fade            //交叉淡化过渡（不支持过渡方向）
flip            //翻转效果
reveal          //将旧视图移开,显示下面的新视图
ripple          //滴水效果（不支持过渡方向）
curl            //向上翻一页
un_curl         //向下翻一页
suck            //收缩效果（不支持过渡方向）
cube            //立方体翻滚效果

subType 取值范围：

from_right      //从右边开始动画
from_left       //从左边开始动画
from_top        //从顶部开始动画
from_bottom     //从底部开始动画

（Android系统flip，ripple，curl，un_curl，suck，cube 类型不支持）

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 描述：新 widget 关闭时候的返回值

示例代码

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:"none",                //动画类型（详见动画类型常量）
    subType:"from_right",       //动画子类型（详见动画子类型常量）
    duration:300                //动画过渡时间，默认300毫秒
}

type 取值范围：

none            //无动画效果
push            //新视图将旧视图推开
movein          //新视图移到旧视图上面
fade            //交叉淡化过渡（不支持过渡方向）
flip            //翻转效果
reveal          //将旧视图移开,显示下面的新视图
ripple          //滴水效果（不支持过渡方向）
curl            //向上翻一页
un_curl         //向下翻一页
suck            //收缩效果（不支持过渡方向）
cube            //立方体翻滚效果

subType 取值范围：


from_right      //从右边开始动画
from_left       //从左边开始动画
from_top        //从顶部开始动画
from_bottom     //从底部开始动画

示例代码

api.closeWidget({
    id: 'A00000001',
    retData: {
        name: 'closeWidget'
    },
    animation: {
        type: 'flip',
        subType: 'from_bottom',
        duration: 500
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

ajax

跨域异步请求，支持标准HTTP协议，支持HTTPS单向/双向认证请求，支持文件上传，支持缓存。 HTTPS需要向国际受信任的CA证书颁发机构购买CA证书，否则将可能请求失败，可以在config中配置不校验CA证书是否受信任。 云编译开启全局加密的情况下，请务必使用api.ajax，避免使用JQ等框架的ajax，否则将引起请求失败。

ajax({params}, callback(ret, err))

params

url：

  • 类型：字符串
  • 默认值：无
  • 描述：请求地址

encode：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）是否对url进行编码。默认或传true时，Android将始终对url编码，而iOS只有在url不合法（如存在中文字符）的时候才进行编码。如果url中有特殊字符需要编码的，建议先在js层进行编码，然后此参数传false。

tag：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）该字段用于传给cancelAjax方法来取消请求，如果传入该字段，请保证各个ajax的tag字段唯一

method：

  • 类型：字符串
  • 默认值：get
  • 描述：（可选项）异步请求方法类型
  • 取值范围：
    get
post
put
delete
head
options
trace
patch

cache：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）是否缓存，若缓存，下次没网络时请求则会使用缓存，仅在get请求有效

timeout：

  • 类型：数字
  • 默认值：30
  • 描述：（可选项）超时时间，单位秒

dataType：

  • 类型：字符串
  • 默认值：json
  • 描述：（可选项）返回数据类型。若该字段传json，接收到服务器返回的数据后会尝试将其转换成JSON对象，如果无法转成JSON对象，将返回数据类型错误
  • 取值范围：
json        //返回数据为 JSON 对象
text        //返回数据为字符串类型

charset：

  • 类型：字符串
  • 默认值：utf-8
  • 描述：（可选项）当响应头里面没有返回字符集编码时，使用此编码来解析数据

headers：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）设置请求头数据。建议里面的key使用首字母大写的形式，如 User-Agent

report：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）是否实时返回上传文件进度

returnAll：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）是否需要返回所有 response 信息（包括响应头、消息体、状态码），为 true 时，返回的头信息获取方法(ret.headers)，消息体信息获取方法(ret.body)，状态码获取方法(ret.statusCode)

data：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）POST 数据，method 为 get 时不传。以下字段除了 values 和 files 可以同时使用，其它参数都不能同时使用。
  • 内部字段：
{
    stream："",  //以二进制流的方式提交文件。stream为文件路径（字符串类型），支持绝对路径，以及fs://、cache://、box://等文件路径协议。可直接使用其他端API返回的结果，如api.getPicture回调的ret.data等
    body："",    //以纯文本的方式提交数据，body支持字符串及JSON对象（若要校验数据完整性，需将JSON对象转换成字符串再传入）。提交JSON对象时，需设置application/json类型的Content-Type头
    values：{},  //以表单方式提交参数（JSON对象）, 如 {"field1": "value1", "field1": "value2"} (直接传JSON对像.)
    files：{}    //以表单方式提交文件，支持多文件上传（JSON对象）,如 {"file": "path"}，也支持同一字段对应多文件：{"file":["path1","path2"]}。文件路径，支持绝对路径，以及fs://、cache://、box://等文件路径协议。可直接使用其他端API返回的结果，如api.getPicture回调的ret.data等.
}

certificate：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）用于https请求开启双向认证的情况下，客户端配置p12安全证书设置。
  • 内部字段：
{
    path:'',          //p12证书路径，支持fs://、widget://、cache://等文件路径协议，字符串类型
    password:''       //证书密码，字符串类型
}

safeMode：

  • 类型：字符串
  • 默认值：none
  • 描述：（可选项）设置请求安全模式。设置后，若检测到数据有安全风险时将返回“不安全的数据”错误
  • 取值范围：
none              //不做数据安全检查
both              //对请求和响应的数据做安全检查
request           //对请求数据做安全检查
response          //对响应的数据做安全检查

proxy：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）设置代理请求服务器。
  • 内部字段：
{
    host:          //服务器地址，字符串类型
    port:          //服务器端口，数字类型
}

callback(ret, err)

ret：

  • 类型：JSON对象或字符串
  • 描述：通常情况下直接为服务器返回的数据，在一些情况下则会有所不同，依赖于传入的dataType、returnAll参数，以及上传文件时是否返回上传进度。
// returnAll参数传true时，内部字段为：
{
    statusCode:          //状态码，数字类型
    headers: {},         //响应头，JSON对象
    body: ''             //消息体，即服务器返回的数据。若dataType为json，那么body为JSON对象，否则为字符串
}

// 上传文件时，若report字段传true返回上传进度时，原服务器返回数据会被放在body字段里面，内部字段为：
{
    progress: 100,       //上传进度，0.00-100.00
    status: '',          //上传状态，数字类型。（0：上传中、1：上传完成、2：上传失败）
    body: ''             //上传完成时，服务器返回的数据。若dataType为json，那么body为JSON对象，否则为字符串
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
    statusCode: 500,      //网络请求状态码，数字类型
    code:0,               //错误码，数字类型。（0：连接错误、1：超时、2：授权错误、3：数据类型错误、4：不安全的数据）
    msg:''                //错误描述，字符串类型
    body:                 //服务器返回的原始数据
}

示例代码

// 表单方式提交数据或文件
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) });
    }
});

// 提交JSON数据
api.ajax({
    url: 'http://192.168.1.101:3101/upLoad',
    method: 'post',
    headers: {
        'Content-Type': 'application/json;charset=utf-8'
    },
    data: {
        body: {
            name: 'haha'
        }
    }
}, function(ret, err) {
    if (ret) {
        api.alert({ msg: JSON.stringify(ret) });
    } else {
        api.alert({ msg: JSON.stringify(err) });
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

cancelAjax

取消异步请求

cancelAjax({params})

params

tag：

  • 类型：字符串
  • 默认值：无
  • 描述：请求标识

示例代码

api.cancelAjax({
    tag: 'publish'
});

可用性

iOS系统，Android系统

可提供的1.1.0及更高版本

download

下载文件

download({params}, callback(ret, err))

params

url：

  • 类型：字符串
  • 默认值：无
  • 描述：下载地址

encode：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）是否对url进行编码。默认或传true时，Android将始终对url编码，而iOS只有在url不合法（如存在中文字符）的时候才进行编码。如果url中有特殊字符需要编码的，建议先在js层进行编码，然后此参数传false。

savePath：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）存储路径，不传时使用自动创建的路径

report：

  • 类型：布尔类型
  • 默认值：false
  • 描述：（可选项）下载过程是否上报

cache：

  • 类型：布尔类型
  • 默认值：true
  • 描述：（可选项）是否使用本地缓存

allowResume：

  • 类型：布尔类型
  • 默认值：false
  • 描述：（可选项）是否允许断点续传

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    fileSize:0,                 //文件大小，数字类型
    percent:0,                  //下载进度（0-100），数字类型
    state:0,                    //下载状态，数字类型。（0：下载中、1：下载完成、2：下载失败）
    savePath:''                 //存储路径（字符串类型）
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
    msg:""    //错误描述
}

示例代码

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：

  • 类型：字符串
  • 默认值：无
  • 描述：下载地址

示例代码

api.cancelDownload({
    url: url
});

补充说明

取消文件下载

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

imageCache

图片缓存

imageCache({params}, callback(ret, err))

params

url：

  • 类型：字符串
  • 默认值：无
  • 描述：图片远程地址

encode：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）是否对url进行编码。默认或传true时，Android将始终对url编码，而iOS只有在url不合法（如存在中文字符）的时候才进行编码。如果url中有特殊字符需要编码的，建议先在js层进行编码，然后此参数传false。

policy：

  • 类型：字符串
  • 默认值：default
  • 描述：（可选项）缓存策略
  • 取值范围：
default                        //默认为 cache_else_network
cache_else_network             //若服务器上没有更新，则使用缓存
no_cache                       //不使用缓存，始终从服务器获取
cache_only                     //当缓存存在时，只从缓存中读取

thumbnail：

  • 类型：布尔类型
  • 默认值：true
  • 描述：（可选项）使用缩略图，底层将根据当前系统及设备性能，返回最优的缩略图，有利于提高应用运行及渲染效率

tag：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）标识信息，将在回调中返回

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    status:true,          //是否成功，布尔类型
    url:''                //图片本地存储路径，若下载失败，则返回传入的url，字符串类型
    tag:''                //标识信息，字符串类型
}

示例代码

api.imageCache({
    url: 'http://a.hiphotos.baidu.com/image/w%3D400/sign=2abe1c77d4ca7bcb7d7bc62f8e086b3f/64380cd7912397ddf9f4bdb05a82b2b7d1a287f0.jpg'
}, function(ret, err) {
    var url = ret.url;
});

可用性

iOS系统，Android系统

可提供的1.1.0及更高版本

applyCertificates

设置全局HTTPS双向认证，客户端P12证书，证书将作用于ajax网络请求，以及openWin、openFrame等加载web页面。此配置与ajax的certificate互斥，即如果ajax配置了certificate，将优先使用ajax出入的certificate。

applyCertificates({params})

params

certificates：

  • 类型：JSON对象数组
  • 默认值：无
  • 描述：证书信息列表
  • 内部字段：
[{
    host:'',              //目标域名，证书将应用于该域名及其子域名，字符串类型
    path:'',              //p12证书路径，支持绝对路径及widget://、fs://等路径，字符串类型
    password:''           //p12证书密码，字符串类型。建议加密存储。
}]

示例代码

api.applyCertificates({
    certificates: [{
        host:'apicloud.com',
        path:'widget://res/https.p12',
        password:'123'
    }]
});

可用性

iOS系统，Android系统

可提供的1.2.79及更高版本

readFile

读取文本文件内容，只支持utf-8编码文本类型文件

readFile({params}, callback(ret, err))

params

sync：

  • 类型：布尔
  • 默认值：false
  • 描述：执行结果的返回方式。为false时通过callback返回，为true时直接返回。

path：

  • 类型：字符串
  • 默认值：无
  • 描述：文件路径，支持绝对路径和文件路径协议如fs://、widget://等

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    status:true,        //操作成功状态值
    data:""             //文件内容，字符串类型
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
    code:0,             //错误码
    msg:""              //错误描述
}

code取值范围:

0            //没有错误
1            //找不到文件错误
2            //不可读取错误
3            //编码格式错误
4            //无效操作错误
5            //无效修改错误
6            //磁盘溢出错误
7            //文件已存在错误

示例代码

//异步返回结果：
api.readFile({
    path: 'fs://a.txt'
}, function(ret, err) {
    if (ret.status) {
        var data = ret.data;
    } else {
        alert(err.msg);
    }
});

//同步返回结果：
var data = api.readFile({
    sync: true,
    path: 'fs://a.txt'
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

writeFile

写入内容到文本文件

writeFile({params}, callback(ret, err))

params

path：

  • 类型：字符串
  • 默认值：无
  • 描述：文件路径，支持绝对路径和文件路径协议如fs://、cache://等，不支持widget://目录，该目录只读

data：

  • 类型：字符串
  • 默认值：无
  • 描述：文件内容

append：

  • 类型：布尔
  • 默认值：false
  • 描述：是否以追加方式写入数据，默认会清除之前文件内容

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    status:true        //操作成功状态值
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
    code:0,           //错误码
    msg:""            //错误描述
}

code 取值范围:

0            //没有错误
1            //找不到文件错误
2            //不可读取错误
3            //编码格式错误
4            //无效操作错误
5            //无效修改错误
6            //磁盘溢出错误
7            //文件已存在错误

示例代码

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：

  • 类型：字符串
  • 默认值：无
  • 描述：值

示例代码

api.setPrefs({
    key: 'userName',
    value: 'api'
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getPrefs

获取偏好设置值

getPrefs({params}, callback(ret, err))

params

sync：

  • 类型：布尔
  • 默认值：false
  • 描述：执行结果的返回方式。为false时通过callback返回，为true时直接返回。

key：

  • 类型：字符串
  • 默认值：无
  • 描述：键

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    value:""        //值
}

示例代码

//异步返回结果：
api.getPrefs({
    key: 'userName'
}, function(ret, err) {
    var userName = ret.value;
});

//同步返回结果：
var userName = api.getPrefs({
    sync: true,
    key: 'userName'
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

removePrefs

删除偏好设置值

removePrefs({params})

params

key：

  • 类型：字符串
  • 默认值：无
  • 描述：键

示例代码

api.removePrefs({
    key: 'userName'
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setGlobalData

设置全局数据，数据只存储在内存中，不会存储到本地文件系统。

setGlobalData({params})

params

key：

  • 类型：字符串
  • 默认值：无
  • 描述：键

value：

  • 类型：标准JSON支持的数据类型，如字符串、数字、JSON对象等
  • 默认值：无
  • 描述：值

示例代码

api.setGlobalData({
    key: 'userName',
    value: 'api'
});

可用性

iOS系统，Android系统

可提供的1.2.87及更高版本

getGlobalData

获取全局数据

getGlobalData({params})

params

key：

  • 类型：字符串
  • 默认值：无
  • 描述：键

示例代码

var userName = api.getGlobalData({
    key: 'userName'
});

可用性

iOS系统，Android系统

可提供的1.2.87及更高版本

clearCache

清除缓存，包括cache://目录下的文件、拍照临时文件、网页缓存文件等，清除时可能需要消耗一定时间。

clearCache({params}, callback(ret, err))

params

timeThreshold：

  • 类型：数字
  • 默认值：0
  • 描述：（可选项）清除多少天前的缓存

callback(ret, err)

  • 描述：清除完成后的回调

示例代码

api.clearCache(function() {
    api.toast({
        msg: '清除完成'
    });
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getCacheSize

获取缓存占用空间大小，缓存包括cache://目录下的文件、拍照临时文件以及网页缓存文件等，计算可能需要花费一些时间

getCacheSize({params}, callback(ret, err))

params

sync：

  • 类型：布尔
  • 默认值：false
  • 描述：执行结果的返回方式。为false时通过callback返回，为true时直接返回。

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    size:        //缓存大小，单位为Byte，数字类型。（-1：无存储设备、-2：正在准备USB存储设备、-3：无法访问存储设备）
}

示例代码

//异步返回结果：
api.getCacheSize(function(ret) {
    var size = ret.size;
});

//同步返回结果：
var size = api.getCacheSize({
    sync: true
});

可用性

iOS系统，Android系统

可提供的1.1.0及更高版本

getTotalSpace

获取总存储空间大小

getTotalSpace({params},callback(ret, err))

params

sync：

  • 类型：布尔
  • 默认值：false
  • 描述：执行结果的返回方式。为false时通过callback返回，为true时直接返回。

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    size:        //总存储空间大小，单位为Byte，数字类型。（-1：无存储设备、-2：正在准备USB存储设备、-3：无法访问存储设备）
}

示例代码

//异步返回结果：
api.getTotalSpace(function(ret, err) {
    var size = ret.size;
});

//同步返回结果：
var size = api.getTotalSpace({
    sync: true
});

可用性

iOS系统，Android系统

可提供的1.2.7及更高版本

getFreeDiskSpace

获取剩余存储空间大小

getFreeDiskSpace({params},callback(ret, err))

params

sync：

  • 类型：布尔
  • 默认值：false
  • 描述：执行结果的返回方式。为false时通过callback返回，为true时直接返回。

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    size:        //剩余存储空间大小，单位为Byte，数字类型。（-1：无存储设备、-2：正在准备USB存储设备、-3：无法访问存储设备）
}

示例代码

//异步返回结果：
api.getFreeDiskSpace(function(ret, err) {
    var size = ret.size;
});

//同步返回结果：
var size = api.getFreeDiskSpace({
    sync: true
});

可用性

iOS系统，Android系统

可提供的1.1.0及更高版本

loadSecureValue

从加密的key.xml文件中读取指定数据，key.xml文件放置于网页包里面的res目录，配置方式：

<?xml version="1.0" encoding="UTF-8"?>
<security>
<item name="appKey" value="1111111"/>
</security>

loadSecureValue({params}, callback(ret, err))

params

sync：

  • 类型：布尔
  • 默认值：false
  • 描述：执行结果的返回方式。为false时通过callback返回，为true时直接返回。

key：

  • 类型：字符串
  • 默认值：无
  • 描述：键

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    value:""        //值
}

示例代码

//异步返回结果：
api.loadSecureValue({
    key: 'appKey'
}, function(ret, err) {
    var appKey = ret.value;
});

//同步返回结果：
var appKey = api.loadSecureValue({
    sync: true,
    key: 'appKey'
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

addEventListener

监听事件，支持系统事件和自定义事件

addEventListener({params}, callback(ret, err))

params

name：

  • 类型：字符串
  • 默认值：无
  • 描述：自定义事件或系统事件名称（详见事件）

extra：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）附加字段。一些特定事件可能需要提供额外的参数。
  • 内部字段：
{
    threshold:           //当事件为scrolltobottom时，设置距离底部多少距离时触发事件，默认值为0，数字类型
    timeout:             //当事件为appidle时，设置经过多长时间不操作屏幕时触发，单位秒，数字类型
}

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 描述：事件发生时传递的参数，可能为空

示例代码

//如监听网络连接事件
api.addEventListener({
    name: 'online'
}, function(ret, err) {
    alert('已连接网络');
});

补充说明

监听事件

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

removeEventListener

移除事件监听

removeEventListener({params})

params

name：

  • 类型：字符串
  • 默认值：无
  • 描述：自定义事件或系统事件名称（详见事件）

示例代码

api.removeEventListener({
    name: 'online'
});

补充说明

停止监听事件

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

sendEvent

将任意一个自定义事件广播出去，该事件可在任意页面通过 addEventListener 监听收到。

sendEvent({params})

params

name

  • 类型：字符串
  • 默认值：无
  • 描述：任意自定义事件的名称，比如：apprunning、appover等

extra

  • 类型：字符串或 JSON 对象
  • 默认值：无
  • 描述：（可选项）附带的参数。在监听页面的回调里面通过 ret.value 获取。

示例代码

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 对象

示例代码

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 事件获取该通知相关内容。

注：当应用在前台弹出通知提示时，iOS平台的通知将在显示几秒后消失，不会在通知栏保留。

notification({params}, callback(ret, err))

params

vibrate：

  • 类型：数组
  • 默认值：[100, 500, 100, 500]
  • 描述：（可选项）伴随节奏的震动，时间数组，单位：毫秒。iOS平台震动时间为固定值；Android平台节奏为【等待-震动-等待-震动..】，例如[100, 500, 100, 500]表现效果为：等待100毫秒-震动500毫秒-等待100毫秒-震动500毫秒

sound：

  • 类型：字符串
  • 默认值：default
  • 描述：（可选项）提示音，默认为系统设置的提示音。Android支持传入widget协议音频文件，例如：widget://res/horse.mp3；当实现闹钟功能时，iOS只支持widget://路径协议

light：

  • 类型：布尔型
  • 默认值：false
  • 描述：（可选项）设备提示灯是否闪烁

notify：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）弹出通知到状态栏。弹出时是否震动或响铃，可通过设置vibrate，sound等字段配合实现。
  • 内部字段：
{
    title:''                //标题，Android中默认值为应用名称，支持Android和iOS 8.2以上系统
    content:''              //内容，默认值为'有新消息'
    extra:''                //附加信息，页面可以监听noticeclicked事件得到点击的通知的附加信息
    updateCurrent: false    //是否覆盖更新已有的通知，取值范围true|false。只Android有效
}

alarm：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）设置闹铃。与notify配合使用，即如果设置了闹铃，那么对应的notify将在设定的闹铃时间触发
  • 内部字段：
{
    hour:           //小时，数字类型，取值范围（0-23），默认值为当前系统时
    minutes:        //分钟，数字类型，取值范围（0-59），默认值为当前系统分
    daysOfWeek:     //通知循环时间，以周为单位，数组类型，取值范围[1,2,3,4,5,6,7]，表示周日、周一、周二、周三、周四、周五、周六。若不传则不循环，只在当天或隔天的指定时间通知一次
    time:           //闹铃目标时间，数字类型，1970年至今的毫秒数，只在设定的时间执行一次，若设置了time，那么hour、minutes、daysOfWeek将被忽略
    openApp:        //当闹铃触发时是否打开当前应用，如果打开，则不弹出状态栏通知，bool类型，默认值为false。仅支持Android平台。
}

callback(ret, err)

如果 notification 时传入了 notify或者alarm，那么将收到 callback，返回本次状态栏通知的 id或者闹铃 id，该 id 可用于取消状态栏通知或者闹铃。

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    id:1        //弹出到状态栏通知的id或者设置的闹铃id，可用于取消通知或者闹铃
}

示例代码

//仅震动
api.notification({
    vibrate:[100, 500, 200, 500, 300, 500, 400, 500]
});

//仅提示音
api.notification({
    sound:'default'
});

//提示音+震动
api.notification();

//弹出状态栏通知
api.notification({
    notify: {
    title: '通知标题',
        content: '通知内容'
    }
});

//闹铃
api.notification({
    notify: {
        content: '闹钟'
    },
    //每周一、二、三、四、五的7点30分闹铃
    alarm: {
        hour: 7,
        minutes: 30,
        daysOfWeek: [2, 3, 4, 5, 6]
    }
}, function(ret, err) {
    var id = ret.id;
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

cancelNotification

取消本应用弹出到状态栏的某个或所有通知，也可以清除设定的闹铃

cancelNotification({params})

params

id：

  • 类型：字符串
  • 默认值：0。如果传入-1，则取消本应用弹到状态栏的所有通知，iOS只支持清除所有弹到状态栏的通知；传入-1并不清除闹铃。
  • 描述：（可选项）调用 notification 方法时返回的 id

示例代码

api.cancelNotification({
    id: 1
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

startLocation

调用系统自带定位功能，开始定位

startLocation({params}, callback(ret, err))

params

accuracy：

  • 类型：字符串
  • 默认值：100m
  • 描述：（可选项）定位精度
  • 取值范围
10m      //精度在10米范围内
100m     //精度在100米范围内
1km      //精度在1千米范围内
3km      //精度在3千米范围内

filter：

  • 类型：数字
  • 默认值：1.0
  • 描述：（可选项）位置更新所需最小距离（单位米）

autoStop：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）获取到位置信息后是否自动停止定位

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    longitude:116.213,                   //经度
    latitude:39.213,                     //纬度
    timestamp:1396068155591,             //时间戳
    status: true                         //定位成功
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
    msg:""    //错误描述
}

示例代码

api.startLocation({
    accuracy: '100m',
    filter: 1,
    autoStop: true
}, function(ret, err){
    if(ret && ret.status){
         //获取位置信息成功
    }else{
         alert(JSON.stringify(err));
    }
});

补充说明

本API使用系统自身定位能力进行定位。 Android 上使用的是 Google 的定位服务，因法规政策的原因，在中国基本无法提供服务，因此建议国内开发者使用百度定位模块（baiduLocation）进行定位操作。 iOS上使用的是苹果的定位服务，不受影响。

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

stopLocation

停止定位

stopLocation()

示例代码

api.stopLocation();

补充说明

停止定位

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getLocation

获取位置信息，获取成功后自动停止获取。

若之前已通过 startLocation() 方法进行定位，则直接返回上次定位的数据，否则使用默认设置进行定位

getLocation(callback(ret, err))

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    longitude:116.213,                  //经度
    latitude:39.213,                    //纬度
    timestamp:1396068155591,            //时间戳
    status:true                         //定位成功
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
    msg:""    //错误描述
}

示例代码

api.getLocation(function(ret, err) {
    if (ret && 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：

  • 类型：字符串
  • 默认值：无
  • 描述：传感器类型
  • 取值范围:
accelerometer       //加速计
gyroscope           //陀螺仪
magnetic_field      //地磁传感器
proximity           //近接传感器

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    x:0,                    //x轴分量值
    y:0,                    //y轴分量值
    z:0,                    //z轴分量值
    proximity:true,         //是否接近设备
    status:true             //操作成功状态值
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
    msg:""        //错误描述
}

示例代码

api.startSensor({
    type: 'accelerometer'
}, function(ret, err) {
    if (ret && ret.status) {

    } else {

    }
});

补充说明

开启传感器

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

stopSensor

停止传感器

stopSensor({params})

params

type：

  • 类型：字符串
  • 默认值：无
  • 描述：传感器类型（详见传感器类型常量）

示例代码

api.stopSensor({
    type: 'accelerometer'
});

补充说明

停止传感器

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

call

拨打电话或进行faceTime

call({params})

params

type：

  • 类型：字符串
  • 默认值：tel_prompt
  • 描述：（可选项）打电话类型
  • 取值范围
tel            //直接拨打电话。注：由于系统限制，iOS 10.2以上系统仍会弹出提示框
tel_prompt     //拨打电话之前会弹出提示框
facetime       //facetime通话，Android不支持

number：

  • 类型：字符串
  • 默认值：无
  • 描述：电话号码

示例代码

api.call({
    type: 'tel_prompt',
    number: '10086'
});

补充说明

拨打电话，需要设备有电话功能

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

sms

调用系统短信界面发送短信，或者后台直接发送短信

sms({params}, callback(ret, err))

params

numbers：

  • 类型：字符串数组
  • 默认值：无
  • 描述：电话号码
  • 备注：当调用系统短信界面进行短信发送时，Android仅支持传入一个号码，且发送是否成功的状态值依赖于系统短信界面的返回值

text：

  • 类型：字符串
  • 默认值：无
  • 描述：文本内容

silent：

  • 类型：布尔型
  • 默认值：false
  • 描述：（可选项）是否后台发送，只支持Android
  • 备注：后台发送时，numbers 支持多个，可同时将一条信息发送给多个号码

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    status:true        //发送状态
}

示例代码

api.sms({
    numbers: ['10086'],
    text: '测试短信'
}, function(ret, err) {
    if (ret && ret.status) {
        //已发送
    } else {
        //发送失败
    }
});

补充说明

发送短信，需要设备有短信功能

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

mail

发送邮件

mail({params}, callback(ret, err))

params

recipients：

  • 类型：字符串数组
  • 默认值：无
  • 描述：收件人

subject：

  • 类型：字符串
  • 默认值：无
  • 描述：邮件主题

body：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）邮件内容

attachments：

  • 类型：字符串数组
  • 默认值：无
  • 描述：（可选项）附件地址。支持fs://协议，以及其他模块或者api返回的路径，附件必须是位于设备公共存储空间，系统邮件APP能访问到的存储。

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    status:true           //发送状态
}

示例代码

api.mail({
    recipients: ['test@163.com'],
    subject: '邮件测试',
    body: '这是一封测试用的邮件',
    attachments: ['fs://test.jpg']
}, function(ret, err) {
    if (ret && ret.status) {
        //已发送
    } else {

    }
});

补充说明

需要在手机上面已经配置好邮件账户

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

openContacts

在应用内打开系统通讯录界面选择联系人

openContacts(callback(ret, err))

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：

{
    status:true,             //操作成功状态值
    name:"",                 //姓名
    phone:""                 //电话号码
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
    msg:""    //错误描述
}

示例代码

api.openContacts(function(ret, err) {
    if (ret && ret.status) {
        var name = ret.name;
        var phone = ret.phone;
    } else {

    }
});

补充说明

打开通讯录界面

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setFullScreen

设置是否全屏

setFullScreen({params})

params

fullScreen：

  • 类型：布尔
  • 默认值：无
  • 描述：是否全屏

optNav：

  • 类型：布尔
  • 默认值：false
  • 描述：在全屏时是否同时隐藏/显示虚拟导航栏。仅对带有虚拟导航栏的Android设备有效

animation：

  • 类型：字符串
  • 默认值：fade
  • 描述：（可选项）状态栏显示隐藏的动画效果，只iOS有效
  • 取值范围：
    none        //无动画
fade        //淡入淡出
slide       //上下滑入滑出
  • 可用性：可提供的1.2.73及更高版本

示例代码

api.setFullScreen({
    fullScreen: true
});

补充说明

设置是否全屏

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setStatusBarStyle

设置状态栏样式为白色（适用于深色背景）或黑色（适用于浅色背景），以及设置状态栏背景颜色

setStatusBarStyle({params})

params

style：

  • 类型：字符串
  • 默认值：light
  • 描述：（可选项）状态栏样式，支持iOS，Android支持小米MIUI6.0及以上手机，魅族Flyme4.0及以上手机，其他Android6.0及以上手机。Android因设备厂商定制差异，频繁切换style不一定生效。
  • 取值范围：
    dark        //状态栏字体为黑色，适用于浅色背景
light       //状态栏字体为白色，适用于深色背景

color：

  • 类型：字符串
  • 默认值：#000
  • 描述：（可选项）状态栏背景颜色，只 Android 5.0 及以上有效

animated：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）是否有动画效果，只iOS有效
  • 可用性：可提供的1.2.73及更高版本

示例代码

api.setStatusBarStyle({
    style: 'light'
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setScreenOrientation

设置屏幕旋转方向

setScreenOrientation({params})

params

orientation：

  • 类型：字符串
  • 默认值：无
  • 描述：旋转屏幕到指定方向，或根据重力感应自动旋转；当前为横屏时，若想只在横屏间根据重力切换，则可以传 auto_landscape，竖屏间切换则传 auto_portrait。
  • 取值范围：
    portrait_up              //竖屏时，屏幕在home键的上面
portrait_down            //竖屏时，屏幕在home键的下面，部分手机如iPhone X系列不支持
landscape_left           //横屏时，屏幕在home键的左边
landscape_right          //横屏时，屏幕在home键的右边
auto                     //屏幕根据重力感应在横竖屏间自动切换
auto_portrait            //屏幕根据重力感应在竖屏间自动切换
auto_landscape           //屏幕根据重力感应在横屏间自动切换

    示例代码

api.setScreenOrientation({
    orientation: 'landscape_left'
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setKeepScreenOn

设置是否禁止屏幕休眠

setKeepScreenOn({params})

params

keepOn

  • 类型：布尔
  • 默认值：无
  • 描述：是否禁止屏幕休眠

示例代码

api.setKeepScreenOn({
    keepOn: true
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

toLauncher

回到系统桌面

toLauncher()

示例代码

api.toLauncher();

补充说明

该接口仅Android平台支持。

可用性

Android系统

可提供的1.0.0及更高版本

setScreenSecure

设置是否禁止截屏，只支持Android

setScreenSecure({params})

params

secure

  • 类型：布尔
  • 默认值：无
  • 描述：是否禁止截屏

示例代码

api.setScreenSecure({
    secure: true
});

可用性

Android系统

可提供的1.1.0及更高版本

setAppIconBadge

设置应用图标右上角数字，支持所有 iOS 手机，以及部分 Android 手机，如小米和三星的某些型号，不支持的设备，表现结果为调用该接口无任何效果

setAppIconBadge({params})

params

badge

  • 类型：数字
  • 默认值：无
  • 描述：显示在应用图标右上角的数字。为0时表示清除应用图标上显示的数字

示例代码

api.setAppIconBadge({
    badge: 1
});

可用性

iOS系统

可提供的1.1.0及更高版本

getPhoneNumber

获取本机电话号码，只支持 Android 部分手机

getPhoneNumber({params},callback(ret, err))

params

sync：

  • 类型：布尔
  • 默认值：false
  • 描述：执行结果的返回方式。为false时通过callback返回，为true时直接返回。

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    value:""                 //电话号码，字符串类型
}

示例代码

//异步返回结果：
api.getPhoneNumber(function(ret, err) {
    var phoneNumber = ret.value;
});

//同步返回结果：
var phoneNumber = api.getPhoneNumber({
    sync: true
});

可用性

Android系统

可提供的1.2.0及更高版本

hasPermission

hasPermission提供动态检测应用是否已取得某个或多个权限。

关于动态权限：Android系统自6.0开始，提供了同iOS系统使用体验一致的动态权限机制：对于敏感权限，如获取手机ID | IMEI，访问相册存储，定位，录音，拍照，录像等，需要在APP运行过程中动态向用户申请，用户同意后方可使用相应的功能。Android要求APP目标适配版本（targetSdkVersion）为23及以上（建议设置26及以上），为帮助您更好的使用该接口，论坛维护了一个示例；如何动态申请权限见requestPermission。

权限列表中，类似contacts | contacts-r | contacts-w为权限组合，可以分别申请读写、只读取、只写入权限，如果只需要读取或者写入，则应该使用contacts-r或contacts-w，而不是contacts。

注：该方法为同步方法，方法调用后直接返回结果。

hasPermission({params})

params

list：

  • 类型：字符串数组
  • 默认值：无
  • 描述：权限列表。
  • 取值范围：
camera               //相机/拍照/录像
contacts             //联系人读取/写入
contacts-r           //仅联系人读取。iOS中等同于contacts。
contacts-w           //仅联系人写入。iOS中等同于contacts。
microphone           //使用麦克风录制音频
photos               //访问相册|本地存储空间。Android上等同于storage。
photos-w             //仅写入相册|本地存储空间。Android上等同于storage-w。
location             //定位
locationAlways       //后台定位，只支持iOS
notification         //状态栏通知
calendar             //日历读取/写入。只支持Android
calendar-r           //仅日历读取
calendar-w           //仅日历写入
phone                //直接拨打电话/获取手机号码|IMEI。只支持Android
phone-call           //仅直接拨打电话
phone-r              //仅获取手机号码|IMEI
phone-r-log          //读取通话记录
phone-w-log          //写入通话记录
sensor               //传感器.只支持Android
sms                  //读取短信/后台发送短信。只支持Android
sms-s                //仅后台发送短信
sms-r                //仅读取短信
storage              //读取/写入|相册|多媒体|本地存储空间。只支持Android
storage-r            //仅读取|相册|多媒体|文件|本地存储空间
storage-w            //仅写入|相册|多媒体|文件|本地存储空间

return

  • 类型：JSON对象数组
  • 内部字段：
[{
    name:                 //权限名，字符串类型。
    granted:              //是否允许，如果从未请求过该权限或者用户未做出过选择时将返回false，布尔类型。
    undetermined:         //是否从未请求过该权限或者用户未做出过选择，只支持iOS，注意：请求notification权限时无法获取该状态，布尔类型。
    limited:              //该字段仅photos权限有效，表示访问相册是否有限制，当受限时，应用只能获取到用户在相册选定的那部分资源，只支持iOS 14及以上系统，布尔类型。
    reducedAccuracy:      //该字段仅location、locationAlways有效，返回当前是否为模糊定位，只支持iOS 14及以上系统，布尔类型。在iOS 14以上系统中，用户可以选择只对应用授权模糊定位，如果应用对定位精度要求高，则可以在判断为模糊定位后请求locationFullAccuracy权限，系统将弹出开启精准定位弹框，用户可以再次进行选择。
}]

示例代码

var resultList = api.hasPermission({
    list:['camera']
});
var granted = resultList[0].granted;
api.alert({
    msg: granted?'有权限':'无权限'
});

可用性

iOS系统，Android系统

可提供的1.2.76及更高版本

requestPermission

向系统请求某个或多个权限。为帮助您更好的使用该接口，论坛维护了一个示例。

对于iOS平台，第一次请求权限时会弹出权限选择框，如果用户选择了不允许，那么再次请求权限时将不会再弹出选择框（定位权限如果用户选择了下次询问，则会再次弹出），而是直接跳转到系统设置中该应用的设置界面。

对于Android平台，只要用户没有选择“不再提示”，那么再次请求权限时都将继续弹出权限选择框；如果用户选择了“不再提示”，那么再次请求权限时将不会再弹出选择框，而是直接跳转到系统设置的该应用权限设置界面。

requestPermission({params}, callback(ret,err))

params

list：

  • 类型：字符串数组
  • 默认值：无
  • 描述：权限列表。
  • 取值范围：
camera               //相机/拍照/录像
contacts             //联系人读取/写入
contacts-r           //仅联系人读取。iOS中等同于contacts。
contacts-w           //仅联系人写入。iOS中等同于contacts。
microphone           //使用麦克风录制音频
photos               //访问相册|本地存储空间。Android上等同于storage。
photos-w             //仅写入相册|本地存储空间。Android上等同于storage-w。
location             //定位
locationAlways       //后台定位，只支持iOS
locationFullAccuracy //临时精确定位，请求时需传入purposeKey参数，申请的临时精确定位只在App生命周期内有效。注意：仅当location、locationAlways权限返回的reducedAccuracy字段为true时才请求临时精确定位，若用户继续选择关闭精确定位时回调方法不会被执行，所以此权限应和其它权限分开进行请求。只支持iOS 14及以上系统。
notification         //状态栏通知
calendar             //日历读取/写入。只支持Android
calendar-r           //仅日历读取
calendar-w           //仅日历写入
phone                //直接拨打电话/获取手机号码|IMEI。只支持Android
phone-call           //仅直接拨打电话
phone-r              //仅获取手机号码|IMEI
phone-r-log          //读取通话记录
phone-w-log          //写入通话记录
sensor               //传感器.只支持Android
sms                  //读取短信/后台发送短信。只支持Android
sms-s                //仅后台发送短信
sms-r                //仅读取短信
storage              //读取/写入|相册|多媒体|本地存储空间。只支持Android
storage-r            //仅读取|相册|多媒体|文件|本地存储空间
storage-w            //仅写入|相册|多媒体|文件|本地存储空间

code：

  • 类型：数字
  • 默认值：无
  • 描述：请求跟踪码，用于回调结果，只支持Android。

purposeKey：

  • 类型：字符串
  • 默认值：无
  • 描述：请求locationFullAccuracy权限的意图字段，在云编译界面添加“精确定位（临时）”权限时输入purposeKey及对应的权限使用描述，系统通过purposeKey找到对应的权限使用描述，然后在开启精确定位的弹框中将描述语展示给用户。

callback

ret:

  • 类型：JSON对象
  • 内部字段：
{
    list:[{
        name:              //权限名，字符串类型
        granted:           //是否允许，布尔类型
    }],
    never:                 //用户是否选择了“不再提示“，只支持Android，布尔类型
    code:                  //请求跟踪码，只支持Android，数字类型。
}

示例代码

var permission = 'camera';
var resultList = api.hasPermission({
    list: [permission]
});
if (resultList[0].granted) {
    // 已授权，可以继续下一步操作
    api.alert({
        msg: '已授权'
    });
} else {
    api.confirm({
        msg: '应用需要您的授权才能访问相机',
        buttons: ['取消', '去设置']
    }, function(ret) {
        if (ret.buttonIndex == 2) {
            api.requestPermission({
                list: [permission],
            }, function(res) {
                if (res.list[0].granted) {
                    // 已授权，可以继续下一步操作
                    api.alert({
                        msg: '已授权'
                    });
                }
            });
        }
    });
}

可用性

iOS系统，Android系统

可提供的1.2.76及更高版本

getInterfaceStyle

获取当前设置的用户界面风格，只支持iOS 13及以上系统

getInterfaceStyle()

return：

  • 类型：字符串
  • 描述：当前设置的用户界面风格，取值范围：light、dark

示例代码

var style = api.getInterfaceStyle();

可用性

iOS系统

可提供的1.3.29及更高版本

setInterfaceStyle

设置用户界面风格，只支持iOS 13及以上系统。

通常情况下，应该在config.xml中配置全局的用户界面风格，只有当在应用内提供界面风格切换时使用此方法。

setInterfaceStyle({params})

params

style：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）界面风格，取值范围：light、dark

示例代码

api.setInterfaceStyle({
    style: 'dark'
});

可用性

iOS系统

可提供的1.3.29及更高版本

alert

弹出带一个按钮的对话框，更多按钮的对话框请使用confirm方法

alert({params}, callback(ret, err))

params

title：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）标题

msg：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）内容

buttons：

  • 类型：字符串数组
  • 默认值：["确定"]
  • 描述：（可选项）按钮

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    buttonIndex:1   //按钮点击序号，从1开始
}

示例代码

api.alert({
    title: 'testtitle',
    msg: 'testmsg',
}, function(ret, err) {

});

补充说明

对话框

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

confirm

弹出带两个或三个按钮的confirm对话框

confirm({params}, callback(ret, err))

params

title：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）标题

msg：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）内容

buttons：

  • 类型：字符串数组
  • 默认值：["取消","确定"]
  • 描述：（可选项）按钮标题，若小于两个按钮，会补齐两个按钮；若大于三个按钮，则使用前三个按钮

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    buttonIndex:1   //按钮点击序号，从1开始
}

示例代码

api.confirm({
    title: 'testtitle',
    msg: 'testmsg',
    buttons: ['确定', '取消']
}, function(ret, err) {
    var index = ret.buttonIndex;
});

补充说明

多个按钮的对话框

可用性

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 对象
  • 内部字段：
{
    buttonIndex:1,              //按钮点击序号，从1开始
    text:""                     //输入文字
}

示例代码

api.prompt({
    buttons: ['确定', '取消']
}, function(ret, err) {
    var index = ret.buttonIndex;
    var text = ret.text;
});

补充说明

带输入框的对话框

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

actionSheet

底部弹出框

actionSheet({params}, callback(ret, err))

params

title：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）标题

cancelTitle：

  • 类型：字符串
  • 默认值：取消
  • 描述：（可选项）取消按钮标题

destructiveTitle：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）红色警示按钮标题，一般用于做一些删除之类操作

buttons：

  • 类型：字符串数组
  • 默认值：无
  • 描述：（可选项）其它按钮

style：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）样式设置，不传时使用默认样式
  • 内部字段：
{
    layerColor:'',         //遮蔽层颜色，仅支持rgba颜色，默认值：rgba(0, 0, 0, 0.4)，Android平台仅支持设置alpha即透明度生效
    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 对象
  • 内部字段：
{
    buttonIndex:1        //按钮点击序号，从1开始
}

示例代码

api.actionSheet({
    title: '底部弹出框测试',
    cancelTitle: '这里是取消按钮',
    destructiveTitle: '红色警告按钮',
    buttons: ['1', '2', '3']
}, function(ret, err) {
    var index = ret.buttonIndex;
});

补充说明

底部弹出框

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

showProgress

显示进度提示框

showProgress({params})

params

style：

  • 类型：字符串
  • 默认值：default
  • 描述：（可选项）进度提示框风格
  • 取值范围
default        //默认

animationType：

  • 类型：字符串
  • 默认值：fade
  • 描述：（可选项）进度提示框动画类型
  • 取值范围
fade        //渐隐渐现
zoom        //缩放

title：

  • 类型：字符串
  • 默认值：加载中
  • 描述：（可选项）标题

text：

  • 类型：字符串
  • 默认值：请稍候...
  • 描述：（可选项）内容

modal：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）是否模态，模态时整个页面将不可交互

示例代码

api.showProgress({
    title: '努力加载中...',
    text: '先喝杯茶...',
    modal: false
});

补充说明

显示进度提示框

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

hideProgress

隐藏进度提示框

hideProgress()

示例代码

api.hideProgress();

补充说明

隐藏进度提示框

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

toast

弹出一个定时自动关闭的提示框

toast({params})

params

msg：

  • 类型：字符串
  • 默认值：无
  • 描述：提示消息

duration：

  • 类型：数字
  • 默认值：2000
  • 描述：（可选项）持续时长，单位：毫秒

location：

  • 类型：字符串
  • 默认值：bottom
  • 描述：（可选项）弹出位置，顶部、中间或底部
  • 取值范围:
top         //顶部
middle      //中间
bottom      //底部

global：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）是否是全局的toast。若为false，toast将只在当前window范围可见；若为true，安卓手机上面弹出的位置将会固定在底部区域。

示例代码

api.toast({
    msg: '网络错误',
    duration: 2000,
    location: 'bottom'
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

openPicker

打开时间选择器

openPicker({params}, callback(ret, err))

params

type：

  • 类型：字符串
  • 默认值：无
  • 描述：拾取器类型
  • 取值范围
date           //日期
time           //时间
date_time      //日期和时间，Android不支持

date：

  • 类型：字符串
  • 默认值：当前时间
  • 描述：（可选项）时间格式化字符串，格式yyyy-MM-dd HH:mm

minDate：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）能够选择的最小时间，格式yyyy-MM-dd HH:mm，只iOS有效

maxDate：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）能够选择的最大时间，格式yyyy-MM-dd HH:mm，只iOS有效

title：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）显示在拾取器上面的标题

arrowRect：

  • 类型：JSON 对象
  • 默认值：无
  • 描述：（可选项）iPad中显示时，箭头指向的位置，只iPad有效
  • 内部字段：
{
    x:0,                  //左上角x坐标，数字类型
    y:0,                  //左上角y坐标，数字类型
    w:0,                  //宽度，数字类型
    h:0,                  //高度，数字类型
}

arrowDirection：

  • 类型：字符串
  • 默认值：any
  • 描述：（可选项）iPad中显示时，箭头指向的方向，只iPad有效
  • 取值范围
left         // 指向左边
right        // 指向右边
up           // 指向上边
down         // 指向下边
any          // 系统根据页面情况选择合适的方向

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    year:2000,         //年
    month:1,           //月
    day:1,             //日
    hour:12,           //时
    minute:00          //分
}

示例代码

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
  • 描述：（可选项）是否可见

bgColor：

  • 类型：字符串
  • 默认值：当defaultRefreshHeader为pull时为rgba(187, 236, 153, 1.0)，为swipe时为#fff
  • 描述：（可选项）背景颜色

pathColor：

  • 类型：字符串
  • 默认值：#0F9D58
  • 描述：（可选项）进度条的颜色，defaultRefreshHeader为swipe时生效。

loadingImg：

  • 类型：字符串
  • 默认值：旋转箭头图片
  • 描述：（可选项）上拉下拉时的图片地址，defaultRefreshHeader为pull时生效。

textColor：

  • 类型：字符串
  • 默认值：rgba(109, 128, 153, 1.0)
  • 描述：（可选项）文本颜色，defaultRefreshHeader为pull时生效。

textDown：

  • 类型：字符串
  • 默认值：下拉可以刷新...
  • 描述：（可选项）下拉文字描述，defaultRefreshHeader为pull时生效。

textUp：

  • 类型：字符串
  • 默认值：松开可以刷新...
  • 描述：（可选项）松开时文字描述，defaultRefreshHeader为pull时生效。

textLoading：

  • 类型：字符串
  • 默认值：加载中...
  • 描述：（可选项）加载状态文字描述，defaultRefreshHeader为pull时生效。

textTime：

  • 类型：字符串
  • 默认值：最后更新加日期时间
  • 描述：（可选项）更新时间文字描述，defaultRefreshHeader为pull时生效。

showTime：

  • 类型：布尔
  • 默认值：true
  • 描述：（可选项）是否显示更新时间，defaultRefreshHeader为pull时生效。

callback(ret, err)

ret：

  • 描述：处于下拉刷新状态的回调

err：

  • 描述：错误信息

示例代码

api.setRefreshHeaderInfo({
    loadingImg: 'widget://image/refresh.png',
    bgColor: '#ccc',
    textColor: '#fff',
    textDown: '下拉刷新...',
    textUp: '松开刷新...'
}, function(ret, err) {
    //在这里从服务器加载数据，加载完成后调用api.refreshHeaderLoadDone()方法恢复组件到默认状态

});

补充说明

下拉刷新

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setCustomRefreshHeaderInfo

显示自定义下拉刷新组件。

使用自定义下拉刷新组件之前，需要在config.xml里面配置要使用的自定义下拉刷新模块名称，如：

<preference name="customRefreshHeader" value="UIPullRefresh"/>

或者在使用openWin、openFrame等方法打开页面时传入customRefreshHeader参数来指定。

setCustomRefreshHeaderInfo({params}, callback(ret, err))

params

由对应的自定义下拉刷新模块提供

callback(ret, err)

由对应的自定义下拉刷新模块提供

示例代码

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()

示例代码

api.refreshHeaderLoading();

可用性

iOS系统，Android系统

可提供的1.1.0及更高版本

refreshHeaderLoadDone

通知下拉刷新数据加载完毕，组件会恢复到默认状态

refreshHeaderLoadDone()

示例代码

api.refreshHeaderLoadDone();

补充说明

通知顶部刷新数据加载完毕

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

showFloatBox

展示一个悬浮框，浮动在屏幕上。

showFloatBox({params}, callback)

params

preventDefault：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）是否阻止默认行为，若传true，可以在回调方法里面处理悬浮框点击操作。默认的行为：1、在主widget调用该方法无效 2、点击后会弹出退出应用提示

iconPath：

  • 类型：字符串
  • 默认值：应用图标
  • 描述：（可选项）展示在悬浮框中的图片地址

duration：

  • 类型：字符串
  • 默认值：5000毫秒
  • 描述：（可选项）自动消隐时长。在该时长内不发生触摸悬浮框行为，悬浮框自动消隐至半透状态

callback(ret, err)

ret：

  • 描述：悬浮框点击后的回调
  • 内部字段：
{
    type:'click'        //事件类型，取值范围：click
}

示例代码

api.showFloatBox({
    iconPath: 'widget://image/icon.png',
    duration: 3000
});

补充说明

对主widget无效

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setMenuItems

设置选择文字弹出菜单。

setMenuItems({params}, callback)

params

customItems：

  • 类型：字符串数组
  • 默认值：无
  • 描述：自定义菜单项。自定义菜单项会添加到系统默认菜单项的后面。

systemItems：

  • 类型：字符串数组
  • 默认值：无
  • 描述：（可选项）系统菜单项。如果不传该参数，则会显示系统菜单项，自定义菜单项会添加到系统菜单项后面；如果传空数组，则不显示系统菜单项；如果传了非空数组，则显示传入的系统菜单。注意：不同系统版本的系统默认菜单项可能会有所不同，会存在无法屏蔽某些系统菜单的情况。
  • 取值范围：
copy                // 复制
selectAll           // 全选
_lookup             // 查询
_addShortcut        // 添加...
_share              // 共享...

callback(ret, err)

ret：

  • 描述：自定义菜单项点击后的回调
  • 内部字段：
{
    index:          //点击的自定义菜单项索引，数字类型
    text:           //当前选择的文字，字符串类型
}

示例代码

api.setMenuItems({
    customItems: ['菜单1', '菜单2']
    systemItems: []
}, function(ret, err){
    var index = ret.index;
});

可用性

iOS系统

可提供的1.2.98及更高版本

getPicture

通过调用系统默认相机或者图库应用，获取图片以及视频媒体文件。

getPicture({params}, callback(ret, err))

params

sourceType：

  • 类型：字符串
  • 默认值：library
  • 描述：（可选项）图片源类型，从相册、图片库或相机获取图片
  • 取值范围
library         //图片库
camera          //相机
album           //相册

encodingType：

  • 类型：字符串
  • 默认值：png
  • 描述：（可选项）返回图片类型，jpg或png
  • 取值范围
jpg      //指定图片格式为jpg
png      //指定图片格式为png

mediaValue：

  • 类型：字符串
  • 默认值：pic
  • 描述：（可选项）媒体类型，图片或视频
  • 取值范围
pic        //图片
video      //视频
all        //图片和视频，Android不支持

destinationType：

  • 类型：字符串
  • 默认值：url
  • 描述：（可选项）返回数据类型，指定返回图片地址或图片经过base64编码后的字符串
  • 取值范围
base64      //指定返回数据为base64编码后内容
url         //指定返回数据为选取的图片地址

direction：

  • 类型：字符串
  • 默认值：rear
  • 描述：（可选项）选择前置或后置摄像头，取值范围（front、rear），只支持iOS

allowEdit：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）是否可以选择图片后进行编辑，支持iOS及部分安卓手机

preview：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）是否选择图片后进行预览，只支持iOS。

quality：

  • 类型：数字
  • 默认值：50
  • 描述：（可选项）图片质量，只针对jpg格式图片（0-100整数）

videoQuality：

  • 类型：字符串
  • 默认值：medium
  • 描述：（可选项）视频质量，调用相机录制视频时该参数生效。取值范围(low、medium、high)，质量越高，录制的视频文件占用存储空间越大。

targetWidth：

  • 类型：数字
  • 默认值：原图宽度
  • 描述：（可选项）压缩后的图片宽度，图片会按比例适配此宽度

targetHeight：

  • 类型：数字
  • 默认值：原图高度
  • 描述：（可选项）压缩后的图片高度，图片会按比例适配此高度

saveToPhotoAlbum：

  • 类型：布尔
  • 默认值：false
  • 描述：（可选项）拍照或录制视频后是否保存到系统相册目录。注意此处仅是文件系统层面的操作，使用诸如“图库”App仍然有可能查看到。

groupName：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）保存图片到自定义分组相册目录，相册不存在则会进行创建。
  • 可用性：可提供的1.2.74及更高版本

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    data:"",                //图片路径
    base64Data:"",          //base64数据，destinationType为base64时返回
    duration:0              //视频时长（数字类型）
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
    msg:""    //错误描述
}

示例代码

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://等扩展文件路径协议，本地文件路径必须带有扩展名

groupName：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）保存图片到自定义分组相册目录，相册不存在则会进行创建。
  • 可用性：可提供的1.2.74及更高版本

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    status:true     //是否保存成功
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
    msg:""    //错误描述
}

示例代码

api.saveMediaToAlbum({
    path: 'fs://1.png'
}, function(ret, err) {
    if (ret && ret.status) {
        alert('保存成功');
    } else {
        alert('保存失败');
    }
});

可用性

iOS系统，Android系统

可提供的1.1.0及更高版本

startRecord

录制amr格式音频

startRecord({params})

params

path：

  • 类型：字符串
  • 默认值：无
  • 描述：（可选项）文件路径，不传时自动创建路径

示例代码

api.startRecord({
    path: 'fs://a.amr'
});

补充说明

录音格式为amr

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

stopRecord

停止录音

stopRecord(callback(ret, err))

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    path:'',              //字符串，返回的音频地址
    duration:0            //数字类型，音频的时长
}

示例代码

api.stopRecord(function(ret, err) {
    if (ret) {
        var path = ret.path;
        var duration = ret.duration;
    }
});

补充说明

停止录音

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

startPlay

播放本地音频，支持amr格式

startPlay({params}, callback(ret, err))

params

path：

  • 类型：字符串
  • 默认值：无
  • 描述：文件路径，支持fs://、widget://等文件路径协议

callback(ret, err)

ret

  • 类型：JSON 对象
  • 描述：播放完成的回调

err

  • 类型：JSON 对象
  • 描述：错误信息

示例代码

api.startPlay({
    path: 'widget://res/1.mp3'
}, function(ret, err) {
    if (ret) {
        alert('播放完成');
    } else {
        alert(JSON.stringify(err));
    }
});

补充说明

播放音频

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

stopPlay

停止播放音频

stopPlay()

示例代码

api.stopPlay();

补充说明

停止播放音频

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

openVideo

打开系统视频播放器

openVideo({params})

params

url：

  • 类型：字符串
  • 默认值：无
  • 描述：本地文件路径（支持fs://路径协议）或者网络资源地址

示例代码

api.openVideo({
    url: 'fs://res/1.mp4'
});

补充说明

打开系统视频播放器

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

require

引用模块

require()

示例代码

var bMap = api.require("bMap");

可用性

iOS系统，Android系统