xe-ajax
简体中文 | English
基于 fetch API 的异步请求函数,用于浏览器和 nodejs 的 http 客户端
Browser Support
xe-ajax 依赖 Promise,如果您的环境不支持 Promise,使用 babel-polyfill 或者 bluebird.js
8+ ✔ | Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | 6.1+ ✔ |
Installing
npm install xe-ajax
Using nodejs
const XEAjax =
<script src="https://cdn.jsdelivr.net/npm/xe-ajax"></script>
API
- 核心
- 便捷函数 1
- 便捷函数 2
Request
*: 只支持现代的浏览器。
参数 | 类型 | 描述 | 默认值 |
---|---|---|---|
url | String | 请求地址 | |
baseURL | String | 基础路径 | |
method | String | 请求方法 | 'GET' |
params | Object | 表单查询参数 | |
body | Object | 提交主体内容 | |
bodyType | String | 提交主体内容方式,可以设置json-data,form-data | 'json-data' |
mode | String | 请求的模式, 可以设置cors,no-cors,same-origin | 'cors' |
cache | String | 处理缓存方式,可以设置default,no-store,no-cache,reload,force-cache,only-if-cached | 'default' |
credentials | String | 设置 cookie 是否随请求一起发送,可以设置: omit,same-origin,include | 'same-origin' |
jsonp | String | jsonp入参属性名 | 'callback' |
jsonpCallback | String | jsonp响应结果的回调函数名 | 默认自动生成函数名 |
timeout | Number | 设置请求超时 | |
headers | Object | 请求头包含信息 | |
origin | String | 请求目标源 | location.origin |
transformParams | Function (params,request) | 用于改变URL参数 | |
paramsSerializer | Function (params,request) | 自定义URL序列化函数 | |
transformBody | Function (body,request) | 用于改变提交数据 | |
stringifyBody | Function (body,request) | 自定义转换提交数据的函数 | |
validateStatus | Function (response) | 自定义校验请求是否成功 | 默认200-299 |
*redirect | String | 重定向模式, 可以设置follow,error,manual | 'follow' |
*referrer | String | 可以设置no-referrer,client或URL | 'client' |
*referrerPolicy | String | 可以设置: no-referrer,no-referrer-when-downgrade,origin,origin-when-cross-origin,unsafe-url | |
*keepalive | String | 选项可用于允许请求超过页面的生存时间 | |
*integrity | String | 包括请求的subresource integrity值 |
Headers
属性 | 类型 | 描述 |
---|---|---|
set | Function (name,value) | 添加 |
append | Function (name,value) | 追加 |
get | Function (name) | 根据 name 获取 |
has | Function (name) | 检查 name 是否存在 |
delete | Function (name) | 根据 name 删除 |
keys | Function | 以迭代器的形式返回所有 name |
values | Function | 以迭代器的形式返回所有 value |
entries | Function | 以迭代器的形式返回所有 [name, value] |
forEach | Function (callback,context) | 迭代器 |
Response
属性 | 类型 | 描述 |
---|---|---|
body | ReadableStream | 返回一个只读的数据流 |
bodyUsed | Boolean | 返回一个只读的布尔值,表示内容是否已被读取 |
headers | Headers | 返回一个只读的响应头对象 |
status | Number | 返回一个只读的响应状态码 |
statusText | String | 返回一个只读的与状态码相对应的状态消息 |
url | String | 返回一个只读的请求路径 |
ok | Boolean | 返回一个只读的布尔值,表示响应是否成功 |
redirected | Boolean | 返回一个只读的布尔值,表示响应是否为重定向请求的结果 |
type | String | 返回一个只读的响应的类型 |
clone | Function | 复制一个新的 Response 对象 |
json | Function | 返回一个内容为 JSON 的 Promise 对象 |
text | Function | 返回一个内容为 Text 的 Promise 对象 |
blob | Function | 返回一个内容为 Blob 的 Promise 对象 |
arrayBuffer | Function | 返回一个内容为 ArrayBuffer 的 Promise 对象 |
formData | Function | 返回一个内容为 FormData 的 Promise 对象 |
全局参数设置
XEAjax
示例
基本使用
const XEAjax = XEAjax
fetch 调用,返回一个结果为 Response 的 Promise 对象
XEAjax // Response TextXEAjax // Response JSONXEAjax // Response BlobXEAjax // Response ArrayBufferXEAjax // Response FormDataXEAjax // 使用 "application/json" 方式提交let body1 = name: 'u111' content: '123456'XEAjax // 使用 "application/x-www-form-urlencoded" 方式提交let body2 = name: 'u222' content: '123456'XEAjax // 使用 "application/x-www-form-urlencoded" 方式提交let searchParams = ;searchParams;searchParams;XEAjax; // 使用 "multipart/form-data" 方式提交let file = documentfiles0let formData = formDataXEAjax // 查询参数和数据同时提交XEAjax XEAjaxXEAjaxXEAjax
根据请求状态码(成功或失败),返回一个包含响应信息的 Peomise 对象 (v3.4.0+)
// 对请求的响应包含以下信息// result => {data, status, statusText, headers} // 根据 validateStatus 状态校验判断完成还是失败XEAjax XEAjaxXEAjaxXEAjaxXEAjax
根据请求状态码(成功或失败),返回响应结果为 JSON 的 Peomise 对象
// 根据 validateStatus 状态校验判断完成还是失败,直接可以获取响应结果XEAjax XEAjaxXEAjaxXEAjaxXEAjax
jsonp 调用
// 例子1// 请求路径: https://test.com/jsonp/test/message/list?callback=jsonp_xeajax_1521272815608_1// 服务端返回结果: jsonp_xeajax_1521272815608_1([...])XEAjax // 例子2// 请求路径: https://test.com/jsonp/test/message/list?cb=jsonp_xeajax_1521272815608_2// 服务端返回结果: jsonp_xeajax_1521272815608_2([...])XEAjax // 例子3// 请求路径: https://test.com/jsonp/test/message/list/page/10/1?id=222&cb=func// 服务端返回结果: func({page: {...}, result: [...])XEAjax
并发多个请求
// 并发多个Promiseall XEAjax XEAjax XEAjax name: 'n1') // 竞速,哪个先请求完成执行哪个Promise // doAll 使用对象参数, 用法和 Promise.all 一致let iterable2 = iterable2iterable2XEAjax
嵌套请求
// 相互依赖的嵌套请求XEAjax XEAjax XEAjax
使用 async/await 处理异步
{ let list = await XEAjax let data = await XEAjax console console}
上传/下载 (v3.4.9+)
参数
属性 | 类型 | 描述 |
---|---|---|
onUploadProgress | Function (event) | 上传进度监听 |
onDownloadProgress | Function (event) | 下载进度监听 |
meanSpeed | Number | 默认0关闭,设置速率为均衡模式,每隔多少毫秒内计算平均速率 |
fixed | Number | 默认2位数 |
Progress 对象
属性 | 类型 | 描述 |
---|---|---|
autoCompute | Boolean | 是否自动计算进度,默认true |
value | Number | 当前进度 % |
loaded | Object | 已传输大小 {value: 原始大小B, size: 转换后大小, unit: 转换后单位} |
total | Object | 总大小 {value: 原始大小B, size: 转换后大小, unit: 转换后单位} |
speed | Object | 传输速度/秒 {value: 原始大小B, size: 转换后大小, unit: 转换后单位} |
remaining | Number | 剩余时间/秒 |
time | Number | 时间戳 |
// 上传、下载let file = documentfiles0let formBody = formBodyXEAjaxXEAjaxXEAjax // 上传进度// 创建一个进度监听对象let progress = // 监听上传进度progress { let value = progressvalue let loadedSize = progressloadedsize let loadedUnit = progressloadedunit let totalSize = progresstotalsize let totalUnit = progresstotalunit let speedSize = progressspeedsize let speedUnit = progressspeedunit let remaining = progressremaining console}let file = documentfiles0let formBody = formBodyXEAjax// 进度:1% 176KB/14.26MB; 速度:1.69MB/秒; 剩余:8秒// 进度:3% 368KB/14.26MB; 速度:640KB/秒; 剩余:22秒// 进度:8% 1.16MB/14.26MB; 速度:1.56MB/秒; 剩余:8秒// ...// 进度:99% 14.08MB/14.26MB; 速度:119.6KB/秒; 剩余:2秒// 进度:100% 14.26MB/14.26MB; 速度:114.4KB/秒; 剩余:0秒 // 下载进度// 创建一个进度监听对象let progress = // 监听下载进度progress { let value = progressvalue let loadedSize = progressloadedsize let loadedUnit = progressloadedunit let totalSize = progresstotalsize let totalUnit = progresstotalunit let speedSize = progressspeedsize let speedUnit = progressspeedunit let remaining = progressremaining console}XEAjax
取消请求 (v3.2.0+)
AbortController 控制器对象
允许控制一个或多个取消指令请求
// 创建一个控制器对象let controller = // 获取signallet signal = controllersignal// 给请求加入控制器 signalXEAjax
拦截器 (v3.0+)
拦截器可以对请求之前和请求之后的任何参数以及数据做处理,注意要调用next执行下一步,否则将停止执行。
Request 拦截器
XEAjax.interceptors.request.use(Function(request, next))
// 请求之前拦截器XEAjaxinterceptorsrequest
Response 拦截器
XEAjax.interceptors.response.use(Function(response, next[, request]), Function(response, next[, request]))
next( [, newResponse] )
属性 | 类型 | 描述 |
---|---|---|
status | Number | 设置响应的状态码 |
statusText | String | 设置与状态码对应的状态消息 |
body | Object | 设置响应主体内容 |
headers | Headers、Object | 设置响应的头信息 |
// 请求完成之后拦截XEAjaxinterceptorsresponse // 请求完成之后改变响应结果XEAjaxinterceptorsresponse
mixin ( fns ) 扩展函数
扩展自己的实用函数到 XEAjax
XEAjax XEAjaxXEAjaxXEAjaxXEAjax
License
MIT © 2017-present, Xu Liangzhan