K-Upload

Vue 3 + Axios 的轻量文件上传组件，支持拖拽、粘贴、并发/队列、取消/重试、暂停/恢复、i18n 文案与自定义插槽。

安装

npm i k-upload
# 或 pnpm add k-upload / yarn add k-upload

快速开始

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import KUpload from 'k-upload'

createApp(App)
  .use(KUpload, { locale: 'auto' }) // 'auto' 跟随系统，或 'zh-CN' | 'zh-TW' | 'en-US' | 'fr-FR' | 'de-DE'
  .mount('#app')

<template>
  <KUpload
    :uploadUrl="url"
    :autoUpload="true"
    :concurrencyLimit="3"
    :maxSizeMB="10"
    accept="image/*"
    :retryOptions="{ retries: 2, baseDelayMs: 800 }"
    @change="onChange"
    @progress="onProgress"
    @success="onSuccess"
    @error="onError"
    @errors="onErrors"
    @complete="onComplete"
  />
  
  <!-- 插槽定制（可选） -->
  <!--
  <KUpload>
    <template #actions="{ upload, select, cancelAll, clearAll }">
      <button @click="select">选择文件</button>
      <button @click="upload">开始上传</button>
      <button @click="cancelAll">全部取消</button>
      <button @click="clearAll">清空</button>
    </template>
  </KUpload>
  -->
</template>

<script setup lang="ts">
const url = '/api/upload'
function onChange(files: File[]) { console.log('选择', files) }
function onProgress(item: any, p: number) { console.log('进度', item.file.name, p) }
function onSuccess(item: any, res: unknown) { console.log('成功', item.file.name, res) }
function onError(item: any, err: unknown) { console.warn('失败', item.file.name, err) }
function onErrors(errs: unknown[]) { console.warn('本轮失败', errs.length) }
function onComplete(list: any[]) { console.log('完成', list) }
</script>

构建

npm run build

组件属性（常用）

• uploadUrl: string（必填）上传地址
• method: 'post' | 'put' | ... 默认 'post'
• headers: Record<string,string>
• data: Record<string,unknown> 额外表单字段
• fieldName: string 默认 'file'
• withCredentials: boolean 默认 false
• multiple: boolean 默认 false
• autoUpload: boolean 默认 false
• accept: string 接受的文件类型
• maxSizeMB: number 单文件体积上限（MB，0 表示不限）
• timeout: number 请求超时，默认 60000ms
• disabled: boolean 禁用
• axiosInstance: AxiosInstance 自定义实例（拦截器/鉴权）
• concurrencyLimit: number 并发上限，默认 3
• directory: boolean 目录上传开关（webkitdirectory）
• beforeUpload(file): boolean | Promise 返回 false/被 reject 将阻止上传
• retryOptions: { retries?: number; baseDelayMs?: number; retryStatusCodes?: number[] }
• messages: Record<string,string> 覆盖默认文案（见 i18n）
• locale: 'auto' | 具体语言码，组件级优先于全局

事件

• change(files: File[])
• progress(item, percent)
• success(item, response)
• error(item, error)
• errors(errors: unknown[]) 本轮失败汇总
• complete(items)

插槽

• dropzone: 上传区域（默认提供卡片）
• actions: 操作按钮区域
• item: 列表项（含 remove/retry/cancel/pause/resume 操作）
• progress: 进度条区域
• status: 状态显示区域

i18n

• 全局：

import KUpload from 'k-upload'
app.use(KUpload, {
  locale: 'auto', // 或 'zh-CN' | 'zh-TW' | 'en-US' | 'fr-FR' | 'de-DE'
  messages: {
    'zh-CN': { select: '选择文件' }
  }
})

• 局部：

<KUpload locale="de-DE" :messages="{ select: 'Auswählen' }" />

功能说明

• 拖拽/点击/粘贴选择文件
• 并发上传与排队（concurrencyLimit）
• 取消上传（单项/全部），失败重试（指数退避）
• 暂停/恢复（非分片，恢复即重新排队）
• 体积与类型限制、额外表单、跨域凭证、超时

许可

MIT