更新记录
3.0.4(2024-09-18)
下载此版本
- 修复打包运行到H5时报 uni[r] is not a funcition 错误的问题
3.0.3(2024-09-08)
下载此版本
3.0.2(2024-09-06)
下载此版本
查看更多
平台兼容性
App |
快应用 |
微信小程序 |
支付宝小程序 |
百度小程序 |
字节小程序 |
QQ小程序 |
HBuilderX 4.0 app-vue app-nvue |
√ |
√ |
√ |
√ |
√ |
√ |
钉钉小程序 |
快手小程序 |
飞书小程序 |
京东小程序 |
× |
× |
× |
√ |
H5-Safari |
Android Browser |
微信浏览器(Android) |
QQ浏览器(Android) |
Chrome |
IE |
Edge |
Firefox |
PC-Safari |
√ |
√ |
√ |
√ |
√ |
√ |
√ |
√ |
√ |
hi-http
介绍
- 网络请求工具,对 uni.request、uni.upload 的扩展封装
仓库
Gitee:https://gitee.com/chenshuang-jinli/hi-uniapp-http
使用示例
创建请求实例
import settings from "@/src/settings";
import HiHttp from "@/uni_modules/hi-http";
// 公共配置
const commonConfig = {
// 数据中表示状态码的字段名称
dataStatusKey: "code",
// 数据中表示状态文本的字段名称
dataStatusTextKey: "errMsg",
// 数据中表示成功状态的状态码
dataSuccessStatusCode: 0,
// 请求前的拦截函数
before: (conf) => {
// console.info("请求前的处理函数 ->", conf);
return true;
},
// 请求后的处理函数
after: (resp, conf) => {
// console.info("请求后的处理函数 ->", conf);
},
// 状态码处理函数
codeFunctions: {
// 用户登录状态失效
401: function (resp, conf) {
// 终止所有请求
commonRequestInstance?.aborts();
commonUploadInstance?.aborts();
// 清除用户相关数据
// useUserStore()?.clear();
// 刷新当前页面
// uni.$hiRouter?.refresh();
}
}
};
// 公共接口请求实例
export const commonRequestInstance = new HiHttp({
...commonConfig,
// 接口基准路径
baseURL: settings.apiBaseUrl,
// 请求时携带的鉴权凭证名称
requestTokenKey: settings.apiRequestTokenKey,
// 接口返回数据中携带的鉴权凭证名称
responseTokenKey: settings.apiResponseTokenKey,
// 存储在本地的鉴权凭证名称
storageTokenKey: settings.apiStorageTokenKey
});
// 公共上传请求实例
export const commonUploadInstance = new HiHttp({
...commonConfig,
// 接口基准路径
baseURL: settings.uploadBaseUrl,
// 请求时携带的鉴权凭证名称
requestTokenKey: settings.uploadRequestTokenKey,
// 接口返回数据中携带的鉴权凭证名称
responseTokenKey: settings.uploadResponseTokenKey,
// 存储在本地的鉴权凭证名称
storageTokenKey: settings.uploadStorageTokenKey
});
创建接口请求函数
/**
* /apis/common.js
* 公共接口集
*
* @list 接口列表
* ========================================================================================================================
* = apiQueryDemo = 一个接口示例
* ========================================================================================================================
*/
import { request } from "./instances";
/**
* 一个接口示例
* @param {Object} config 请求时的配置
*/
export function apiQueryDemo(config = {}) {
config.url = "/api/v1/hi_http_request_demo";
return request.post(config);
}
使用接口请求函数
// .then().catch().finally() 方式
async function handleClick1() {
apiQueryDemo({
data: {
id: 1
}
})
.then((res) => {
console.log("res1 ->", res);
})
.catch((err) => console.error(err))
.finally(() => console.log("请求结束了"));
}
// await 方式
async function handleClick2() {
console.log("before await!");
const res = await apiQueryDemo({
data: {
id: 1
}
});
console.log("res2 ->", res);
console.log("after await!");
}
// success、error、fail、complete 回调函数方式
async function handleClick3() {
const task = await apiQueryDemo({
data: {
id: 1
},
success: (res) => {
console.log("res3 ->", res);
},
error: (err) => console.error(err),
fail: (err) => console.error(err),
complete: () => console.log("请求结束了")
});
// 取消请求
console.log("task ->", task);
task.abort();
}
默认配置
// 默认配置
const defaultConfig = {
/**
* [uni.request() 自带配置](https://uniapp.dcloud.net.cn/api/request/request.html)
*/
url: "", // 接口地址,可以是绝对路径或者相对路径,如果是相对路径,最终会和 baseURL 合并成一个完整的 URL
data: {}, // 请求的参数
header: {}, // 设置请求的 header, header 中不能设置 Referer
method: "GET", // 请求类型,GET | POST | PUT | DELETE | CONNECT | HEAD | OPTIONS | TRACE | UPLOAD(扩展的)
timeout: 30000, // 超时时间,单位毫秒
dataType: "json", // 告诉服务器,我要发送的数据类型,如果设为 json, 会对返回的数据进行一次 JSON.parse, 非 json 不会进行 JSON.parse
responseType: "text", // 设置响应的数据类型,text | arraybuffer
sslVerify: true, // 是否验证 ssl 证书?
withCredentials: false, // 域请求时是否携带凭证(cookies)?
firstIpv4: false, // DNS 解析时是否优先使用 ipv4?
enableHttps: false, // 是否开启 http2?
enableQuic: false, // 是否开启 quic?
enableCache: false, // 是否开启 cache?
enableHttpDNS: false, // 是否开启 HttpDNS 服务?
httpDNSServiceId: "", // HttpDNS 服务商 Id
enableChunked: false, // 是否开启 transfer-encoding chunked?
forceCellularNetwork: false, // 是否在 wifi 下使用移动网络发送请求?
enableCookie: false, // 开启后可在 headers 中编辑 cookie
cloudCache: false, // 是否开启云加速?
defer: false, // 控制当前请求是否延时至首屏内容渲染后发送
/**
* [uni.upload() 自带配置](https://uniapp.dcloud.net.cn/api/request/network-file.html)
*/
files: [], // 需要上传的文件列表。使用 files 时,filePath 和 name 不生效
fileType: "image", // 文件类型,image/video/audio
file: {}, // 要上传的文件对象
filePath: "", // 要上传文件资源的路径
name: "file", // 文件对应的 key , 开发者在服务器端通过这个 key 可以获取到文件二进制内容
formData: {}, // HTTP 请求中其他额外的 form data
/**
* 重写 uni.request() 的回调函数
*/
// HTTP 状态码正常且返回数据的状态码也正常的回调函数
// 回调参数:接口返回的数据(response.data)和本次请求的最终配置(config)
// 注意: 此函数被重写了,和 uni.request 或 uni.upload 的 success 不一样了
success: null,
// HTTP 状态码异常或返回数据的状态码异常的回调函数
// 回调参数:errData: 包含错误码和错误文本的对象,如果是接口返回的数据状态码异常,则返回的是接口返回的数据对象; config: 本次请求的最终配置(config)
// 注意: uni 本身没有此回调函数,该回调函数是为了更好的处理返回数据而扩展增加的
error: null,
// 接口请求失败的回调函数
// 请求未成功
// 包括: 网络不通 | 请求被强行中断 | 请求超时 | 找不到域名 | ssl握手失败等
// 回调参数为 errorData: 包含错误码和错误文本的对象和请求配置(config)
fail: null,
// 接口调用结束的回调函数(调用成功、失败都会执行)
// 回调参数为 response 和请求配置(config)
complete: null,
/**
* HiHttp 扩展配置 - 基础配置
*/
// 接口基准前缀(一般为接口域名地址)
baseURL: "",
// 请求时携带的鉴权凭证名称
requestTokenKey: "Authorization",
// 接口返回数据中携带的鉴权凭证名称
responseTokenKey: "Authorization",
// 存储在本地的鉴权凭证名称
storageTokenKey: "Authorization",
// 请求时携带的更新鉴权凭证名称
requestRefreshTokenKey: "refresh_token",
// 接口返回数据中携带的更新鉴权凭证名称
responseRefreshTokenKey: "refresh_token",
// 数据中表示状态码的字段名称
dataStatusKey: "code",
// 数据中表示状态文本的字段名称
dataStatusTextKey: "errMsg",
// 数据中表示成功状态的状态码
dataSuccessStatusCode: 0,
// 自定义的表示请求失败的状态码和状态信息
// 根据 HTTP 规范,408 Request Timeout 表示请求超时
requestFailStatusCode: -1,
// 请求拦截器,参数为此次请求配置(config)
// 返回true则继续请求,返回false则中断请求
before: null,
// 响应拦截器
// 回调参数为 response 和请求配置(config)
after: null,
// HTTP 状态码和数据状态码处理函数集
// 所有函数的回调参数都为 response 和请求配置(config)
codeFunctions: {
// 例如: 处理 1000 状态码的函数
// "1000": (response, config) => {},
},
/**
* HiHttp 扩展配置 - 和提示相关的配置
*/
// Loading - 加载提示
showLoading: true, // 是否显示 loading?
loadingTime: 800, // 请求超过此值设置的毫秒数后才会显示,设置为 0 会在请求后立即显示
loadingText: "", // 提示内容
loadingMask: true, // 是否显示透明蒙层,防止触摸穿透
// 自定义显示 loading 的函数,参数为请求配置(config)
// 注意: 设置了此函数后,还需要对应的配置下方的关闭函数,否则 loading 可能不会被正确关闭,除非你在现实函数中处理了关闭的相关逻辑
loadingShowFunction: null,
// 自定义隐藏 loading 的函数,参数为请求配置(config)
loadingHideFunction: null,
// Success - 成功提示
showSuccess: false, // 是否显示提示?
successText: "", // 提示内容
successIcon: "none", // 图标,success | error | fail | exception | loading | none
successImage: "", // 自定义图标的本地路径
successMask: true, // 是否显示透明蒙层,防止触摸穿透
successDuration: 2500, // 提示的持续时间,单位毫秒
successPositon: "", // 提示的显示位置,"top" | "center" | "bottom",填写有效值后只有 successText 属性生效
successEndCallback: null, // 提示显示结束后的回调,参数为接口返回的数据和请求配置(config)
successShowFunction: null, // 自定义显示提示的函数,参数为接口返回的数据和请求配置(config)
// Error - 错误提示
showError: true, // 是否显示提示?
errorText: "", // 提示内容
errorIcon: "none", // 图标,success | error | fail | exception | loading | none
errorImage: "", // 自定义图标的本地路径
errorMask: true, // 是否显示透明蒙层,防止触摸穿透
errorDuration: 2500, // 提示的持续时间,单位毫秒
errorPositon: "", // 提示的显示位置,"top" | "center" | "bottom",填写有效值后只有 successText 属性生效
errorEndCallback: null, // 提示显示结束后的回调,参数为错误信息对象和请求配置(config)
errorShowFunction: null, // 自定义显示提示的函数。参数为错误信息对象和请求配置(config)
// Fail - 请求失败,包括: 网络不通 | 请求被强行中断 | 请求超时 | 找不到域名 | ssl握手失败等
showFail: true, // 是否显示提示
failText: "请求失败", // 提示内容
failIcon: "none", // 图标,success | error | fail | exception | loading | none
failImage: "", // 自定义图标的本地路径
failMask: true, // 是否显示透明蒙层,防止触摸穿透
failDuration: 2500, // 提示的持续时间,单位毫秒
failPositon: "", // 提示的显示位置,"top" | "center" | "bottom",填写有效值后只有 successText 属性生效
failEndCallback: null, // 提示显示结束后的回调,参数为错误信息对象和请求配置(config)
failShowFunction: null // 自定义显示提示的函数,参数为错误信息对象和请求配置(config)
};
实例方法列表
- setConfig(config): 设置本次实例的配置
- get(config): GET 请求
- post(config): POST 请求
- put(config): PUT 请求
- delete(config): DELETE 请求
- connect(config): CONNECT 请求
- head(config): HEAD 请求
- options(config): OPTIONS 请求
- trace(config): TRACE 请求
- upload(config): 上传请求
- aborts(): 中断当前实例上的所有请求