@uni-helper/axios-adapter 1.18.0 → 1.20.0

package/README.md

@@ -6,20 +6,32 @@
 
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/uni-helper/axios-adapter)
 
-## 安装
+## 目录
 
-```
-pnpm i @uni-helper/axios-adapter axios
-```
+- [简介](#简介)
+- [平台兼容性](#平台兼容性)
+- [安装](#安装)
+- [快速开始](#快速开始)
+- [使用](#使用)
+  - [创建自定义实例](#创建自定义实例)
+  - [与 useAxios 一起使用](#与-useaxios-一起使用)
+  - [上传和下载](#上传和下载)
+  - [小程序](#小程序)
+- [API 参考](#api-参考)
+- [版本策略](#版本策略)
+- [参与贡献](#参与贡献)
+- [许可证](#许可证)
 
-## 使用
+## 简介
+
+`@uni-helper/axios-adapter` 封装了 uni-app 的 `uni.request`、`uni.downloadFile`、`uni.uploadFile` 等接口，让开发者可以在 uni-app 的各类平台上继续使用熟悉的 axios 编程范式。适配器同时为 TypeScript 项目提供全局类型扩展，补充 `upload`、`download` 以及 uni-app 专有请求参数的类型定义。
 
-<details>
-<summary>点击查看平台兼容性</summary>
+## 平台兼容性
 
-| Vue2 | Vue3 |
-| ---- | ---- |
-| √    | √    |
+| Vue 版本 | 支持情况 |
+| -------- | -------- |
+| Vue 2    | √        |
+| Vue 3    | √        |
 
 | App                                      | 快应用 | 微信小程序 | 支付宝小程序 | 百度小程序 | 字节小程序 | QQ 小程序 |
 | ---------------------------------------- | ------ | ---------- | ------------ | ---------- | ---------- | --------- |
@@ -33,9 +45,15 @@ pnpm i @uni-helper/axios-adapter axios
 | --------- | --------------- | ------------------- | ------------------ | ------ | --- | ---- | ------- | --------- |
 | √         | √               | √                   | √                  | √      | √   | √    | √       | √         |
 
-</details>
+## 安装
 
-### 基本用法
+```bash
+pnpm i @uni-helper/axios-adapter axios
+```
+
+适配器与 axios 的版本需要保持主版本号和次版本号一致。当前适配器版本为 `1.20.0`，推荐搭配 `axios@^1.20.0` 使用。
+
+## 快速开始
 
 ```ts
 import { createUniAppAxiosAdapter } from '@uni-helper/axios-adapter'
@@ -44,7 +62,11 @@ import axios from 'axios'
 axios.defaults.adapter = createUniAppAxiosAdapter()
 ```
 
-或者创建自定义实例
+配置完成后，即可像往常一样使用 `axios.get`、`axios.post` 等方法发起请求。
+
+## 使用
+
+### 创建自定义实例
 
 ```ts
 import { createUniAppAxiosAdapter } from '@uni-helper/axios-adapter'
@@ -86,13 +108,12 @@ axios.request({
 
 ### 小程序
 
-自 axios 1.4.0 开始，axios 内部已经处理了小程序的兼容性问题
+自 axios 1.4.0 开始，axios 已对小程序环境做了兼容处理。若仍需在小程序中使用 `FormData` 和 `Blob`，可安装对应的 polyfill 并启用构建插件：
 
-<details>
-<summary>我要使用 `FormData` 和 `Blob` 对象</summary>
+```bash
+pnpm add miniprogram-formdata miniprogram-blob
+```
 
-小程序没有 `FormData` 和 `Blob` 对象，
-使用 `pnpm add miniprogram-formdata miniprogram-blob` 来安装对应的 polyfill，然后使用插件
 ```ts
 // vite.config.js
 import uniAxiosAdapter from '@uni-helper/axios-adapter/vite'
@@ -104,12 +125,35 @@ export default {
 }
 ```
 
-如果你使用的是 Vue CLI，改用 `@uni-helper/axios-adapter/webpack` 即可
+如果你使用的是 Vue CLI，改用 `@uni-helper/axios-adapter/webpack` 即可。
+
+## API 参考
+
+### `createUniAppAxiosAdapter(options?: UserOptions): AxiosAdapter`
+
+创建适配器实例，可直接赋值给 `axios.defaults.adapter` 或 `axios.create({ adapter })`。
+
+- `options`：可选配置对象，当前版本支持扩展 uni-app 请求参数（参见 `globalExtensions.ts` 中的类型定义）。
+- 返回值：标准的 `AxiosAdapter` 函数。
+
+### `axios.upload<T = any, D = any, P = any>(url: string, data?: D, config?: AxiosRequestConfig<D, P>): Promise<AxiosResponse<T, D, {}, P>>`
+
+以 `uni.uploadFile` 发送上传请求，`data` 通常为 `FormData` 实例。
+
+### `axios.download<T = any, D = any, P = any>(url: string, config?: AxiosRequestConfig<D, P>): Promise<AxiosResponse<T, D, {}, P>>`
+
+以 `uni.downloadFile` 发起下载请求，返回的 `response.data` 默认为文件临时路径或 `Buffer`（取决于运行环境）。
+
+泛型已与 axios 自带方法对齐：`T` 为响应数据类型，`D`/`P` 分别对应请求数据与 `params`。旧版的第二个泛型参数 `R`（自定义返回类型）已移除——axios 1.19 起其默认值 `AxiosResponseDefault` 未导出，无法继续透传 `R`。
+
+## 版本策略
+
+自 1.4.0 开始，请始终保持主版本号和次版本号与 axios 一致。例如当你安装了 1.5.1 版本时，你可以安装 axios 的 1.5.x 版本。这样做的目的是确保适配器始终支持最新的 axios 特性。
 
-</details>
+## 参与贡献
 
-### 版本
+欢迎通过 Issue 或 Pull Request 参与改进本项目。开始前请阅读 [CONTRIBUTING.md](./CONTRIBUTING.md)，了解本地开发、测试、提交规范与架构说明。
 
-自 1.4.0 开始，请始终保持主版本号和次版本号与 axios 一致。例如当你安装了 1.5.1 版本时，你可以安装 axios 的 1.5.x 版本。
+## 许可证
 
-这样做的目的是始终支持最新的 axios。
+[MIT](https://github.com/uni-helper/axios-adapter/blob/main/LICENSE)

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_rolldown_runtime = require("./rolldown-runtime-D6vf50IK.cjs");
+const require_rolldown_runtime = require("./rolldown-runtime-VH7oDXx4.cjs");
 let axios = require("axios");
 let axios_unsafe_core_buildFullPath = require("axios/unsafe/core/buildFullPath");
 axios_unsafe_core_buildFullPath = require_rolldown_runtime.__toESM(axios_unsafe_core_buildFullPath, 1);
@@ -70,7 +70,8 @@ function progressEventReducer(listener, isDownloadStream) {
 			bytes: progressBytes,
 			rate: rate || void 0,
 			estimated: rate && total && inRange ? (total - loaded) / rate : void 0,
-			event: result
+			event: result,
+			lengthComputable: true
 		};
 		data[isDownloadStream ? "download" : "upload"] = true;
 		listener(data);
@@ -137,7 +138,7 @@ var OnCanceled = class {
 		if (this.config.cancelToken || this.config.signal) {
 			this.onCanceled = (cancel) => {
 				if (!task) return;
-				reject(!cancel || cancel.type ? new axios.CanceledError(void 0, void 0, this.config, task) : cancel);
+				reject(!cancel || cancel.type ? new axios.CanceledError(void 0, this.config, task) : cancel);
 				task.abort();
 				task = null;
 			};
@@ -162,14 +163,15 @@ const download = (config, options) => {
 			...requestOptions,
 			success(result) {
 				if (!task) return;
-				(0, axios_unsafe_core_settle.default)(resolve, reject, {
+				const response = {
 					config: responseConfig,
 					data: result.tempFilePath,
 					headers: {},
 					status: result.statusCode,
 					statusText: result.errMsg ?? "OK",
 					request: task
-				});
+				};
+				(0, axios_unsafe_core_settle.default)(resolve, reject, response);
 				task = null;
 			},
 			fail(error) {
@@ -208,7 +210,7 @@ const request = (config, options) => {
 					result.header = dingHeader;
 				}
 				const headers = new axios.AxiosHeaders(result.header);
-				(0, axios_unsafe_core_settle.default)(resolve, reject, {
+				const response = {
 					config: responseConfig,
 					data: result.data,
 					headers,
@@ -216,7 +218,8 @@ const request = (config, options) => {
 					statusText: result.errMsg ?? "OK",
 					request: task,
 					cookies: result.cookies
-				});
+				};
+				(0, axios_unsafe_core_settle.default)(resolve, reject, response);
 				task = null;
 			},
 			fail(error) {
@@ -259,14 +262,15 @@ const upload = (config, options) => {
 			...requestOptions,
 			success(result) {
 				if (!task) return;
-				(0, axios_unsafe_core_settle.default)(resolve, reject, {
+				const response = {
 					config: responseConfig,
 					data: result.data,
 					headers: {},
 					status: result.statusCode,
 					statusText: result.errMsg ?? "OK",
 					request: task
-				});
+				};
+				(0, axios_unsafe_core_settle.default)(resolve, reject, response);
 				task = null;
 			},
 			fail(error) {

package/dist/index.d.cts

@@ -1,6 +1,8 @@
-import { t as UserOptions } from "./types-NHxcq8Qp.cjs";
 import { AxiosAdapter } from "axios";
-
+//#region src/types.d.ts
+interface Options {}
+interface UserOptions extends Partial<Options> {}
+//#endregion
 //#region src/globalExtensions.d.ts
 declare module 'axios' {
   interface AxiosRequestConfig extends Omit<UniApp.RequestOptions, 'success' | 'fail' | 'complete' | 'header'>, Omit<UniApp.UploadFileOption, 'success' | 'fail' | 'complete' | 'header' | 'formData'>, Omit<UniApp.DownloadFileOption, 'success' | 'fail' | 'complete' | 'header'>, Partial<Pick<UniApp.RequestTask, 'onHeadersReceived'>> {}
@@ -8,8 +10,8 @@ declare module 'axios' {
     cookies?: string[];
   }
   interface Axios {
-    upload: <T = any, R = AxiosResponse<T>, D = any>(url: string, data?: D, config?: AxiosRequestConfig<D>) => Promise<R>;
-    download: <T = any, R = AxiosResponse<T>, D = any>(url: string, config?: AxiosRequestConfig<D>) => Promise<R>;
+    upload: <T = any, D = any, P = any>(url: string, data?: D, config?: AxiosRequestConfig<D, P>) => AxiosPromise<T, D, P>;
+    download: <T = any, D = any, P = any>(url: string, config?: AxiosRequestConfig<D, P>) => AxiosPromise<T, D, P>;
   }
 }
 //#endregion

package/dist/index.d.ts

@@ -1,6 +1,8 @@
-import { t as UserOptions } from "./types-NHxcq8Qp.js";
 import { AxiosAdapter } from "axios";
-
+//#region src/types.d.ts
+interface Options {}
+interface UserOptions extends Partial<Options> {}
+//#endregion
 //#region src/globalExtensions.d.ts
 declare module 'axios' {
   interface AxiosRequestConfig extends Omit<UniApp.RequestOptions, 'success' | 'fail' | 'complete' | 'header'>, Omit<UniApp.UploadFileOption, 'success' | 'fail' | 'complete' | 'header' | 'formData'>, Omit<UniApp.DownloadFileOption, 'success' | 'fail' | 'complete' | 'header'>, Partial<Pick<UniApp.RequestTask, 'onHeadersReceived'>> {}
@@ -8,8 +10,8 @@ declare module 'axios' {
     cookies?: string[];
   }
   interface Axios {
-    upload: <T = any, R = AxiosResponse<T>, D = any>(url: string, data?: D, config?: AxiosRequestConfig<D>) => Promise<R>;
-    download: <T = any, R = AxiosResponse<T>, D = any>(url: string, config?: AxiosRequestConfig<D>) => Promise<R>;
+    upload: <T = any, D = any, P = any>(url: string, data?: D, config?: AxiosRequestConfig<D, P>) => AxiosPromise<T, D, P>;
+    download: <T = any, D = any, P = any>(url: string, config?: AxiosRequestConfig<D, P>) => AxiosPromise<T, D, P>;
   }
 }
 //#endregion

package/dist/index.js

@@ -64,7 +64,8 @@ function progressEventReducer(listener, isDownloadStream) {
 			bytes: progressBytes,
 			rate: rate || void 0,
 			estimated: rate && total && inRange ? (total - loaded) / rate : void 0,
-			event: result
+			event: result,
+			lengthComputable: true
 		};
 		data[isDownloadStream ? "download" : "upload"] = true;
 		listener(data);
@@ -131,7 +132,7 @@ var OnCanceled = class {
 		if (this.config.cancelToken || this.config.signal) {
 			this.onCanceled = (cancel) => {
 				if (!task) return;
-				reject(!cancel || cancel.type ? new CanceledError(void 0, void 0, this.config, task) : cancel);
+				reject(!cancel || cancel.type ? new CanceledError(void 0, this.config, task) : cancel);
 				task.abort();
 				task = null;
 			};
@@ -156,14 +157,15 @@ const download = (config, options) => {
 			...requestOptions,
 			success(result) {
 				if (!task) return;
-				settle(resolve, reject, {
+				const response = {
 					config: responseConfig,
 					data: result.tempFilePath,
 					headers: {},
 					status: result.statusCode,
 					statusText: result.errMsg ?? "OK",
 					request: task
-				});
+				};
+				settle(resolve, reject, response);
 				task = null;
 			},
 			fail(error) {
@@ -202,7 +204,7 @@ const request = (config, options) => {
 					result.header = dingHeader;
 				}
 				const headers = new AxiosHeaders(result.header);
-				settle(resolve, reject, {
+				const response = {
 					config: responseConfig,
 					data: result.data,
 					headers,
@@ -210,7 +212,8 @@ const request = (config, options) => {
 					statusText: result.errMsg ?? "OK",
 					request: task,
 					cookies: result.cookies
-				});
+				};
+				settle(resolve, reject, response);
 				task = null;
 			},
 			fail(error) {
@@ -253,14 +256,15 @@ const upload = (config, options) => {
 			...requestOptions,
 			success(result) {
 				if (!task) return;
-				settle(resolve, reject, {
+				const response = {
 					config: responseConfig,
 					data: result.data,
 					headers: {},
 					status: result.statusCode,
 					statusText: result.errMsg ?? "OK",
 					request: task
-				});
+				};
+				settle(resolve, reject, response);
 				task = null;
 			},
 			fail(error) {

package/dist/{rolldown-runtime-D6vf50IK.cjs → rolldown-runtime-VH7oDXx4.cjs}

@@ -15,7 +15,7 @@ var __copyProps = (to, from, except, desc) => {
 	}
 	return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
 	value: mod,
 	enumerable: true
 }) : target, mod));

package/dist/{unplugin-Cgwh-Njz.cjs → unplugin-DATd423M.cjs}

@@ -1,9 +1,9 @@
-const require_rolldown_runtime = require("./rolldown-runtime-D6vf50IK.cjs");
+const require_rolldown_runtime = require("./rolldown-runtime-VH7oDXx4.cjs");
 let node_process = require("node:process");
 node_process = require_rolldown_runtime.__toESM(node_process, 1);
 let local_pkg = require("local-pkg");
 //#region src/unplugin.ts
-const unplugin$1 = (0, require("unplugin").createUnplugin)((_options = {}) => {
+const unplugin$1 = (0, require("unplugin").createUnplugin)(() => {
 	const hasFormDataPolyfill = (0, local_pkg.isPackageExists)("miniprogram-formdata");
 	const hasBlobPolyfill = (0, local_pkg.isPackageExists)("miniprogram-blob");
 	return {

package/dist/{unplugin-Br8JKdJO.js → unplugin-DJxh_3Ax.js}

@@ -2,7 +2,7 @@ import process from "node:process";
 import { isPackageExists } from "local-pkg";
 import { createUnplugin } from "unplugin";
 //#region src/unplugin.ts
-const unplugin = createUnplugin((_options = {}) => {
+const unplugin = createUnplugin(() => {
 	const hasFormDataPolyfill = isPackageExists("miniprogram-formdata");
 	const hasBlobPolyfill = isPackageExists("miniprogram-blob");
 	return {

package/dist/vite.cjs

@@ -1,4 +1,4 @@
 //#region src/vite.ts
-var vite_default = require("./unplugin-Cgwh-Njz.cjs").unplugin.vite;
+var vite_default = require("./unplugin-DATd423M.cjs").unplugin.vite;
 //#endregion
 module.exports = vite_default;

package/dist/vite.d.cts

@@ -1,5 +1,3 @@
-import { n as UserUnpluginOptions } from "./types-NHxcq8Qp.cjs";
-
 //#region src/vite.d.ts
-declare const _default: (options: UserUnpluginOptions) => import("vite").Plugin<any> | import("vite").Plugin<any>[];
+declare const _default: (options?: unknown) => import("vite").Plugin<any> | import("vite").Plugin<any>[];
 export = _default;

package/dist/vite.d.ts

@@ -1,6 +1,4 @@
-import { n as UserUnpluginOptions } from "./types-NHxcq8Qp.js";
-
 //#region src/vite.d.ts
-declare const _default: (options: UserUnpluginOptions) => import("vite").Plugin<any> | import("vite").Plugin<any>[];
+declare const _default: (options?: unknown) => import("vite").Plugin<any> | import("vite").Plugin<any>[];
 //#endregion
 export { _default as default };

package/dist/vite.js

@@ -1,4 +1,4 @@
-import { t as unplugin } from "./unplugin-Br8JKdJO.js";
+import { t as unplugin } from "./unplugin-DJxh_3Ax.js";
 //#region src/vite.ts
 var vite_default = unplugin.vite;
 //#endregion

package/dist/webpack.cjs

@@ -1,4 +1,4 @@
 //#region src/webpack.ts
-var webpack_default = require("./unplugin-Cgwh-Njz.cjs").unplugin.webpack;
+var webpack_default = require("./unplugin-DATd423M.cjs").unplugin.webpack;
 //#endregion
 module.exports = webpack_default;

package/dist/webpack.d.cts

@@ -1,5 +1,3 @@
-import { n as UserUnpluginOptions } from "./types-NHxcq8Qp.cjs";
-
 //#region src/webpack.d.ts
-declare const _default: (options: UserUnpluginOptions) => WebpackPluginInstance;
+declare const _default: (options?: unknown) => WebpackPluginInstance;
 export = _default;

package/dist/webpack.d.ts

@@ -1,6 +1,4 @@
-import { n as UserUnpluginOptions } from "./types-NHxcq8Qp.js";
-
 //#region src/webpack.d.ts
-declare const _default: (options: UserUnpluginOptions) => WebpackPluginInstance;
+declare const _default: (options?: unknown) => WebpackPluginInstance;
 //#endregion
 export { _default as default };

package/dist/webpack.js

@@ -1,4 +1,4 @@
-import { t as unplugin } from "./unplugin-Br8JKdJO.js";
+import { t as unplugin } from "./unplugin-DJxh_3Ax.js";
 //#region src/webpack.ts
 var webpack_default = unplugin.webpack;
 //#endregion

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@uni-helper/axios-adapter",
   "type": "module",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "description": "The Axios adapter for uniapp",
   "author": {
     "name": "kejunmao",
     "email": "kejun1997@gmail.com"
   },
   "license": "MIT",
+  "funding": "https://afdian.com/a/kejun",
   "homepage": "https://github.com/uni-helper/axios-adapter",
   "repository": {
     "type": "git",
@@ -59,7 +60,7 @@
     "dist"
   ],
   "peerDependencies": {
-    "axios": "^1.18.0",
+    "axios": "^1.20.0",
     "vite": "^5.0.0"
   },
   "dependencies": {
@@ -67,17 +68,17 @@
     "unplugin": "^2.3.11"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^9.0.0",
-    "@dcloudio/types": "^3.4.31",
-    "@types/node": "^24.13.2",
-    "axios": "^1.18.0",
-    "bumpp": "^11.1.0",
-    "eslint": "^10.5.0",
-    "msw": "^2.14.6",
-    "tsdown": "^0.22.2",
-    "typescript": "^5.9.3",
+    "@antfu/eslint-config": "^9.3.0",
+    "@dcloudio/types": "^3.4.32",
+    "@types/node": "^24.13.3",
+    "axios": "^1.20.0",
+    "bumpp": "^12.2.2",
+    "eslint": "^10.9.1",
+    "msw": "^2.15.0",
+    "tsdown": "^0.22.14",
+    "typescript": "^6.0.3",
     "vite": "^5.4.21",
-    "vitest": "^3.2.6"
+    "vitest": "^3.2.7"
   },
   "scripts": {
     "build": "tsdown",

package/dist/types-NHxcq8Qp.d.cts

@@ -1,7 +0,0 @@
-//#region src/types.d.ts
-interface Options {}
-interface UserOptions extends Partial<Options> {}
-interface UnpluginOptions {}
-interface UserUnpluginOptions extends Partial<UnpluginOptions> {}
-//#endregion
-export { UserUnpluginOptions as n, UserOptions as t };

package/dist/types-NHxcq8Qp.d.ts

@@ -1,7 +0,0 @@
-//#region src/types.d.ts
-interface Options {}
-interface UserOptions extends Partial<Options> {}
-interface UnpluginOptions {}
-interface UserUnpluginOptions extends Partial<UnpluginOptions> {}
-//#endregion
-export { UserUnpluginOptions as n, UserOptions as t };