Nestjs Admin

Appearance

BaUpload 组件使用文档 ​

组件概述 ​

BaUpload 组件是一个功能强大的文件上传组件，支持图片、语音、视频和普通文件的上传。它集成了多种云存储服务（本地、腾讯云 COS、阿里云 OSS），提供了完善的文件校验、预览、删除等功能。

基本用法 ​

1. 单文件图片上传 ​

vue
<template>
  <BaUpload
    v-model:file-url="avatarUrl"
    v-model:file-name="avatarName"
    type="image"
    :max-size="2"
    :format="['jpg', 'png', 'jpeg']" />
</template>

<script setup>
import { ref } from 'vue'

const avatarUrl = ref('')
const avatarName = ref('')
</script>

2. 多文件上传 ​

vue
<template>
  <BaUpload v-model:file-list="fileList" type="image" multiple :limit="5" />
</template>

<script setup>
import { ref } from 'vue'

const fileList = ref([
  { name: 'example1.jpg', url: 'https://example.com/image1.jpg' },
  { name: 'example2.png', url: 'https://example.com/image2.png' },
])
</script>

3. 视频上传 ​

vue
<template>
  <BaUpload v-model:file-url="videoUrl" type="video" :max-size="50" :format="['mp4']">
    <template #tip>
      <div>支持 MP4 格式，最大 50MB</div>
    </template>
  </BaUpload>
</template>

Props 参数详解 ​

基础属性 ​

参数类型默认值说明
fileUrlString''单文件上传时的文件URL（v-model绑定）
fileNameString''单文件上传时的文件名（v-model绑定）
imgSizeNumberundefined图片文件大小（v-model绑定）
fileListArray[]多文件上传时的文件列表（v-model绑定）

上传配置 ​

参数类型默认值说明
typeString'image'上传文件类型：'image'、'voice'、'video'、'file'
maxSizeNumberundefined文件大小限制(MB)，各类型有默认值
maxImgPxArray[10000, 10000]图片尺寸限制[宽, 高]，默认不限制
formatArrayundefined允许的文件格式，['*']为不限制
acceptString''文件选择器接受的文件类型

多选配置 ​

参数类型默认值说明
multipleBooleanfalse是否支持多文件上传
limitNumber/Stringundefined多文件上传数量限制

其他配置 ​

参数类型默认值说明
paramsObject{}上传时的额外参数

Events 事件 ​

支持的事件 ​

事件名参数说明
update:fileUrl(url)单文件URL更新
update:fileName(name)单文件名更新
update:imgSize(size)图片大小更新
update:fileList(fileList)文件列表更新
uploadSuccess({ name, url })上传成功回调
loadingChange(loading)加载状态变化

Slots 插槽 ​

默认插槽 ​

自定义上传按钮内容：

vue
<template>
  <BaUpload v-model:file-url="fileUrl">
    <div class="custom-upload-btn">
      <i class="el-icon-plus"></i>
      <span>点击上传</span>
    </div>
  </BaUpload>
</template>

tip 插槽 ​

自定义提示信息：

vue
<template>
  <BaUpload v-model:file-url="fileUrl">
    <template #tip>
      <div class="upload-tip">
        <p>支持 JPG/PNG 格式</p>
        <p>图片大小不超过 2MB</p>
      </div>
    </template>
  </BaUpload>
</template>

类型特定配置 ​

图片上传 (type="image") ​

vue
<template>
  <BaUpload
    v-model:file-url="imageUrl"
    type="image"
    :max-size="5"
    :format="['jpg', 'png', 'jpeg', 'gif']"
    :max-img-px="[1920, 1080]">
    <template #tip>
      <div>支持 JPG/PNG/GIF 格式，最大 5MB，分辨率不超过 1920×1080</div>
    </template>
  </BaUpload>
</template>

语音上传 (type="voice") ​

vue
<template>
  <BaUpload v-model:file-url="voiceUrl" type="voice" :max-size="2" :format="['amr']">
    <template #tip>
      <div>支持 AMR 格式，最大 2MB，时长不超过 60 秒</div>
    </template>
  </BaUpload>
</template>

视频上传 (type="video") ​

vue
<template>
  <BaUpload v-model:file-url="videoUrl" type="video" :max-size="100" :format="['mp4']">
    <template #tip>
      <div>支持 MP4 格式，最大 100MB，需使用标准编码</div>
    </template>
  </BaUpload>
</template>

普通文件上传 (type="file") ​

vue
<template>
  <BaUpload v-model:file-url="fileUrl" type="file" :max-size="50" :format="['doc', 'docx', 'pdf', 'ppt', 'pptx']">
    <template #tip>
      <div>支持 Word/PDF/PPT 格式，最大 50MB</div>
    </template>
  </BaUpload>
</template>

完整示例 ​

用户头像上传组件 ​

vue
<template>
  <div class="avatar-upload">
    <BaUpload
      v-model:file-url="avatarUrl"
      v-model:file-name="avatarName"
      type="image"
      :max-size="2"
      :format="['jpg', 'png', 'jpeg']"
      :max-img-px="[500, 500]"
      @upload-success="handleUploadSuccess">
      <template #tip>
        <div class="avatar-tip">
          <p>建议尺寸：300×300 像素</p>
          <p>支持 JPG/PNG 格式，大小不超过 2MB</p>
        </div>
      </template>
    </BaUpload>

    <div class="avatar-preview" v-if="avatarUrl">
      <img :src="avatarUrl" alt="头像预览" />
      <el-button @click="clearAvatar" size="small">清除</el-button>
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const avatarUrl = ref('')
const avatarName = ref('')

const handleUploadSuccess = ({ name, url }) => {
  console.log('头像上传成功:', { name, url })
  // 可以在这里调用更新用户头像的API
}

const clearAvatar = () => {
  avatarUrl.value = ''
  avatarName.value = ''
}
</script>

<style scoped>
.avatar-upload {
  display: flex;
  align-items: flex-start;
  gap: 20px;
}

.avatar-tip {
  color: #999;
  font-size: 12px;
  line-height: 1.5;
}

.avatar-preview img {
  width: 100px;
  height: 100px;
  border-radius: 50%;
  object-fit: cover;
}
</style>

商品图片管理 ​

vue
<template>
  <div class="product-images">
    <h3>商品图片</h3>

    <BaUpload
      v-model:file-list="productImages"
      type="image"
      multiple
      :limit="5"
      :max-size="3"
      :format="['jpg', 'png']"
      @upload-success="handleImageUpload">
      <template #tip>
        <div>最多上传 5 张图片，每张不超过 3MB</div>
      </template>
    </BaUpload>

    <div class="image-gallery" v-if="productImages.length">
      <div v-for="(image, index) in productImages" :key="index" class="image-item">
        <img :src="image.url" :alt="image.name" />
        <div class="image-info">
          <span>{{ image.name }}</span>
          <el-button type="danger" size="small" @click="removeImage(index)"> 删除 </el-button>
        </div>
      </div>
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const productImages = ref([])

const handleImageUpload = ({ name, url }) => {
  console.log('图片上传成功:', { name, url })
  // 可以在这里保存到服务器
}

const removeImage = (index) => {
  productImages.value.splice(index, 1)
}
</script>

文件资料上传 ​

vue
<template>
  <div class="document-upload">
    <el-form :model="formData" label-width="100px">
      <el-form-item label="文档标题">
        <el-input v-model="formData.title" />
      </el-form-item>

      <el-form-item label="文档类型">
        <el-select v-model="formData.docType">
          <el-option label="产品说明书" value="manual" />
          <el-option label="技术文档" value="tech" />
          <el-option label="合同协议" value="contract" />
        </el-select>
      </el-form-item>

      <el-form-item label="上传文件">
        <BaUpload
          v-model:file-url="formData.fileUrl"
          v-model:file-name="formData.fileName"
          type="file"
          :max-size="20"
          :format="['pdf', 'doc', 'docx']"
          :params="{ docType: formData.docType }"
          @upload-success="handleFileUpload">
          <template #tip>
            <div>支持 PDF/Word 格式，最大 20MB</div>
          </template>
        </BaUpload>
      </el-form-item>

      <el-form-item>
        <el-button type="primary" @click="submitForm">提交</el-button>
        <el-button @click="resetForm">重置</el-button>
      </el-form-item>
    </el-form>
  </div>
</template>

<script setup>
import { reactive } from 'vue'

const formData = reactive({
  title: '',
  docType: '',
  fileUrl: '',
  fileName: '',
})

const handleFileUpload = ({ name, url }) => {
  console.log('文件上传成功:', { name, url })
}

const submitForm = () => {
  if (!formData.fileUrl) {
    $message.warning('请先上传文件')
    return
  }

  // 提交表单逻辑
  console.log('提交表单:', formData)
}

const resetForm = () => {
  Object.assign(formData, {
    title: '',
    docType: '',
    fileUrl: '',
    fileName: '',
  })
}
</script>

存储配置说明 ​

组件支持多种存储方式，通过配置 cosConfig 来切换：

本地存储（默认） ​

javascript
cosConfig: {
  fileObject: 'local'
}

腾讯云 COS ​

javascript
cosConfig: {
  fileObject: 'tencentOss',
  bucketName: 'your-bucket',
  region: 'ap-beijing',
  secretId: 'your-secret-id',
  secretKey: 'your-secret-key'
}

阿里云 OSS ​

javascript
cosConfig: {
  fileObject: 'aliOss',
  bucketName: 'your-bucket',
  region: 'oss-cn-hangzhou',
  secretId: 'your-access-key-id',
  secretKey: 'your-access-key-secret',
  cosImgUrlPrefix: 'https://your-domain.com/'
}

MinIO ​

javascript
cosConfig: {
  fileObject: 'minio',
  // 相关配置...
}

注意事项 ​

  1. 文件大小限制：不同类型文件有不同的默认大小限制

    • 图片：2MB
    • 语音：2MB
    • 视频：100MB
    • 普通文件：50MB

  2. 格式限制：各类型有默认支持的格式

    • 图片：png, jpg, jpeg, svg
    • 语音：amr
    • 视频：mp4
    • 文件：doc, docx, pdf, ppt, pptx

  3. 图片尺寸校验：只对图片类型生效，通过 maxImgPx 配置

  4. 视频编码校验：视频文件会检查是否为标准 MP4 编码

  5. 语音时长限制：AMR 格式语音文件限制最长 60 秒

  6. 预览功能：图片和视频支持预览，其他类型显示文件名和下载链接

常见问题 ​

Q: 如何自定义上传按钮样式？ ​

A: 使用默认插槽可以完全自定义上传按钮的外观。

Q: 上传进度如何显示？ ​

A: 组件内置了进度条显示，包含百分比和上传速度。

Q: 如何处理上传失败？ ​

A: 组件会自动显示错误提示，也可以监听相关事件进行自定义处理。

Q: 支持断点续传吗？ ​

A: 当前版本暂不支持断点续传，大文件建议分片上传。

Q: 如何限制上传数量？ ​

A: 使用 multiple 和 limit 属性控制多文件上传的数量限制。