axios-adapter

适用于 Vue2 和 Vue3 的 uniapp Axios 适配器

本适配器封装 uni-app 的 uni.request、uni.downloadFile、uni.uploadFile 等接口,让 axios 的编程方式在 uni-app 各平台继续可用。

本包同时为 TypeScript 项目提供全局类型扩展,补充 upload、download 与 uni-app 专有请求参数的类型定义。

平台兼容性

Vue 版本支持情况
Vue 2√
Vue 3√
App快应用微信小程序支付宝小程序百度小程序字节小程序QQ 小程序
HBuilderX 3.4.8
app-vue
app-nvue
√√√√√√
钉钉小程序快手小程序飞书小程序京东小程序
√√√√
H5-SafariAndroid Browser微信浏览器 (Android)QQ 浏览器 (Android)ChromeIEEdgeFirefoxPC-Safari
√√√√√√√√√

安装

npm i @uni-helper/axios-adapter axios

适配器与 axios 的主版本号和次版本号必须一致。当前适配器版本是 1.21.0,推荐搭配 axios@^1.21.0 使用。

基本用法

import { createUniAppAxiosAdapter } from '@uni-helper/axios-adapter'
import axios from 'axios'

axios.defaults.adapter = createUniAppAxiosAdapter()

配置完成后,可以照常使用 axios.get、axios.post 等方法。

uni.request 本身没有默认超时。适配器设置了 60 秒默认超时,可以用 config.timeout 覆盖。

创建自定义实例

import { createUniAppAxiosAdapter } from '@uni-helper/axios-adapter'
import axios from 'axios'

const instance = axios.create({ adapter: createUniAppAxiosAdapter() })

传递 uni-app 专有参数

导入本包后,axios 的请求配置类型会自动扩展出 uni-app 专有参数,可以直接使用:

axios.get('https://example.com/get', {
  enableHttp2: true,
  enableQuic: true,
  enableCache: true,
})

这些参数原样透传给 uni.request。类型扩展同时为 AxiosResponse 补充了 cookies 字段。

取消请求

const controller = new AbortController()

axios.get('/get', { signal: controller.signal })

// 需要取消时
controller.abort()

除 AbortController 外,也兼容 axios 旧版的 CancelToken。

Basic Auth 用户名编码

config.auth 由适配器直接拼成 Authorization: Basic ... 请求头,行为与 axios 1.21 的 xhr、fetch 一致:

  • 密码始终按 UTF-8 编码。
  • 用户名默认按原字节发送。

用户名含非 ASCII 字符时,必须显式开启 transitional.encodeBasicAuthUsername:

axios.get('/get', {
  auth: { username: '用户名', password: 'pwd' },
  transitional: { encodeBasicAuthUsername: true },
})

也可以写在实例默认值上:axios.create({ adapter, transitional: { encodeBasicAuthUsername: true } })。

与 useAxios 一起使用

import { createUniAppAxiosAdapter } from '@uni-helper/axios-adapter'
import axios from 'axios'

axios.defaults.adapter = createUniAppAxiosAdapter()
const { data, isFinished } = useAxios('/posts')

详见 vueuse useAxios。

上传和下载

// 下载
axios.download('/')
// or
axios.request({
  url: '/',
  method: 'download',
})

// 上传
axios.upload('/', new File([new Blob()], 'fake file'))
// or
axios.request({
  url: '/',
  method: 'upload',
  data: new File([new Blob()], 'fake file'),
})

监听进度和响应头

axios.download('/file', {
  onHeadersReceived(result) {
    console.log(result.header)
  },
  onDownloadProgress(progressEvent) {
    console.log(progressEvent.loaded, progressEvent.total)
  },
})

axios.upload('/upload', data, {
  onUploadProgress(progressEvent) {
    console.log(progressEvent.loaded, progressEvent.total)
  },
})

三种请求都支持 onHeadersReceived。

onDownloadProgress 与 onUploadProgress 的事件格式与浏览器端 axios 一致:上传事件带 upload: true,下载事件带 download: true。下载与上传响应的 headers 是空对象。

小程序

自 axios 1.4.0 起,axios 已对小程序环境做了部分兼容处理。

需要在小程序里使用 FormData 与 Blob 时,必须安装 polyfill 并启用构建插件:

pnpm add miniprogram-formdata miniprogram-blob
// vite.config.js
import uniAxiosAdapter from '@uni-helper/axios-adapter/vite'

export default {
  plugins: [
    uniAxiosAdapter()
  ]
}

使用 Vue CLI 时,改用 @uni-helper/axios-adapter/webpack。

API

createUniAppAxiosAdapter

function createUniAppAxiosAdapter(options?: UserOptions): AxiosAdapter

创建适配器实例,可以直接赋值给 axios.defaults.adapter,或传给 axios.create({ adapter })。

调用时会在 Axios 原型上挂载 upload 与 download 方法,对所有 axios 实例全局生效。

options 是可选配置对象。当前版本没有可配置字段,仅作预留。返回值是标准的 AxiosAdapter 函数。

axios.upload

function upload<T = any, D = any, P = any>(
  url: string,
  data?: D,
  config?: AxiosRequestConfig<D, P>,
): Promise<AxiosResponse<T, D>>

uni.uploadFile 发送上传请求。data 通常是 FormData 实例。

axios.download

function download<T = any, D = any, P = any>(
  url: string,
  config?: AxiosRequestConfig<D, P>,
): Promise<AxiosResponse<T, D>>

uni.downloadFile 发起下载请求。response.data 是下载文件的临时路径(tempFilePath)。

泛型与 axios 自带方法对齐:T 是响应数据类型,D 与 P 分别对应请求数据与 params。

旧版的第二个泛型参数 R(自定义返回类型)已移除。axios 1.19 起其默认值 AxiosResponseDefault 未导出,无法继续透传 R。

版本策略

自 1.4.0 起,适配器的主版本号和次版本号必须与 axios 一致。例如安装了 1.21.0 时,axios 必须是 1.21.x。

这样处理后,适配器始终支持最新的 axios 特性。