ajax

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