更新记录
1.0.1(2024-04-23)
- 增加了Gitee仓库地址
- 测试接口更新为自己用 uniCloud 写的测试接口,原来的聚合数据的接口不能用了
- 配置了 h5 devServer,解决 h5 请求时的跨域问题
- 更新了示例工程,可以直接运行示例工程
1.0.0(2024-04-09)
第一次发布
平台兼容性
Vue2 | Vue3 |
---|---|
√ | √ |
App | 快应用 | 微信小程序 | 支付宝小程序 | 百度小程序 | 字节小程序 | QQ小程序 |
---|---|---|---|---|---|---|
HBuilderX 3.6.12 app-vue app-nvue | √ | √ | √ | √ | √ | √ |
钉钉小程序 | 快手小程序 | 飞书小程序 | 京东小程序 |
---|---|---|---|
√ | √ | √ | √ |
H5-Safari | Android Browser | 微信浏览器(Android) | QQ浏览器(Android) | Chrome | IE | Edge | Firefox | PC-Safari |
---|---|---|---|---|---|---|---|---|
√ | √ | √ | √ | √ | √ | √ | √ | √ |
hi-request
对 uni.request() 扩展封装 可以下载示例项目查看更加详细的使用方法
仓库地址
开始
实例化
// config: 单个实例的基础配置项,会和默认配置项进行合并成
const hr = new HiRequest(config);
// 也可以通过下面的方法设置实例的基础配置项
hr.setConfig(config);
请求接口
// 第一种方式: 选项式回调函数方式
// 第1个参数: 请求地址
// 第2个参数: 单次请求的配置
// 注意: 如果控制台报错 Uncaught (in promise),这是因为 promise 没有 catch 的原因,使用 try...catch.. 或增加 .catch() 即刻解决此报错
const promise = hr.get("url", {
// ... 其他配置项
// 只有 HTTP 和返回的数据状态码正常才会调用此函数
// data: 接口返回的数据
// config: 本次请求的配置项
success: (data, config) => {
console.log("请求成功 →", data, config);
},
// 如果 HTTP 或返回数据的状态码有一个不正常就会调用此回调函数
// response: HTTP Response 对象
// config: 本次请求的配置项
error: (response, config) => {
console.log("请求错误 →", response, config);
},
// 请求失败,包括: 网络不通 | 请求被强行中断 | 请求超时 | 找不到域名 | ssl握手失败等会调用此函数
// 1. 通过 requestTask.abort() 中止的请求, error = {errMsg: 'request:fail abort'}
// 2. 网络离线时, error = {errMsg: 'request:fail'}
// 3. 其他情况 error 可能会是任何类型的数据
// config: 本次请求的配置项
fail: (error, config) => {
console.log("请求失败 →", response, config);
},
// 请求完成,不管成功或失败都会调用此函数
// response: HTTP Response 对象
// config: 本次请求的配置项
complete: (response, config) => {
console.log("请求完成 →", response, config);
}
});
// 第二种方式: then/catch 调用方式
// 第1个参数: 请求地址
// 第2个参数: 单次请求的配置
const promise = hr.post("url", {
// ... 其他配置项
// 请求参数
data: {
username: "ChenWanzhao"
}
})
// 只有 HTTP 和返回的数据状态码正常才会调用此函数
// data: 接口返回的数据
// config: 本次请求的配置项
.then((data, config) => {
console.log("请求成功 →", data, config);
})
// 除去上方的情况外,都会走 catch()
// response: HTTP Response 对象
// config: 本次请求的配置项
.catch((response, config) => {
console.log("请求错误或失败 →", response, config);
});
// 第三种方式: 即使用选项式回调函数又使用 then/catch
// 第1个参数: 请求地址
// 第2个参数: 单次请求的配置
const promise = hr.get("url", {
// ... 其他配置项
// 选项式回调函数
success: (data, config) => {},
error: (response, config) => {},
fail: (error, config) => {},
complete: (response, config) => {}
})
.then((data, config) => {})
.catch((response, config) => {})
// 中断请求
// requestTask 对象默认被挂载到了请求函数的返回值 promise 上
// 可以通过 promise.requestTask.abort() 中断请求
// 如:
const promise = hr.get("url", config);
promise.requestTask.abort();
// 注意: 因为 Promise 的 then/catch/finally 会返回一个新的 Promise,如果通过链式调用相关函数会导致 promise.requestTask 为 undefined
// 比如;
const promise = hr.get("url", config).then().catch().finally();
promise.requestTask.abort(); // 此时会报错
// 这时,可以将链式调用拆分出来,具体如下:
const promise = hr.get("url", config);
promise.then().catch().finally(); // 这样不会影响 promise
promise.requestTask.abort(); // 中断请求
配置项说明
uni.request() 自带配置
uni.request() 官方文档地址
配置项 | 说明 |
---|---|
url | 开发者服务器接口地址 可以是绝对路径或者相对路径,如果是相对路径,最终会和 baseURL 合并成一个完整的 URL |
data | 请求的参数 |
header | 设置请求的 header, header 中不能设置 Referer |
method | 请求类型 GET | POST | PUT | DELETE | CONNECT | HEAD | OPTIONS | TRACE 注意: method 有效值必须大写, 每个平台支持的 method 有效值不同,详细见官方文档 |
timeout | 超时时间,单位毫秒 |
dataType | 告诉服务器,我要发送的数据类型 如果设为 json, 会对返回的数据进行一次 JSON.parse, 非 json 不会进行 JSON.parse |
responseType | 设置响应的数据类型,text | arraybuffer |
sslVerify | 是否验证 ssl 证书? |
withCredentials | 域请求时是否携带凭证(cookies)? |
firstIpv4 | DNS 解析时是否优先使用 ipv4? |
enableHttps | 是否开启 http2? |
enableQuic | 是否开启 quic? |
enableCache | 是否开启 cache? |
enableHttpDNS | 是否开启 HttpDNS 服务?如开启,需要同时填入 httpDNSServiceId HttpDNS 用法详见 |
httpDNSServiceId | HttpDNS 服务商 Id HttpDNS 用法详见 |
enableChunked | 是否开启 transfer-encoding chunked? http 的响应头,如果存在 Transfer-Encoding: chunked 代表使用分块传输编码 |
forceCellularNetwork | 是否在 wifi 下使用移动网络发送请求? |
enableCookie | 开启后可在 headers 中编辑 cookie |
cloudCache | 是否开启云加速? 详见云加速服务 |
defer | 控制当前请求是否延时至首屏内容渲染后发送 |
重写 uni.request() 的回调函数
回调函数 | 说明 |
---|---|
success(data. config) | HTTP 状态码正常 && 返回数据的状态码也正常的回调函数 data: 接口返回的数据 config: 本次请求的配置 |
error(response, config) | HTTP 状态码异常 || 返回数据的状态码异常的回调函数 response: Response 对象 config: 本次请求的配置 |
fail(error, config) | 请求未成功的回调函数,包括: 网络不通 | 请求被强行中断 | 请求超时 | 找不到域名 | ssl握手失败等 error: 错误信息或错误对象 config: 本次请求的配置 |
complete(response, config) | 接口调用结束的回调函数(调用成功、失败都会执行) response: Response 对象 config: 本次请求的配置 |
扩展配置 - 基础配置
配置项 | 说明 |
---|---|
debug | 是否开启 debug? 开启后会在控制台输出一些此次请求的相关信息 |
baseURL | 接口基准前缀(一般为接口域名地址) |
tokenKey | 访问令牌名称 注意: 每次请求时会将此字段作为参数添加到请求 header 中,每次响应时,如果响应的 header 中有此字段,会自动更新此字段,此字段的值会存储到本地缓存中 |
tokenStorageKey | 访问令牌存储在本地的名称 一般,一个项目将访问令牌存储到本地时,存储的属性名会和令牌名称一致,但是,如果通过域名下有多个项目(比如有用户端,管理端,运营端等都部署在同一域名下),此时,如果多个项目的令牌名称又相同,就会导致,登录一个端时会吧其他端顶掉线,这时,在不同端将此字段配置成不同的值可以防止此情况发生 提示: 如果此值为空,默认存储的名称会和上面的访问令牌名称相同 |
dataStatusKey | 返回数据中表示数据状态码的属性的 key 名称,默认 code |
dataStatusTextKey | 返回数据中表示数据状态信息文本的属性 key 名称,默认 message |
dataSuccessStatusCode | 表示返回数据状态正常的状态码,默认 200 |
requestFailStatusCode | 自定义的表示请求失败的状态码和状态信息,默认 408,根据 HTTP 规范,408 Request Timeout 表示请求超时 |
requestInterceptorFunction | 请求拦截器,不会阻断请求,参数为此次请求配置(config) |
responseInterceptorFunction | 响应拦截器,不会阻断请求,回调参数为 response 和请求配置(config) |
functions | HTTP 状态码和数据状态码处理函数集,所有函数的回调参数都为 response 和请求配置(config) 例如: 处理 1000 状态码的函数可以这样配置: "1000": (response, config) => {} |
扩展配置 - 和提示相关的配置
配置项 | 说明 |
---|---|
showLoading | 是否显示 loading? |
loadingTime | 请求超过此值设置的毫秒数后才会显示,设置为 0 会在请求后立即显示 |
loadingText | 提示内容,顺序为: loadingText → response.data[dataStatusTextKey] → response.errMsg → response.statusCode |
loadingMask | 是否显示透明蒙层,防止触摸穿透 |
loadingShowFunction | 自定义显示 loading 的函数,参数为请求配置(config) 注意: 设置了此函数后,还需要对应的配置下方的关闭函数,否则 loading 可能不会被正确关闭,除非你在现实函数中处理了关闭的相关逻辑 |
loadingHideFunction | 自定义隐藏 loading 的函数,参数为请求配置(config) |
showSuccess | 是否显示成功提示? |
successText | 提示内容,顺序为: successText → response.data[dataStatusTextKey] → response.errMsg → response.statusCode |
successIcon | 图标, success | error | fail | exception | loading | none, 详见 |
successImage | 自定义图标的本地路径 |
successMask | 是否显示透明蒙层,防止触摸穿透 |
successDuration | 提示的持续时间,单位毫秒 |
successPositon | 提示的显示位置,填写有效值后只有 successText 属性生效,有效值: "top" | "center" | "bottom" |
successEndCallback | 提示显示结束后的回调,参数为 response 和请求配置(config) |
successShowFunction | 自定义显示提示的函数,参数为 response 和请求配置(config) |
showError | 是否显示错误提示? |
errorText | 提示内容,顺序为: errorText → response.data[dataStatusTextKey] → response.data.errMsg → response.statusCode |
errorIcon | 图标, success | error | fail | exception | loading | none, 详见 |
errorImage | 自定义图标的本地路径 |
errorMask | 是否显示透明蒙层,防止触摸穿透 |
errorDuration | 提示的持续时间,单位毫秒 |
errorPositon | 提示的显示位置,填写有效值后只有 errorText 属性生效,有效值: "top" | "center" | "bottom" |
errorEndCallback | 提示显示结束后的回调,参数为 response 和请求配置(config) |
errorShowFunction | 自定义显示提示的函数,参数为 response 和请求配置(config) |
showFail | 是否显示请求失败(网络不通 | 请求被强行中断 | 请求超时 | 找不到域名 | ssl握手失败等)提示? |
failText | 提示内容,顺序为: failText → error.errMsg → error |
failIcon | 图标, success | error | fail | exception | loading | none, 详见 |
failImage | 自定义图标的本地路径 |
failMask | 提示的持续时间,单位毫秒 |
failPositon | 提示的显示位置,填写有效值后只有 failText 属性生效,有效值: "top" | "center" | "bottom" |
failEndCallback | 提示显示结束后的回调,参数为 error 和请求配置(config) |
failShowFunction | 自定义显示提示的函数,参数为 error 和请求配置(config) |