API对象

概述

api 对象是您入门 APICloud 必须了解和熟练掌握的一个基础对象。api 对象提供了构建应用程序所需要的一些基本的方法[Method],如窗口操作、相册和网络数据访问等;以及一些常见的属性[Attrbute],如屏幕宽度(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

系统类型,取值范围详见系统类型常量,字符串类型

示例代码

var systemType = api.systemType;  // 比如: ios

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

systemVersion

手机平台的系统版本,字符串类型

示例代码

var systemVersion = api.systemVersion;  // 比如: 8.0

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

version

引擎版本信息,字符串类型

示例代码

var version = api.version;  //比如: 1.0.0

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

deviceId

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

示例代码

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

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

deviceToken

iOS中用于推送的Token,若未从系统获取到则返回空字符串,字符串类型

示例代码

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

可用性

iOS系统

可提供的1.1.0及更高版本

deviceModel

设备型号,字符串类型

示例代码

var deviceModel = api.deviceModel;  // 比如: iPhone 5

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

deviceName

设备名称,字符串类型

示例代码

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

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

operator

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

示例代码

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

可用性

iOS系统,Android系统

可提供的1.1.0及更高版本

connectionType

当前网络连接类型,如 2g、3g、4g、wifi 等,取值范围详见网络类型常量,字符串类型

示例代码

var connectionType = api.connectionType;  //比如: wifi

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

fullScreen

应用是否全屏,布尔类型,只支持iOS

示例代码

var fullScreen = api.fullScreen;  // 比如: true

可用性

iOS系统

可提供的1.0.0及更高版本

screenWidth

屏幕分辨率宽,数字类型

示例代码

var screenWidth = api.screenWidth;  // 比如: 640

可用性

iOS系统,Android系统

可提供的1.1.0及更高版本

screenHeight

屏幕分辨率高,数字类型

示例代码

var screenHeight = api.screenHeight;  // 比如: 960

可用性

iOS系统,Android系统

可提供的1.1.0及更高版本

winName

当前 window 名称,字符串类型

该属性值为 openWin() 时传递的 name 参数值,注意首页的名称为 root

示例代码

var winName = api.winName;  //比如: root

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

winWidth

当前 window 宽度,数字类型

此属性值不同于屏幕的分辨率,比如 iPhone 5 的分辨率为 640*1136,但是其 winWidth 为 320,因此前端需根据 winWidth 和 winHeight 来进行布局

示例代码

var winWidth = api.winWidth;  // 比如: 320

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

winHeight

当前 window 高度,数字类型

此属性值不同于屏幕的分辨率,比如 iPhone 5 的分辨率为 640*1136,但是其 winHeight 为 568(若不使用iOS7风格则为 548),因此前端需根据 winWidth 和 winHeight 来进行布局

示例代码

var winHeight = api.winHeight;  // 比如: 568

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

frameName

frame 名称,字符串类型

若当前环境为 window 中,则该属性值为空字符串

示例代码

var frameName = api.frameName;  //比如: trans-con

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

frameWidth

frame 宽度,数字类型

若当前环境为 window 中,则值和 winWidth 相同

示例代码

var frameWidth = api.frameWidth;  // 比如: 320

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

frameHeight

frame 高度,数字类型

若当前环境为 window 中,则值和 winHeight 相同

示例代码

var frameHeight = api.frameHeight;  // 比如: 504

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

pageParam

页面参数,JSON 对象类型

用于获取页面间传递的参数值,为 openWin()、openFrame() 等方法中的 pageParam 参数对应值

示例代码

var pageParam = api.pageParam; //比如: {"name" : "tans-con"}

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

wgtParam

widget 参数,JSON 对象类型

用于获取 widget 间传递的参数值,为 openWidget() 方法中的 wgtParam 参数对应值

示例代码

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

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

appParam

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

示例代码

var appParam = api.appParam; // 比如: appLoader

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

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

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                //直接拨打电话
tel_prompt        //iOS拨打电话之前会弹出提示框
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及更高版本

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

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

状态栏通知被用户点击后的回调,字符串类型

callback(ret, err)

ret:

  • 描述:通知被点击后的回调
  • 内部字段:
{
    type:0,            //内容来源类型。取值范围:0-APICloud 收到的推送内容,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及更高版本

openWin

打开window

若 window 已存在,则会把该 window 显示到最前面,如果 url 和之前的 url 有变化,或者 reload 为 true 时,页面会刷新,但是该 window 里面已经打开的 frame 等不会移除

若当前正在进行 openWin、closeWin 等带动画过渡的 window 操作,调用此方法会失效

openWin({params})

params

name:

  • 类型:字符串
  • 默认值:无
  • 描述:window 名字,不能为空字符串

url:

  • 类型:字符串
  • 默认值:无
  • 描述:页面地址,可以为本地文件路径,支持相对路径和绝对路径,以及 widget://、fs://等协议路径,也可以为远程地址

headers:

  • 类型:JSON 对象
  • 默认值:无
  • 描述:(可选项)请求头

useWKWebView:

  • 类型:布尔
  • 默认值:false
  • 描述:(可选项)是否使用WKWebView来加载页面,只支持iOS8.0及以上系统。WKWebView是iOS8新出的WebKit库中的控件,相比于以前的UIWebView,在性能和功能等方面都有所提升。注意使用WKWebView后,localStorage可能不能和其它未使用WKWebView加载的页面通用,同时也不支持方法结果同步返回。

historyGestureEnabled:

  • 类型:布尔
  • 默认值:false
  • 描述:(可选项)是否可以通过手势来进行历史记录前进后退,只在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 有效

vScrollBarEnabled:

  • 类型:布尔
  • 默认值:true
  • 描述:(可选项)是否显示垂直滚动条

hScrollBarEnabled:

  • 类型:布尔
  • 默认值:true
  • 描述:(可选项)是否显示水平滚动条

scaleEnabled:

  • 类型:布尔
  • 默认值:false
  • 描述:(可选项)页面是否可以缩放

slidBackEnabled:

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

slidBackType:

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

animation:

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

showProgress:

  • 类型:布尔
  • 默认值:false
  • 描述:(可选项)是否显示等待框,此参数即将废弃,使用 progress 参数代替。若传了 progress 参数,此参数将忽略

progress:

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

delay:

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

reload:

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

allowEdit:

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

softInputMode:

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

softInputBarEnabled:

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

customRefreshHeader:

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

示例代码

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

补充说明

窗口操作

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

closeWin

关闭 window

若当前正在进行 openWin、closeWin 等带动画过渡的 window 操作,调用此方法会失效

closeWin({params})

params

name:

  • 类型:字符串
  • 默认值:无
  • 描述:(可选项)window 名字,不传时关闭当前 window,为 root 时无效

animation:

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

示例代码

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

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

补充说明

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

closeToWin

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

若当前正在进行 openWin、closeWin 等带动画过渡的 window 操作,调用此方法会失效

closeToWin({params})

params

name:

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

animation:

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

示例代码

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

补充说明

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

setWinAttr

设置 window 属性

setWinAttr({params})

params

bounces:

  • 类型:布尔
  • 默认值:无
  • 描述:(可选项)页面是否弹动

bgColor:

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

scrollToTop:

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

vScrollBarEnabled:

  • 类型:布尔
  • 默认值:无
  • 描述:(可选项)是否显示垂直滚动条

hScrollBarEnabled:

  • 类型:布尔
  • 默认值:无
  • 描述:(可选项)是否显示水平滚动条

scaleEnabled:

  • 类型:布尔
  • 默认值:无
  • 描述:(可选项)页面是否可以缩放

slidBackEnabled:

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

softInputMode:

  • 类型:字符串
  • 默认值:无
  • 描述:(可选项)当键盘弹出时,输入框被盖住时,当前页面的调整方式,详见键盘弹出页面调整方式常量;只iOS有效,Android请在 config.xml 里面配置并云编译使用

示例代码

api.setWinAttr({
    bounces: true,
    bgColor: '#fff',
    vScrollBarEnabled: true,
    hScrollBarEnabled: true,
    scaleEnabled: true,
    slidBackEnabled: true
});

补充说明

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

openFrame

打开 frame

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

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

openFrame({params})

params

name:

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

url:

  • 类型:字符串
  • 默认值:无
  • 描述:页面地址,可以为本地文件路径,支持相对路径和绝对路径,以及widget://、fs://等协议路径,也可以为远程地址

headers:

  • 类型:JSON 对象
  • 默认值:无
  • 描述:(可选项)请求头

useWKWebView:

  • 类型:布尔
  • 默认值:false
  • 描述:(可选项)是否使用WKWebView来加载页面,只支持iOS8.0及以上系统。WKWebView是iOS8新出的WebKit库中的控件,相比于以前的UIWebView,在性能和功能等方面都有所提升。注意使用WKWebView后,localStorage可能不能和其它未使用WKWebView加载的页面通用,同时也不支持方法结果同步返回。

historyGestureEnabled:

  • 类型:布尔
  • 默认值:false
  • 描述:(可选项)是否可以通过手势来进行历史记录前进后退,只在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有效

vScrollBarEnabled:

  • 类型:布尔
  • 默认值:true
  • 描述:(可选项)是否显示垂直滚动条

hScrollBarEnabled:

  • 类型:布尔
  • 默认值:true
  • 描述:(可选项)是否显示水平滚动条

scaleEnabled:

  • 类型:布尔
  • 默认值:false
  • 描述:(可选项)页面是否可以缩放

rect:

  • 类型:JSON 对象
  • 默认值:充满整个父页面
  • 描述:(可选项)frame 的位置和大小,设置 margin 后,在不同手机上面会保持与父页面的各方向边距一致,而中间区域会自动扩充。
  • 内部字段:
{
    x:0,             //左上角x坐标
    y:0,             //左上角y坐标
    w:320,           //宽度,若传'auto',页面从x位置开始自动充满父页面宽度
    h:480            //高度,若传'auto',页面从y位置开始自动充满父页面高度

    marginLeft:0,    //相对父 window 左外边距的距离

    marginTop:0,    //相对父 window 上外边距的距离

    marginBottom:0,    //相对父 window 下外边距的距离

    marginRight:0    //相对父 window 右外边距的距离
}

showProgress:

  • 类型:布尔
  • 默认值:false
  • 描述:(可选项)是否显示等待框,此参数即将废弃,使用 progress 参数代替。若传了 progress 参数,此参数将忽略

progress:

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

reload:

  • 类型:布尔
  • 默认值:false
  • 描述:(可选项)页面已经打开时,是否重新加载页面

allowEdit:

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

softInputMode:

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

softInputBarEnabled:

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

animation:

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

customRefreshHeader:

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

示例代码

api.openFrame({
    name: 'page2',
    url: './page2.html',
    rect: {
        x: 0,
        y: 0,
        w: 320,
        h: 480
    },
    pageParam: {
        name: 'test'
    },
    bounces: true,
    bgColor: 'rgba(0,0,0,0)',
    vScrollBarEnabled: true,
    hScrollBarEnabled: true
});

补充说明

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

closeFrame

关闭frame

closeFrame({params})

params

name:

  • 类型:字符串
  • 默认值:无
  • 描述:(可选项)frame 名字,不传时关闭当前 frame

示例代码

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

补充说明

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

setFrameAttr

设置frame属性

setFrameAttr({params})

params

name:

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

bounces:

  • 类型:布尔
  • 默认值:无
  • 描述:(可选项)页面是否弹动

hidden:

  • 类型:布尔
  • 默认值:无
  • 描述:(可选项)本 frame 是否隐藏(隐藏即从屏幕上移除,但不销毁)

bgColor:

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

scrollToTop:

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

vScrollBarEnabled:

  • 类型:布尔
  • 默认值:无
  • 描述:(可选项)是否显示垂直滚动条

hScrollBarEnabled:

  • 类型:布尔
  • 默认值:无
  • 描述:(可选项)是否显示水平滚动条

scaleEnabled:

  • 类型:布尔
  • 默认值:无
  • 描述:(可选项)页面是否可以缩放

rect:

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

softInputMode:

  • 类型:字符串
  • 默认值:无
  • 描述:(可选项)当键盘弹出时,输入框被盖住时,当前页面的调整方式,详见键盘弹出页面调整方式常量;只iOS有效,Android请在 config.xml 里面配置并云编译使用

示例代码

api.setFrameAttr({
    name: 'page2',
    rect: {
        x: 0,
        y: 0,
        w: 320,
        h: 480
    },
    bounces: true,
    bgColor: '#fff',
    vScrollBarEnabled: true,
    hScrollBarEnabled: true
});

补充说明

设置 frame 属性

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

bringFrameToFront

调整 frame 到前面

bringFrameToFront({params})

params

from:

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

to:

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

示例代码

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
  • 描述:(可选项)动画曲线类型,指定动画开始和结束时的快慢,详见动画曲线类型

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 组打开后,当前页面加载完成后,页面会预加载后面指定个数页面

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

params

name:

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

background:

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

scrollEnabled:

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

rect:

  • 类型:JSON 对象
  • 默认值:充满整个父页面
  • 描述:(可选项)frameGroup 的位置和大小,设置 margin 后,在不同手机上面会保持与父页面的各方向边距一致,而中间区域会自动扩充。
  • 内部字段:
{
    x:0,             //左上角x坐标
    y:0,             //左上角y坐标
    w:320,           //宽度,若传'auto',页面从x位置开始自动充满父页面宽度
    h:480,          //高度,若传'auto',页面从y位置开始自动充满父页面高度

    marginLeft:0,    //相对父window左外边距的距离
    marginTop:0,    //相对父window上外边距的距离
    marginBottom:0,    //相对父window下外边距的距离
    marginRight:0    //相对父window右外边距的距离
}

index:

  • 类型:数字
  • 默认值:0
  • 描述:(可选项)默认显示的页面索引

preload:

  • 类型:数字
  • 默认值:1
  • 描述:(可选项)预加载的 frame 个数,默认加载当前页后面一个

frames:

  • 类型:数组
  • 默认值:无
  • 描述:frame 数组
  • 内部字段:
[{
    name:'',                                //frame名字,字符串类型,不能为空字符串
    url:'',                                 //页面地址,可以为本地文件路径,支持相对路径和绝对路径,以及widget://、fs://等协议路径,也可以为远程地址,字符串类型
    headers:{},                             //(可选项)请求头
    useWKWebView:false,                        //(可选项)是否使用WKWebView来加载页面,只支持iOS8.0及以上系统。WKWebView是iOS8新出的WebKit库中的控件,相比于以前的UIWebView,在性能和功能等方面都有所提升。注意使用WKWebView后,localStorage可能不能和其它未使用WKWebView加载的页面通用,同时也不支持方法结果同步返回。
    historyGestureEnabled:false,            //(可选项)是否可以通过手势来进行历史记录前进后退,只在useWKWebView参数为true时有效。
    pageParam:{},                           //(可选项)页面参数,页面中可以通过api.pageParam获取,JSON对象
    bounces:true,                           //(可选项)是否弹动,布尔型,默认值:若在 config.xml 里面配置了pageBounce,则默认值为配置的值,否则为false
    bgColor:'#fff',                         //(可选项)背景色,支持图片和颜色,格式为#fff、#ffffff、rgba(r,g,b,a)等,图片路径支持fs://、widget://等APICloud自定义文件路径协议,同时支持相对路径
    scrollToTop:true                        //(可选项)当点击状态栏,页面是否滚动到顶部。若当前屏幕上不止一个页面的scrollToTop属性为true,则所有的都不会起作用。默认值:true。只iOS有效
    vScrollBarEnabled:true,                 //(可选项)是否显示垂直滚动条,布尔型,默认值:true
    hScrollBarEnabled:false,                //(可选项)是否显示水平滚动条,布尔型,默认值:false
    scaleEnabled:true,                      //(可选项)页面是否可以缩放,布尔型,默认值:false
    allowEdit:false,                        //(可选项)是否允许长按页面时弹出选择菜单
    softInputMode:'auto'                    //(可选项)当键盘弹出时,输入框被盖住时,当前页面的调整方式,参考键盘弹出页面调整方式常量,只iOS有效
    softInputBarEnabled:false,                //(可选项)是否显示键盘上方的工具条,布尔型,默认值:true,只iOS有效
    customRefreshHeader:''                    //(可选项)设置使用自定义下拉刷新模块的名称,设置后可以使用api.setCustomRefreshHeaderInfo方法来使用自定义下拉刷新组件
}]

callback(ret, err)

ret:

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

示例代码

api.openFrameGroup({
    name: 'group1',
    background: '#fff',
    scrollEnabled: false,
    rect: {
        x: 0,
        y: 0,
        w: 'auto',
        h: 'auto'
    },
    index: 0,
    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 组是否隐藏

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,
    scroll: true
});

补充说明

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

openPopoverWin

iPad 上面打开弹出层窗口,弹出层从底部往上弹出,然后显示在屏幕中间一片指定区域,周围为黑色半透明,只 iPad 上面有效

弹出层是模态的,弹出层后面的界面将不可操作,在弹出层窗口里面不能再打开弹出窗口

弹出层里面页面可以使用所有的 window 和 frame 相关操作,如 openWin、openFrame 等

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

openPopoverWin({params})

params

width:

  • 类型:数字
  • 默认值:540
  • 描述:(可选项)弹出窗口在屏幕中间显示的宽度

height:

  • 类型:数字
  • 默认值:620
  • 描述:(可选项)弹出窗口在屏幕中间显示的高度

name:

  • 类型:字符串
  • 默认值:无
  • 描述:弹出层的第一个 window 的名字,不能为空字符串

url:

  • 类型:字符串
  • 默认值:无
  • 描述:弹出层的第一个 window 页面地址,可以为本地文件路径,支持相对路径和绝对路径,以及 widget://、fs:// 等协议路径,也可以为远程地址,不能为空字符串

pageParam:

  • 类型:JSON 对象
  • 默认值:无
  • 描述:(可选项)页面参数,新页面中可以通过 api.pageParam 获取

bounces:

  • 类型:布尔
  • 默认值:若在 config.xml 里面配置了 pageBounce,则默认值为配置的值,否则为 false
  • 描述:(可选项)页面是否弹动

bgColor:

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

scrollToTop:

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

vScrollBarEnabled:

  • 类型:布尔
  • 默认值:true
  • 描述:(可选项)是否显示垂直滚动条

hScrollBarEnabled:

  • 类型:布尔
  • 默认值:true
  • 描述:(可选项)是否显示水平滚动条

scaleEnabled:

  • 类型:布尔
  • 默认值:false
  • 描述:(可选项)页面是否可以缩放

showProgress:

  • 类型:布尔
  • 默认值:false
  • 描述:(可选项)是否显示等待框,此参数即将废弃,使用 progress 参数代替。若传了 progress 参数,此参数将忽略

progress:

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

allowEdit:

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

softInputMode:

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

softInputBarEnabled:

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

customRefreshHeader:

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

示例代码

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有效
    vScrollBarEnabled:true,             //(可选项)是否显示垂直滚动条,默认true 
    hScrollBarEnabled:true,             //(可选项)是否显示水平滚动条,默认true
    scaleEnabled:true,                  //(可选项)页面是否可以缩放,布尔型,默认值:false
    allowEdit:false,                    //(可选项)是否允许长按页面时弹出选择菜单
    softInputMode:'auto'                //(可选项)当键盘弹出时,输入框被盖住时,当前页面的调整方式,参考键盘弹出页面调整方式常量,只iOS有效
    softInputBarEnabled:false,            //(可选项)是否显示键盘上方的工具条,布尔型,默认值:true,只iOS有效
    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有效
    vScrollBarEnabled:true,             //(可选项)是否显示垂直滚动条,默认true 
    hScrollBarEnabled:true,             //(可选项)是否显示水平滚动条,默认true
    scaleEnabled:true,                  //(可选项)页面是否可以缩放,布尔型,默认值:false
    allowEdit:false,                    //(可选项)是否允许长按页面时弹出选择菜单
    softInputMode:'auto'                //(可选项)当键盘弹出时,输入框被盖住时,当前页面的调整方式,参考键盘弹出页面调整方式常量,只iOS有效
    softInputBarEnabled:false,            //(可选项)是否显示键盘上方的工具条,布尔型,默认值:true,只iOS有效
    customRefreshHeader:''                //(可选项)设置使用自定义下拉刷新模块的名称,设置后可以使用api.setCustomRefreshHeaderInfo方法来使用自定义下拉刷新组件
}

callback(ret, err)

ret:

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

示例代码

api.openSlidLayout({
    type: 'all',
    leftEdge: 80,
    rightEdge: 60,
    fixedPane: {
        name: 'win1',
        url: 'win1.html',
        bgColor: '#fff',
        bounces: true,
        vScrollBarEnabled: true,
        hScrollBarEnabled: false
    },
    slidPane: {
        name: 'win2',
        url: 'win2.html',
        bgColor: '#fff',
        bounces: true,
        vScrollBarEnabled: true,
        hScrollBarEnabled: false
    }
}, function(ret, err) {

});

补充说明

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

openSlidPane

向左或右进行侧滑

openSlidPane({params})

params

type:

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

示例代码

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

name:

  • 类型:字符串
  • 默认值:无
  • 描述:window 名字,不能为空字符串

url:

  • 类型:字符串
  • 默认值:无
  • 描述:页面地址,可以为本地文件路径,支持相对路径和绝对路径,以及 widget://、fs://等协议路径,也可以为远程地址

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有效

vScrollBarEnabled:

  • 类型:布尔
  • 默认值:true
  • 描述:(可选项)是否显示垂直滚动条

hScrollBarEnabled:

  • 类型:布尔
  • 默认值:true
  • 描述:(可选项)是否显示水平滚动条

scaleEnabled:

  • 类型:布尔
  • 默认值:false
  • 描述:(可选项)页面是否可以缩放

slidBackEnabled:

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

slidBackType:

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

animation:

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

showProgress:

  • 类型:布尔
  • 默认值:false
  • 描述:(可选项)是否显示等待框,此参数即将废弃,使用 progress 参数代替。若传了 progress 参数,此参数将忽略

progress:

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

delay:

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

reload:

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

allowEdit:

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

softInputMode:

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

softInputBarEnabled:

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

customRefreshHeader:

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

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有效
    vScrollBarEnabled:true,             //(可选项)是否显示垂直滚动条,默认true 
    hScrollBarEnabled:true,             //(可选项)是否显示水平滚动条,默认true
    scaleEnabled:true,                  //(可选项)页面是否可以缩放,布尔型,默认值:false
    allowEdit:false,                    //(可选项)是否允许长按页面时弹出选择菜单
    softInputMode:'auto',                //(可选项)当键盘弹出时,输入框被盖住时,当前页面的调整方式,参考键盘弹出页面调整方式常量,只iOS有效
    softInputBarEnabled:false,            //(可选项)是否显示键盘上方的工具条,布尔型,默认值:true,只iOS有效
    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有效
    vScrollBarEnabled:true,             //(可选项)是否显示垂直滚动条,默认true 
    hScrollBarEnabled:true,             //(可选项)是否显示水平滚动条,默认true
    scaleEnabled:true,                  //(可选项)页面是否可以缩放,布尔型,默认值:false
    allowEdit:false,                    //(可选项)是否允许长按页面时弹出选择菜单
    softInputMode:'auto'                //(可选项)当键盘弹出时,输入框被盖住时,当前页面的调整方式,参考键盘弹出页面调整方式常量,只iOS有效
    softInputBarEnabled:false,            //(可选项)是否显示键盘上方的工具条,布尔型,默认值:true,只iOS有效
    customRefreshHeader:''                //(可选项)设置使用自定义下拉刷新模块的名称,设置后可以使用api.setCustomRefreshHeaderInfo方法来使用自定义下拉刷新组件
}

示例代码

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

execScript

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

execScript({params})

params

name:

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

frameName:

  • 类型:字符串
  • 默认值:无
  • 描述:(可选项)frame名称

script:

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

示例代码

//在名为winName的window中执行jsfun脚本
var jsfun = 'funcGoto();';
api.execScript({
    name: 'winName',
    script: jsfun
});


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


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

补充说明

统一处理逻辑为:exec->window->frame

name 参数: 当 name 不传值,或者传空字符串的情况下,execScript 对象为调用 execScript 的window(该 window 可能位于屏幕或者后台),在该 window 中继续 frameName 的逻辑; 当 name 传值且非空字符串,但并未找到名为 name 的 window,则直接返回不处理(不论 frameName 是否有值)。若找到了对应的 window,则在该 window 中继续 frameName 的逻辑;

frameName 参数: 当 frameName 不传值,或者传空字符串的情况下,execScript 对象为调用 execScript 的 window(该 window 可能位于屏幕或者后台),在该 window 中执行 script; 当 frameName 传值且非空字符串,但并未找到名为 frameName 的 frame,则直接返回不处理。若找到了该 frame,则在该 frame 中执行 script。

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

historyBack

历史记录后退一页

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

params

frameName:

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

callback(ret, err)

ret:

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

示例代码

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

补充说明

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

historyForward

历史记录前进一页

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

params

frameName:

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

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    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及更高版本

removeLaunchView

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

removeLaunchView({params})

params

animation:

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

示例代码

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

补充说明

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

parseTapmode

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

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

parseTapmode()

示例代码

api.parseTapmode();

补充说明

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

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:

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参数'
    }
});

//Android中的使用方法如下:

api.openApp({
    androidPkg: 'Android.intent.action.VIEW',
    mimeType: 'text/html',
    uri: 'http://www.baidu.com'
}, function(ret, err) {
    if (ret) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

补充说明

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

appInstalled

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

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

params

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 获取

animation:

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

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动画类型subType动画子类型
  • 内部字段:
{
    type:"none",                //动画类型(详见动画类型常量)
    subType:"from_right",       //动画子类型(详见动画子类型常量)
    duration:300                //动画过渡时间,默认300毫秒
}

示例代码

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

补充说明

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

ajax

跨域异步请求,支持文件上传

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

params

url:

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

encode:

  • 类型:布尔
  • 默认值:true
  • 描述:(可选项)是否对url进行编码。传false时底层将不会对url进行编码

tag:

  • 类型:字符串
  • 默认值:无
  • 描述:(可选项)请求标识,可以传递此字段给 cancelAjax 方法来取消请求

method:

  • 类型:字符串
  • 默认值:get
  • 描述:(可选项)异步请求方法类型(详见异步请求方法类型常量)

cache:

  • 类型:布尔
  • 默认值:false
  • 描述:(可选项)是否缓存,若缓存,下次没网络时请求则会使用缓存

timeout:

  • 类型:数字
  • 默认值:30
  • 描述:(可选项)超时时间,单位秒

dataType:

charset:

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

headers:

  • 类型:JSON 对象
  • 默认值:无
  • 描述:(可选项)请求头

report:

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

returnAll:

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

data:

  • 类型:JSON 对象
  • 默认值:无
  • 描述:(可选项)POST 数据,method 为 get 时不传。以下字段除了 values 和 files 可以同时使用,其它参数都不能同时使用。
  • 内部字段:
{
    stream:"",        //文件路径(字符串类型)
    body:"",            //以纯文本的方式提交数据(字符串类型)
    values:{},        //以表单方式提交参数(JSON对象), 如 {"field1": "value1", "field1": "value2"} (直接传JSON对像.)
    files:{}            //以表单方式提交文件,支持多文件上传(JSON对象),如 {"file": "path"},也支持同一字段对应多文件:{"file":["path1","path2"]}。路径支持绝对路径,以及fs://、widget://、cache://等文件路径协议.
}

certificate:

  • 类型:JSON 对象
  • 默认值:无
  • 描述:(可选项)https 安全证书设置。
  • 内部字段:
{
    path:'',                //p12证书路径,支持fs://、widget://、cache://等文件路径协议,字符串类型
    password:''            //证书密码,字符串类型
}

callback(ret, err)

ret:

  • 类型:JSON 对象或字符串
  • 描述:类型依赖于传入的 dataType 和 returnAll
  • 返回上传进度时,原服务器返回数据会被放在body字段里面,内部字段为:
{
    progress: 100,          //上传进度,0.00-100.00
    status: '',             //上传状态,详见上传状态常量
    body: ''                //上传完成时,服务器返回的数据
}

err:

  • 类型:JSON 对象
  • 内部字段:
{
    statusCode: 400,        //网络请求状态码,数字类型
    code:0,                    //错误码(详见异步请求错误码常量),数字类型
    msg:''                    //错误描述,字符串类型
    body:                    //当请求失败如需要权限时,此时服务器返回的数据会通过该参数返回;当要求返回的数据格式为json,而返回的数据不是json格式时,数据通过该参数返回
}

示例代码

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) });
    }
});

补充说明

可用性

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进行编码。传false时底层将不会对url进行编码

savePath:

  • 类型:字符串
  • 默认值:无
  • 描述:(可选项)存储路径,不传时使用自动创建的路径

report:

  • 类型:布尔类型
  • 默认值:false
  • 描述:(可选项)下载过程是否上报

cache:

  • 类型:布尔类型
  • 默认值:true
  • 描述:(可选项)是否使用本地缓存

allowResume:

  • 类型:布尔类型
  • 默认值:false
  • 描述:(可选项)是否允许断点续传

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    fileSize:0,                 //文件大小,数字类型
    percent:0,                  //下载进度(0-100),数字类型
    state:0,                    //下载状态(详见下载状态常量)
    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进行编码。传false时底层将不会对url进行编码

policy:

  • 类型:字符串
  • 默认值:default
  • 描述:(可选项)缓存策略(详见缓存策略常量)

thumbnail:

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

callback(ret, err)

ret:

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

示例代码

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

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:""              //错误描述
}

示例代码

//异步返回结果:
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:""            //错误描述
}

示例代码

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: 'k',
    value: '1'
});

补充说明

可用性

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: 'k'
});

补充说明

删除偏好设置值

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

clearCache

清除缓存,包括下载的文件、拍照临时文件、网页缓存文件等,清除时可能需要消耗一定时间。

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

params

timeThreshold:

  • 类型:数字
  • 默认值:0
  • 描述:(可选项)清除多少天前的缓存

callback(ret, err)

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

示例代码

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

补充说明

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

getCacheSize

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

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

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,数字类型
}

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 事件得到内容

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

params

vibrate:

  • 类型:数组
  • 默认值:[500,500]
  • 描述:(可选项)伴随节奏的震动,时间数组,时间单位为毫秒,iOS上面震动时间为固定值

sound:

  • 类型:字符串
  • 默认值:default
  • 描述:(可选项)提示音,默认为系统提示音。当实现闹钟功能时,iOS只支持widget://路径协议

light:

  • 类型:布尔型
  • 默认值:false
  • 描述:(可选项)设备提示灯是否闪烁

notify:

  • 类型:JSON 对象
  • 默认值:无
  • 描述:(可选项)弹出通知到状态栏
  • 内部字段:
{
    title:''                //标题,默认值为应用名称,只Android有效
    content:''                //内容,默认值为'有新消息'
    extra:''                   //传递给通知的数据,在通知被点击后,该数据将通过监听函数回调给网页
    updateCurrent: false    //是否覆盖更新已有的通知,取值范围true|false。只Android有效
}

alarm:

  • 类型:JSON 对象
  • 默认值:无
  • 描述:(可选项)如果本次通知设置了闹铃,那么该通知将在设定的闹铃时间弹出
  • 内部字段:
{
    hour:            //小时,数字类型,取值范围(0-23),默认值为当前系统时
    minutes:        //分钟,数字类型,取值范围(0-59),默认值为当前系统分
    daysOfWeek:        //通知循环时间,以周为单位,数组类型,如[1,2,3,4,5,6,7]代表周日、周一、周二、周三、周四、周五、周六。若不传则不循环,只在当天或隔天的指定时间通知一次
    time:           //闹铃目标时间,数字类型,1970年至今的毫秒数,只在设定的时间执行一次,若设置了time,那么hour、minutes、daysOfWeek将被忽略
}

callback(ret, err)

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

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    id:1        //弹出到状态栏通知的id,可用于取消通知
}

示例代码

api.notification({
    notify: {
        content: '闹钟'
    },
    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只支持清除所有弹到状态栏的通知。
  • 描述:(可选项)调用 notification 方法时返回的 id

示例代码

api.cancelNotification({
    id: 1
});

补充说明

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

startLocation

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

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

params

accuracy:

  • 类型:字符串
  • 默认值:100m
  • 描述:(可选项)定位精度(详见定位精度常量)

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:

  • 类型:字符串
  • 默认值:无
  • 描述:传感器类型(详见传感器类型常量)

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
  • 描述:(可选项)打电话类型(详见电话类型常量)

number:

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

示例代码

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

补充说明

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

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

sms

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

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

params

numbers:

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

text:

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

silent:

  • 类型:布尔型
  • 默认值:false
  • 描述:(可选项)是否后台发送,iOS不支持
  • 备注:后台发送时,numbers 支持多个,可同时将一条信息发送给多个号码

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    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:

  • 类型:数组
  • 默认值:无
  • 描述:(可选项)附件地址

callback(ret, err)

ret:

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

示例代码

api.mail({
    recipients: ['test@163.com'],
    subject: '邮件测试',
    body: '这是一封测试用的邮件',
    attachments: ['widget://a.txt']
}, 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:

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

示例代码

api.setFullScreen({
    fullScreen: true
});

补充说明

设置是否全屏

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

setStatusBarStyle

设置状态栏样式为白色(适用于深色背景)或黑色(适用于浅色背景),以及设置状态栏背景颜色

setStatusBarStyle({params})

params

style:

  • 类型:字符串
  • 默认值:light
  • 描述:(可选项)状态栏样式(详见状态栏样式常量),支持iOS,Android支持小米MIUI6.0及以上手机,魅族Flyme4.0及以上手机,其他Android6.0及以上手机。

color:

  • 类型:字符串
  • 默认值:#000
  • 描述:(可选项)状态栏背景颜色,只 Android 5.0 及以上有效

示例代码

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

补充说明

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

setScreenOrientation

设置屏幕旋转方向

setScreenOrientation({params})

params

orientation:

  • 类型:字符串
  • 默认值:无
  • 描述:旋转屏幕到指定方向,或根据重力感应自动旋转;当前为横屏时,若想只在横屏间根据重力切换,则可以传 auto_landscape,竖屏间切换则传 auto_portrait。详见屏幕旋转方向常量

示例代码

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

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)
    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
  • 描述:(可选项)进度提示框风格(详见进度提示框风格常量)

animationType:

title:

  • 类型:字符串
  • 默认值:加载中
  • 描述:(可选项)标题

text:

  • 类型:字符串
  • 默认值:请稍候...
  • 描述:(可选项)内容

modal:

  • 类型:布尔
  • 默认值:true
  • 描述:(可选项)是否模态,模态时整个页面将不可交互

示例代码

api.showProgress({
    style: 'default',
    animationType: 'fade',
    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
  • 描述:(可选项)弹出位置,顶部、中间或底部(详见toast位置常量)

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:

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

title:

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

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
  • 描述:(可选项)是否可见

loadingImg:

  • 类型:字符串
  • 默认值:旋转箭头图片
  • 描述:(可选项)上拉下拉时的图片地址

bgColor:

  • 类型:字符串
  • 默认值:rgba(187, 236, 153, 1.0)
  • 描述:(可选项)背景颜色

textColor:

  • 类型:字符串
  • 默认值:rgba(109, 128, 153, 1.0)
  • 描述:(可选项)文本颜色

textDown:

  • 类型:字符串
  • 默认值:下拉可以刷新...
  • 描述:(可选项)下拉文字描述

textUp:

  • 类型:字符串
  • 默认值:松开可以刷新...
  • 描述:(可选项)松开时文字描述

textLoading:

  • 类型:字符串
  • 默认值:加载中...
  • 描述:(可选项)加载状态文字描述

textTime:

  • 类型:字符串
  • 默认值:最后更新加日期时间
  • 描述:(可选项)更新时间文字描述

showTime:

  • 类型:布尔
  • 默认值:true
  • 描述:(可选项)是否显示更新时间

callback(ret, err)

ret:

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

err:

  • 描述:错误信息

示例代码

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

});

补充说明

下拉刷新

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

setCustomRefreshHeaderInfo

显示顶部自定义下拉刷新组件,页面必须设置为弹动。

可以在config.xml里面配置要使用的自定义下拉刷新模块名称,如:

<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

展示一个悬浮框,浮动在屏幕上,点击时关闭当前widget

showFloatBox({params})

params

iconPath:

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

duration:

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

示例代码

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

补充说明

对主widget无效

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

getPicture

通过系统相册或拍照获取图片和视频

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

params

sourceType:

  • 类型:字符串
  • 默认值:library
  • 描述:(可选项)图片源类型,从相册、图片库或相机获取图片(详见图片源类型常量)

encodingType:

  • 类型:字符串
  • 默认值:png
  • 描述:(可选项)返回图片类型,jpg或png(详见图片编码类型常量)

mediaValue:

  • 类型:字符串
  • 默认值:pic
  • 描述:(可选项)媒体类型,图片或视频(详见媒体类型常量)

destinationType:

  • 类型:字符串
  • 默认值:url
  • 描述:(可选项)返回数据类型,指定返回图片地址或图片经过base64编码后的字符串(详见图片数据格式常量)

direction:

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

allowEdit:

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

quality:

  • 类型:数字
  • 默认值:50
  • 描述:(可选项)图片质量,只针对jpg格式图片(0-100整数)

videoQuality:

  • 类型:字符串
  • 默认值:medium
  • 描述:(可选项)视频质量,取值范围(low、medium、high),只支持iOS

targetWidth:

  • 类型:数字
  • 默认值:原图宽度
  • 描述:(可选项)压缩后的图片宽度,图片会按比例适配此宽度

targetHeight:

  • 类型:数字
  • 默认值:原图高度
  • 描述:(可选项)压缩后的图片高度,图片会按比例适配此高度

saveToPhotoAlbum:

  • 类型:布尔
  • 默认值:false
  • 描述:(可选项)拍照或录制视频后是否保存到相册

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://等文件路径协议,必须带有扩展名

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

开始播放音频

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://、widget://等文件路径协议)或者网络资源地址

示例代码

api.openVideo({
    url: 'widget://res/1.mp4'
});

补充说明

打开系统视频播放器

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

require

引用模块

require()

示例代码

var bMap = api.require("bMap");

可用性

iOS系统,Android系统