xe-ajax

简体中文 | English


fetch API based asynchronous request function for the browser and node.js HTTP client.

Browser Support

xe-ajax Depends on a native Promise implementation to be supported. If your environment doesn't support Promises, you can babel-polyfill or bluebird.js.

!IE | !Edge | !Chrome | !Firefox | !Opera | !Safari
--- | --- | --- | --- | --- | --- |
8+ ✔ | Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | 6.1+ ✔ |

Installing

``shell
npm install xe-ajax --save
`

`javascript
import XEAjax from 'xe-ajax'
import XEAjaxMock from 'xe-ajax-mock'

XEAjax.use(XEAjaxMock)
`

Using nodejs

`javascript
const XEAjax = require('xe-ajax')
`

Get on unpkg and cdnjs

`javascript

`

API

* Core
* ajax ( request )
* [fetch ( url[, request] )](#fetch-to-response)
* Function 1
* [doJsonp ( url[, params, request] )](#jsonp)
* [doGet ( url[, params, request] )](#fetch-to-response-schema-v340)
* [doPost ( url[, body, request] )](#fetch-to-response-schema-v340)
* Function 2
* [jsonp ( url[, params, request] )](#jsonp)
* [get ( url[, params, request] )](#fetch-to-json)
* [post ( url[, body, request] )](#fetch-to-json)

$3

*: Only modern browsers are supported.

| Name | Type | Description | default value |
|------|------|-----|----|
| url | String | Request interface contains the URL of the request. | |
| baseURL | String | Request base URL | |
| method | String | The method read-only property of the Request interface contains the request's method | 'GET' |
| params | Object | Request the params contents. | |
| body | Object | Request the body contents. | |
| bodyType | String | Submit type, You can set: json-data,form-data | 'json-data' |
| mode | String | The mode you want to use for the request, You can set: cors,no-cors,same-origin | 'cors' |
| cache | String | Handling cache mode, You can set: default,no-store,no-cache,reload,force-cache,only-if-cached | 'default' |
| credentials | String | Set the cookie to be sent along with the request, You can set: omit,same-origin,include | 'same-origin' |
| jsonp | String | set jsonp Callback parameter name. | 'callback' |
| jsonpCallback | String | Set jsonp callback function name. | Default is a random number with json_xeajax_ prefix |
| timeout | Number | Setting the request timeout. | |
| headers | Object | Optional header fields. | {'Accept': 'application/json, text/plain, /'} |
| origin | String | Change the origin. | location.origin |
| transformParams | Function (params,request) | Change the URL parameter before sending the request. | |
| paramsSerializer | Function (params,request) | The custom URL serialization function is finally spliced in the URL. | XEAjax.serialize |
| transformBody | Function (body,request) | Change the commit body before sending the request. | |
| stringifyBody | Function (body,request) | Customize the body stringify function. | JSON.stringify |
| validateStatus | Function (response) | Verify that the request is successful. | 200-299 |
| *redirect | String | The redirect mode to use, You can set: follow,error,manual | 'follow' |
| *referrer | String | Specifies the value of the referer HTTP header. You can set: no-referrer,client,URL | 'client' |
| *referrerPolicy | String | You can set: no-referrer,no-referrer-when-downgrade,origin,origin-when-cross-origin,unsafe-url | |
| *keepalive | String | The keepalive option can be used to allow the request to outlive the page. | |
| *integrity | String | Contains the subresource integrity value of the request. | |

$3

| Name | Type | Description |
|------|------|-----|
| set | Function (name,value) | Sets a new value for an existing header inside a Headers object, or adds the header if it does not already exist. |
| append | Function (name,value) | Appends a new value onto an existing header inside a Headers object, or adds the header if it does not already exist. |
| get | Function (name) | Returns a ByteString sequence of all the values of a header within a Headers object with a given name. |
| has | Function (name) | Returns a boolean stating whether a Headers object contains a certain header. |
| delete | Function (name) | Deletes a header from a Headers object. |
| keys | Function | Returns an iterator allowing you to go through all keys of the key/value pairs contained in this object. |
| values | Function | Returns an iterator allowing you to go through all values of the key/value pairs contained in this object. |
| entries | Function | Returns an iterator allowing to go through all key/value pairs contained in this object. |
| forEach | Function (callback,context) | Executes a provided function once for each array element. |

$3

| Name | Type | Description |
|------|------|-----|
| body | ReadableStream | The body read-only property of the Body mixin is a simple getter used to expose a ReadableStream of the body contents. |
| bodyUsed | Boolean | The bodyUsed read-only property of the Body mixin contains a Boolean that indicates whether the body has been read yet. |
| headers | Headers | The headers read-only property of the Response interface contains the Headers object associated with the response. |
| status | Number | The status read-only property of the Response interface contains the status code of the response. |
| statusText | String | The statusText read-only property of the Response interface contains the status message corresponding to the status code. |
| url | String | The url read-only property of the Response interface contains the URL of the response. The value of the url property will be the final URL obtained after any redirects. |
| ok | Boolean | The ok read-only property of the Response interface contains a Boolean stating whether the response was successful. |
| redirected | Boolean | The read-only redirected property of the Response interface indicates whether or not the response is the result of a request you made which was redirected. |
| type | String | The type read-only property of the Response interface contains the type of the response. |
| clone | Function | Creates a clone of a Response object. |
| json | Function | Takes a Response stream and reads it to completion. It returns a promise that resolves with the result of parsing the body text as JSON. |
| text | Function | Takes a Response stream and reads it to completion. It returns a promise that resolves with a USVString (text). |
| blob | Function | Takes a Response stream and reads it to completion. It returns a promise that resolves with a Blob. |
| arrayBuffer | Function | Takes a Response stream and reads it to completion. It returns a promise that resolves with an ArrayBuffer. |
| formData | Function | Takes a Response stream and reads it to completion. It returns a promise that resolves with a FormData object. |

Default Global Settings

`JavaScript
import XEAjax from 'xe-ajax'

XEAjax.setup({
// origin: 'https://test.com',
// baseURL: 'https://test.com',
bodyType: 'json-data',
credentials: 'include',
headers: {
'Accept': 'application/json, text/plain, \/\;'
},
validateStatus (response) {
return response.status >= 200 && response.status < 300
},
transformParams (params, request) {
if (request.method === 'GET') {
params.queryDate = params.queryDate.getTime()
}
return params
},
paramsSerializer (params, request) {
return XEUtils.serialize(params)
}，
transformBody (body, request) {
body.startTime = body.startDate.getTime()
return body
},
stringifyBody (body, request) {
return JSON.stringify(body)
}
})
`

Examples

$3

`JavaScript
const XEAjax = require('xe-ajax')

XEAjax.ajax({
url: '/api/test/message/list',
method: 'GET',
params: {
id: 1
}
})
.then(response => {
if (response.ok) {
// success
} else {
// failed
}
}).catch(e => {
// error
console.log(e.message)
})
`

$3

`JavaScript
import XEAjax from 'xe-ajax'

XEAjax.fetch('/api/test/message/save', {
method: 'POST',
body: {
name: 'test'
}
})
.then(response => {
if (response.ok) {
// success
} else {
// failed
}
}).catch(e => {
// error
console.log(e.message)
})

// Response Text
XEAjax.fetch('/api/test/message/list')
.then(response => {
response.text().then(text => {
// text
})
})

// Response JSON
XEAjax.fetchGet('/api/test/message/list')
.then(response => {
response.json().then(data => {
// data
})
})

// Response Blob
XEAjax.fetch('/api/test/message/list')
.then(response => {
response.blob().then(blob => {
// blob
})
})

// Response ArrayBuffer
XEAjax.fetch('/api/test/message/list')
.then(response => {
response.arrayBuffer().then(arrayBuffer => {
// arrayBuffer
})
})

// Response FormData
XEAjax.fetch('/api/test/message/list')
.then(response => {
response.formData().then(formData => {
// formData
})
})

// Submit 'application/json'
let body1 = {
name: 'u111',
password: '123456'
}
XEAjax.fetchPost('/api/test/message/save', body1, {bodyType: 'json-data'})

// Submit 'application/x-www-form-urlencoded'
let body2 = {
name: 'u222',
password: '123456'
}
XEAjax.fetchPost('/api/test/message/save', body2, {bodyType: 'form-data'})

// Submit "application/x-www-form-urlencoded"
let searchParams = new URLSearchParams();
searchParams.append('name', 'u222');
searchParams.append('content', '123456');
XEAjax.fetchPost('/api/test/message/save', searchParams);

// Submit 'multipart/form-data'
let file = document.querySelector('#myFile').files[0]
let formData = new FormData()
formData.append('file', file)
XEAjax.fetchPost('/api/test/message/save', formData)

// Submit body and query params.
XEAjax.fetchPost('/api/test/message/save', {name: 'u333',password: '123456'}, {params: {id: 111}})

XEAjax.fetchGet('/api/test/message/list')
XEAjax.fetchPut('/api/test/message/update', {name: 'u222'})
XEAjax.fetchDelete('/api/test/message/delete/1')
`

$3

`JavaScript
import XEAjax from 'xe-ajax'

// The response for a request contains the following information.
// Result => {data, status, statusText, headers}

// The completion or failure is based on state check.
XEAjax.doGet('/api/test/message/list').then(result => {
// success result.data
}).catch(result => {
// failed
})

XEAjax.doGet('/api/test/message/list/page/15/1')
XEAjax.doPost('/api/test/message/save', {name: 'u111'})
XEAjax.doPut('/api/test/message/update', {name: 'u222'})
XEAjax.doDelete('/api/test/message/delete/1')
`

$3

`JavaScript
import XEAjax from 'xe-ajax'

// The completion or failure is based on state check.
XEAjax.get('/api/test/message/list').then(data => {
// success
}).catch(data => {
// failed
})

XEAjax.get('/api/test/message/list/page/15/1').then(({page, result}) => {
// success
})

XEAjax.post('/api/test/message/save', {name: 'test'})
XEAjax.post('/api/test/message/save', {name: 'test', password: '123456'}, {bodyType: 'json-data'})
XEAjax.post('/api/test/message/save', {name: 'test', password: '123456'}, {bodyType: 'form-data'})

let file = document.querySelector('#myFile').files[0]
let formBody = new FormData()
formBody.append('file', file)
XEAjax.post('/api/test/message/save', formBody)
`

$3

`JavaScript
import XEAjax from 'xe-ajax'

// Case 1:
// http://test.com/api/jsonp/public/message?callback=jsonp_xeajax_1521272815608_1
// jsonp_xeajax_1521272815608_1({message: 'success'})
XEAjax.fetchJsonp('/api/jsonp/public/message')
.then(response => {
if (response.ok) {
response.json().then(data => {
// data
})
}
})

// Case 2:
// http://test.com/api/jsonp/public/message?cb=jsonp_xeajax_1521272815608_2
// jsonp_xeajax_1521272815608_2({message: 'success'})
XEAjax.doJsonp('/api/jsonp/public/message', null, {jsonp: 'cb'})
.then(response => {
// response.data
})

// Case 3:
// http://test.com/api/jsonp/public/message?id=222&cb=func
// func({message: 'success'})
XEAjax.jsonp('/api/jsonp/public/message', {id: 222}, {jsonp: 'cb',jsonpCallback: 'func'})
.then(data => {
// data
})
`

$3

`JavaScript
import XEAjax from 'xe-ajax'

Promise.all([
XEAjax.fetchGet('/api/test/message/list'),
XEAjax.doGet('/api/test/message/list'),
XEAjax.post('/api/test/message/save'), {name: 'n1'})
]).then(datas => {
// all finish
}).catch(e => {
// error
})

Promise.race([
XEAjax.get('/api/test/message/list'),
XEAjax.get('/api/test/message/list')
]).then(datas => {
// finish
}).catch(e => {
// error
})

// doAll Use object parameters, The use is consistent with that of Promise.
let iterable2 = []
iterable2.push({url: '/api/test/message/list'})
iterable2.push({url: '/api/test/message/save', body: {name: 'n1'}}, method: 'POST'})
XEAjax.doAll(iterable2).then(datas => {
// all finish
}).catch(e => {
// error
})
`

$3

`JavaScript
import XEAjax from 'xe-ajax'

// This should be avoided in the project.
XEAjax.fetchGet('/api/test/message/info', {id: 3})
.then(response => response.json())
.then(data => XEAjax.fetchGet(/api/test/message/delete/${data.id}))
.then(response => {
if (response.ok) {
response.json().then(data => {
// data
})
}
})
XEAjax.doGet('/api/test/message/info', {id: 3})
.then(result => XEAjax.doGet(/api/test/message/delete/${result.data.id}))
.then(result => {
// result.data
})
XEAjax.get('/api/test/message/info', {id: 3})
.then(data => XEAjax.get(/api/test/message/delete/${data.id}))
.then(data => {
// data
})
`

Promises, async/await

`JavaScript
import XEAjax from 'xe-ajax'

async function init() {
let list = await XEAjax.get('/api/test/message/list')
let data = await XEAjax.get('/api/test/message/info', {id: list[0].id})
console.log(list)
console.log(data)
}

init()
`

Upload/Download (v3.4.9+)

| Name | Type | Description |
|------|------|-----|
| onUploadProgress | Function (event) | Upload progress |
| onDownloadProgress | Function (event) | Download progress |
| meanSpeed | Number | Default 0 off,Set the rate to equalization mode and calculate the average rate every millisecond. |
| fixed | Number | default 2 |

$3

| Name | Type | Description |
|------|------|-----|
| autoCompute | Boolean | Whether to automatically calculate. |
| value | Number | Current progress % |
| loaded | Object | Transmitted size {value, size, unit} |
| total | Object | Total size {value, size, unit} |
| speed | Object | Transmission speed/s {value, size, unit} |
| remaining | Number | RemainingTime/s |
| time | Number | timestamp |

Listener request progress.

`JavaScript
import XEAjax from 'xe-ajax'

let file = document.querySelector('#myFile').files[0]
let formBody = new FormData()
formBody.append('file', file)
XEAjax.fetchPost('/api/upload', formBody)
XEAjax.doPost('/api/upload', formBody)
XEAjax.post('/api/upload', formBody)


// Upload
// Create a Progress.
let progress = new XEAjax.Progress()
progress.onUploadProgress = evnt => {
let value = progress.value
let loadedSize = progress.loaded.size
let loadedUnit = progress.loaded.unit
let totalSize = progress.total.size
let totalUnit = progress.total.unit
let speedSize = progress.speed.size
let speedUnit = progress.speed.unit
let remaining = progress.remaining
console.log(Progress:${value}% ${loadedSize}${loadedUnit}${totalSize}/${totalUnit}; Speed:${speedSize}/${speedUnit}s; Remaining:${remaining}s)
}
let file = document.querySelector('#myFile').files[0]
let formBody = new FormData()
formBody.append('file', file)
XEAjax.fetchPost('/api/upload', formBody, {progress})
// Progress:1% 176KB/14.26MB; Speed:1.69MB/s; Remaining:8s
// Progress:3% 368KB/14.26MB; Speed:640KB/s; Remaining:22s
// Progress:8% 1.16MB/14.26MB; Speed:1.56MB/s; Remaining:8s
// ...
// Progress:99% 14.08MB/14.26MB; Speed:119.6KB/s; Remaining:2s
// Progress:100% 14.26MB/14.26MB; Speed:114.4KB/s; Remaining:0s


// Download
// Create Progress object.
let progress = new XEAjax.Progress()
progress.onDownloadProgress = evnt => {
let value = progress.value
let loadedSize = progress.loaded.size
let loadedUnit = progress.loaded.unit
let totalSize = progress.total.size
let totalUnit = progress.total.unit
let speedSize = progress.speed.size
let speedUnit = progress.speed.unit
let remaining = progress.remaining
console.log(Progress:${value}% ${loadedSize}${loadedUnit}${totalSize}/${totalUnit}; Speed:${speedSize}/${speedUnit}s; Remaining:${remaining}s)
}
XEAjax.fetchGet('/api/download/file/1', {progress, method: 'GET'})
`

Cancel request (v3.2.0+)

$3

Allows control of one or more cancellation requests.

`JavaScript
import XEAjax from 'xe-ajax'

// Create a controller.
let controller = new XEAjax.AbortController()
let signal = controller.signal
// Associate the signal and controller with the fetch request.
XEAjax.fetchGet('/api/test/message/list', {id: 1}, {signal})
.then(response => {
// finish
}).catch(function (e) {
// error
})
setTimeout(() => {
controller.abort()
}, 50)
`

Interceptor (v3.0+)

$3

XEAjax.interceptors.request.use(Function(request, next))

`JavaScript
import XEAjax from 'xe-ajax'

// Trigger before the request is sent.
XEAjax.interceptors.request.use((request, next) => {
// Can be used for unified permission intercept, set request header, Token authentication, parameters, etc.

// Set params
// Request.params.version = Date.now()

// Set Token validation to prevent XSRF/CSRF attacks.
request.headers.set('X-Token', cookie('x-id'))

// Call next(), execute the next interceptor.
next()
})
`

$3

XEAjax.interceptors.response.use(Function(response, next[, request]), Function(response, next[, request]))

next( [, newResponse] )

| Name | Type | Description |
|------|------|-----|
| status | Number | Setting the status code of the response. |
| statusText | String | Setting the status message corresponding to the status code. |
| body | Object | Setting the body contents. |
| headers | Headers、Object | Setting the Headers object associated with the response. |

`JavaScript
import XEAjax from 'xe-ajax'

// Intercept when the request is finish.
XEAjax.interceptors.response.use((response, next) => {
// It can be used for unified processing after a request is finish, such as checking for invalidation, message prompt, special scenario processing, etc.

// Example: check login failover.
if (response.status === 403) {
router.replace({path: '/login'})
// Break up
} else {
// Call next(), execute the next interceptor.
next()
}
})

// Intercept and change the response data after the request is complete.
XEAjax.interceptors.response.use((response, next) => {
response.json().then(data => {
let { status, statusText, headers } = response
let body = {
message: status === 200 ? 'success' : 'error',
result: data
}
// Change the response data and continue with the next interceptor.
next({status, statusText, headers, body})
})
}, (e, next) => {
// Turn all the exception errors to finish.
let body = {
message: 'error',
result: null
}
// Change the response data and continue with the next interceptor.
next({status: 200, body})
})
`

mixin ( fns )

Extends its own utility functions to XEAjax.

`JavaScript
import XEAjax from 'xe-ajax'

XEAjax.mixin({
get (url, request) {
return XEAjax.doGet(url, null, request)
},
delete (url, request) {
return XEAjax.doDelete(url, request)
},
post (url, data, request) {
return XEAjax.doPost(url, data, request)
},
put (url, data, request) {
return XEAjax.doPut(url, data, request)
}
})

XEAjax.get('/api/test/message/list', {params: {id: 123}})
XEAjax.delete('/api/test/message/delete/123')
XEAjax.post('/api/test/message/save', {name: 'test1'})
XEAjax.put('/api/test/message/update', {id: 123, name: 'test1'})
``

License

MIT © 2017-present, Xu Liangzhan