useUploadWithProgress

带进度监控的文件上传 composable，支持实时进度和取消上传。

Usage

使用自动导入的 useUploadWithProgress composable 进行文件上传，基于原生 XMLHttpRequest 实现，支持实时进度监控和取消上传。

<script setup lang="ts">
// 获取上传相关方法和状态
const { progress, uploading, upload, abort } = useUploadWithProgress()

// 上传文件
const handleUpload = async (files: File[]) => {
  const result = await upload('/api/upload', files, {
    onSuccess: (response) => {
      console.log('上传成功:', response)
    }
  })

  if (result.data) {
    console.log('服务器返回:', result.data)
  }
}

// 取消上传
const handleCancel = () => {
  abort()
}
</script>

<template>
  <div>
    <UFileUpload @change="handleUpload" :loading="uploading" />

    <div v-if="uploading" class="mt-4">
      <UProgress :model-value="progress" :max="100"/>
      <p>上传中: {{ progress }}%</p>
      <UButton color="red" @click="handleCancel">取消</UButton>
    </div>
  </div>
</template>

useUploadWithProgress 基于原生 XMLHttpRequest 实现，支持上传进度监听。
支持自动认证(从 session 获取 token)。
自动检查业务状态码。
内置 Toast 提示。

适用于需要展示上传进度的场景，如图片上传、文件管理等。对于无需进度的小文件，可以直接使用 $api.$fetch。

了解 API 系统的全局配置选项

单文件 vs 多文件上传

upload() 方法支持单个文件和多个文件:

// 单文件上传
await upload('/api/upload', file, {
  fieldName: 'file'
})
// FormData: file=<File>

// 多文件上传
await upload('/api/upload', [file1, file2, file3], {
  fieldName: 'files'
})
// FormData: files=<File>, files=<File>, files=<File>

额外表单字段

可以附加额外的表单字段:

await upload('/api/upload', file, {
  fieldName: 'avatar',
  fields: {
    userId: '123',
    category: 'profile',
    description: '用户头像'
  }
})

// FormData:
// avatar=<File>
// userId=123
// category=profile
// description=用户头像

业务状态码检查

useUploadWithProgress 会自动检查业务状态码:

// 成功响应
{
  code: 200,
  message: '上传成功',
  data: { url: 'https://cdn.example.com/file.jpg' }
}
// 触发 onSuccess 回调,显示成功 Toast

// 失败响应
{
  code: 400,
  message: '文件类型不支持'
}
// 触发 onError 回调,显示错误 Toast

业务状态码规则由模块配置的 response 选项控制。

取消上传

使用 abort() 方法取消正在进行的上传:

const { uploading, upload, abort } = useUploadWithProgress()

// 开始上传
upload('/api/upload', largeFile)

// 用户点击取消
const handleCancel = () => {
  if (uploading.value) {
    abort()  // 中止上传
  }
}

取消上传后:

uploading 变为 false
progress 重置为 0
error 设为 new Error('上传已取消')
不会显示 Toast 提示

认证集成

useUploadWithProgress 会自动从 session 获取 token 并添加到请求头:

// 自动添加 Authorization 头
await upload('/api/upload', file)
// 请求头: Authorization: Bearer <token>

如需额外的请求头:

await upload('/api/upload', file, {
  headers: {
    'X-Custom-Header': 'value'
  }
})

API

useUploadWithProgress()

useUploadWithProgress<T = unknown>(): { progress, uploading, data, error, upload, abort }

创建上传管理器。

Type Parameters

type

服务器响应 data 字段的类型。

Returns

返回包含以下方法和属性的上传管理器对象:

progress

Ref<number>

上传进度,范围 0-100。

uploading

Ref<boolean>

是否正在上传中。

data

Ref<ApiResponse<T> | null>

服务器响应数据。

error

Ref<Error | null>

错误信息(如果上传失败)。

upload()

(url: string, files: File | File[], options?: UploadWithProgressOptions) => Promise<{ data: ApiResponse<T> | null, error: Error | null }>

执行上传。

abort()

() => void

中止当前上传，重置进度和状态。

Changelog

6ebb7 — refactor: 更新运行时实现以适配新配置架构

f2709 — refactor: 重构 API 配置架构并新增上传下载组件

useApiAuth

API 认证 composable，提供登录、登出和 Session 管理，与 nuxt-auth-utils 无缝集成。

useDownloadWithProgress

带进度监控的文件下载 composable，支持实时进度和取消下载。