提供封装了 HTTP 请求流程的 Promise 化接口。
- 具备 Promise 化的接口,并支持中断请求。
- 带有 TypeScript 类型声明。
- 支持浏览器和微信小程序两种运行环境,并提供了一致的外部接口。
- 在浏览器环境下:
- 封装了 XMLHTTPRequest 对象创建、请求发起、请求响应的全流程。
- 支持发送常用的数据类型:文本、对象、FormData、Blob 和 ArrayBuffer。
- 支持把数据序列化为
application/json
或application/x-www-form-urlencoded
的请求体。 - 根据选项设置把响应内容解析为 JSON、XML、文本、Blob 或 ArrayBuffer。
- 支持文件上传和下载场景下的进度响应(
onDownloadProgress
、onUploadProgress
)。 - 支持 PC 和移动端所有主流浏览器(其中 IE 浏览器的最低兼容版本是 9)。
- 在 IE 9 中,符合特定条件的情况下,通过 XDomainRequest 发起跨域请求。
- 在微信小程序环境下:
- 基于 wx.request 进行封装。
- 支持发送的数据类型包括:文本、对象和 ArrayBuffer。
- 根据选项设置把响应内容解析为 JSON、文本或 ArrayBuffer。
npm i @just4/request
import { Request } from '@just4/request';
import { xhrAdapter } from '@just4/request/adapter/xhr';
const xhrRequest = new Request(xhrAdapter);
需先安装 miniprogram-api-typings
。
import { Request } from '@just4/request';
import { wxRequestAdapter } from '@just4/request/adapter/wx-request';
// 用于微信小程序端
const wxRequest = new Request(wxRequestAdapter);
创建 Request 类的实例之后,就可以调用相关方法:
const result = await xhrRequest.send(url, {
// 选项说明见 API 文档
});
res.data; // data 是响应数据
res.options; // options 是请求选项
res.requestWith; // requestWith 是所使用的适配器的标识
实例化 Request 实例时可以传入基础选项。调用 send 方法时,传入的选项将与基础选项合并。合并后的选项才是请求时使用的选项。
const xhrRequest = new Request(xhrAdapter, {
responseType: 'json'
preventCaching: false
});
// 合并后的选项为 { responseType: 'json', preventCaching: true }
xhrRequest.send(url, {
preventCaching: true
});
// 以下两种调用方法,发送的请求是一样的
await xhrRequest.send('/detail?id=12345');
await xhrRequest.send('/detail', {
params: { id: '12345' }
});
把 method
选项的值设为 POST
,就可以发送 POST 请求。
await xhrRequest.send('/login', {
method: 'POST',
data: {
username: 'user',
password: 'qwer123'
}
});
如果 POST 请求的部分数据是以 URL 参数的形式传输,仍然可以放到 params
选项中:
await xhrRequest.send('/login', {
method: 'POST',
params: {
from: 'promotion'
},
data: {
username: 'user',
password: 'qwer123'
}
});
默认情况下,POST 请求的数据是以 application/x-www-form-urlencoded
编码发送的。如果需要发送 application/json
编码的数据,可以把 requestType
设置为 json
。
await xhrRequest.send('/login', {
method: 'POST',
requestType: 'json',
params: {
from: 'promotion'
},
data: {
username: 'user',
password: 'qwer123'
}
});
设置 preventCaching
选项为 true
后,send
方法会在请求的 URL 后拼接时间戳参数(任何请求方式都有效)。
// 实际请求的地址类似于 /detail?id=12345&_=1672712809951
await xhrRequest.send('/detail', {
params: { id: '12345' },
preventCaching: true
});
可以通过 timeout
指定请求的超时时间(毫秒)。如果请求超时,将会返回拒绝状态的 promise 实例。
import { RequestErrorType } from '@just4/request';
try {
await xhrRequeset.send('/login', {
method: 'post',
data: {
username: 'user',
password: 'qwer123'
},
timeout: 8000
});
} catch (e) {
if (e.type === RequestErrorType.TIMEOUT) {
// 请求超时
}
}
先通过 receiveTaskId
把请求的 id 记录下来,通过 cancel
方法取消请求。如果请求在完成前被取消,将会返回拒绝状态的 promise 实例。
let taskId = 0;
setTimeout(() => {
cancel(requestId);
}, 5000);
try {
await xhrRequest.send('/login', {
method: 'POST',
data: {
username: 'user',
password: 'qwer123'
},
receiveTaskId(id) {
taskId = id;
}
});
} catch (e) {
if (e.type === RequestErrorType.ABORT) {
// 请求被取消
}
}
- 不再引入
miniprogram-api-typings
,而是在tsconfig.json
中指定。
- 为保证调用上的灵活性,
@just4/request/index
不再导出适配器。 -
Request
类的send
、get
和post
都允许不传options
参数。
- 请求选项新增
extra
字段,可用于传入自定义选项。
- 升级依赖包版本并对应调整相关 API 的调用。