UnifiedAttachmentUpload 组件使用手册

概述

UnifiedAttachmentUpload 是一个统一的附件上传组件，支持多种文件格式的上传、预览和下载功能。该组件基于 Element Plus 的 ElUpload 组件进行了二次封装，提供了更丰富的功能和更好的用户体验。

主要特性

• 📁 支持多种文件格式（图片、文档、视频等）
• 🖼️ 智能预览（图片直接显示，视频播放，文档下载）
• 🔒 文件类型和大小限制
• 🔄 双向绑定（URL 和 Key）
• 📱 响应式设计
• 🎨 美观的界面展示

基础用法

1. 基本使用

<template>
  <div>
    <unified-attachment-upload v-model="fileUrls" />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import UnifiedAttachmentUpload from '@/components/UnifiedAttachmentUpload/index.vue'

const fileUrls = ref('')
</script>

2. 多文件上传

<template>
  <div>
    <unified-attachment-upload
      v-model="fileUrls"
      v-model:keys="fileKeys"
      :multiple="true"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import UnifiedAttachmentUpload from '@/components/UnifiedAttachmentUpload/index.vue'

const fileUrls = ref([])
const fileKeys = ref([])
</script>

Props 属性

Events 事件

方法

高级用法

1. 自定义文件类型限制

<template>
  <div>
    <unified-attachment-upload
      v-model="imageUrls"
      :accept="'.jpg,.jpeg,.png,.gif'"
      :max-size="10"
      :limit="5"
      tip="仅支持图片格式，单个文件不超过10MB"
    />
  </div>
</template>

2. 文档上传专用

<template>
  <div>
    <unified-attachment-upload
      v-model="documentUrls"
      v-model:keys="documentKeys"
      :accept="'.pdf,.doc,.docx,.xls,.xlsx,.txt'"
      :max-size="20"
      :limit="10"
      tip="仅支持文档格式，单个文件不超过20MB"
    />
  </div>
</template>

3. 监听上传事件

<template>
  <div>
    <unified-attachment-upload
      v-model="fileUrls"
      v-model:keys="fileKeys"
      @success="handleUploadSuccess"
      @error="handleUploadError"
      @remove="handleFileRemove"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import UnifiedAttachmentUpload from '@/components/UnifiedAttachmentUpload/index.vue'
import { ElMessage } from 'element-plus'

const fileUrls = ref([])
const fileKeys = ref([])

const handleUploadSuccess = (result, file) => {
  console.log('上传成功:', result)
  ElMessage.success('文件上传成功')
}

const handleUploadError = (error, file) => {
  console.error('上传失败:', error)
  ElMessage.error('文件上传失败')
}

const handleFileRemove = (removedFile) => {
  console.log('文件已移除:', removedFile)
  ElMessage.info('文件已移除')
}
</script>

4. 禁用状态

<template>
  <div>
    <unified-attachment-upload
      v-model="fileUrls"
      :disabled="true"
      tip="只读模式，不可上传"
    />
  </div>
</template>

5. 与表单集成

<template>
  <el-form :model="form" :rules="rules" ref="formRef">
    <el-form-item label="附件" prop="attachments">
      <unified-attachment-upload
        v-model="form.attachments"
        v-model:keys="form.attachmentKeys"
        :limit="10"
        @success="handleUploadSuccess"
      />
    </el-form-item>
  </el-form>
</template>

<script setup>
import { ref, reactive } from 'vue'
import UnifiedAttachmentUpload from '@/components/UnifiedAttachmentUpload/index.vue'

const formRef = ref()

const form = reactive({
  attachments: [],
  attachmentKeys: []
})

const rules = {
  attachments: [
    { required: true, message: '请上传附件', trigger: 'change' }
  ]
}

const handleUploadSuccess = () => {
  // 上传成功后触发表单验证
  formRef.value?.validateField('attachments')
}
</script>

注意事项

1. 文件大小限制

• 默认单个文件大小限制为 50MB
• 可以通过 max-size 属性自定义限制
• 超过限制的文件将无法上传

2. 文件类型限制

• 组件内置了常见文件类型的支持
• 可以通过 accept 属性自定义允许的文件类型
• 不符合类型的文件将无法上传

3. 数据格式

• modelValue 支持字符串（逗号分隔）和数组格式
• keys 同样支持字符串（逗号分隔）和数组格式
• 组件会自动保持输入和输出的格式一致

4. 预览功能

• 图片文件：直接在对话框中显示
• 视频文件：在对话框中播放
• 文档文件：显示文件信息和下载按钮

5. 样式定制

• 组件使用 SCSS 样式，可以通过覆盖 CSS 类进行定制
• 主要样式类：.unified-attachment-upload

常见问题

Q: 如何清空已上传的文件？

A: 可以通过调用组件的 clearFiles 方法：

const uploadRef = ref()
uploadRef.value.clearFiles()

Q: 如何获取文件列表？

A: 组件通过 v-model 和 v-model:keys 绑定数据，可以直接访问这些数据。

Q: 支持哪些文件类型？

A: 默认支持图片、文档、视频等常见格式，可以通过 accept 属性自定义。

Q: 文件上传到哪里？

A: 文件上传到 /business/file/upload 接口，需要携带认证 token。

最佳实践

1. 合理设置文件限制：根据业务需求设置合适的文件大小和数量限制
2. 提供清晰的提示：使用 tip 属性告诉用户可以上传什么类型的文件
3. 处理上传事件：监听 success 和 error 事件，提供用户反馈
4. 数据格式一致性：保持 modelValue 和 keys 的数据格式一致
5. 禁用状态管理：在只读或编辑状态下使用 disabled 属性

更新日志

v1.0.0

• 初始版本
• 支持多种文件格式上传
• 支持文件预览和下载
• 支持双向绑定
• 支持文件类型和大小限制