yudao-ui-admin-vben/apps/web-naive/src/components/upload/README.md

Upload Components - Naive UI 版本

本目录包含已重构为 Naive UI 的上传组件。

组件列表

1. ImageUpload - 图片上传组件

• 文件: image-upload.vue
• 功能: 专门用于图片上传的组件，支持图片预览
• 特性:
  • 支持单图/多图上传
  • 支持图片预览（使用 NModal + NImage）
  • 支持拖拽上传
  • 自动校验文件类型和大小
  • 支持自定义上传 API
  • 支持进度显示

2. FileUpload - 文件上传组件

• 文件: file-upload.vue
• 功能: 通用文件上传组件
• 特性:
  • 支持单文件/多文件上传
  • 支持拖拽上传区域
  • 支持文件预览和下载
  • 自动校验文件类型和大小
  • 支持自定义上传 API
  • 支持进度显示
  • 支持返回文本内容（用于配置文件等）

3. InputUpload - 输入框上传组件

• 文件: input-upload.vue
• 功能: 结合输入框和文件上传的组件
• 特性:
  • 支持文本输入框或文本域
  • 支持通过上传文件自动填充内容
  • 使用 NGrid 布局，响应式设计

使用示例

ImageUpload 图片上传

<script setup lang="ts">
import { ref } from 'vue';
import { ImageUpload } from '#/components/upload';

const imageUrl = ref('');
</script>

<template>
  <ImageUpload
    v-model="imageUrl"
    :max-number="1"
    :max-size="2"
    :accept="['jpg', 'jpeg', 'png', 'gif']"
  />
</template>

FileUpload 文件上传

<script setup lang="ts">
import { ref } from 'vue';
import { FileUpload } from '#/components/upload';

const fileUrl = ref('');
</script>

<template>
  <FileUpload
    v-model="fileUrl"
    :max-number="3"
    :max-size="5"
    :accept="['pdf', 'doc', 'docx']"
    drag
  />
</template>

InputUpload 输入框上传

<script setup lang="ts">
import { ref } from 'vue';
import { InputUpload } from '#/components/upload';

const configContent = ref('');
</script>

<template>
  <InputUpload
    v-model="configContent"
    input-type="textarea"
    :file-upload-props="{
      accept: ['json', 'yaml', 'yml'],
      maxSize: 1,
    }"
  />
</template>

Props 说明

通用 Props (FileUploadProps)

属性	类型	默认值	说明
modelValue/value	string | string[]	-	v-model 绑定值
accept	string[]	[]	接受的文件类型
maxSize	number	2	文件最大大小（MB）
maxNumber	number	1	最大文件数量
multiple	boolean	false	是否支持多选
disabled	boolean	false	是否禁用
drag	boolean	false	是否支持拖拽上传
directory	string	-	上传目录
api	Function	-	自定义上传 API
showDescription	boolean	-	是否显示描述文本

ImageUpload 特有 Props

属性	类型	默认值	说明
listType	string	'picture-card'	列表类型
accept	string[]	['jpg', 'jpeg', 'png', 'gif', 'webp']	接受的图片类型
showDescription	boolean	true	是否显示描述文本

InputUpload 特有 Props

属性	类型	默认值	说明
inputType	'input' | 'textarea'	'input'	输入框类型
inputProps	InputProps	-	输入框属性
fileUploadProps	FileUploadProps	-	文件上传组件属性

Events

事件名	参数	说明
update:value	value: string | string[]	值更新事件
update:modelValue	value: string | string[]	v-model 更新事件
change	value: string | string[]	值变化事件
delete	file: UploadFileInfo	删除文件事件
preview	file: UploadFileInfo	预览文件事件（仅 FileUpload）
returnText	text: string	返回文件文本内容（仅 FileUpload）

辅助工具

useUpload

• 文件: use-upload.ts
• 功能: 提供上传相关的工具函数
• 主要方法:
  • httpRequest: 统一的文件上传请求方法
  • getUploadUrl: 获取上传 URL

useUploadType

• 功能: 处理上传类型相关的逻辑
• 主要方法:
  • getStringAccept: 获取 accept 字符串
  • getHelpText: 获取帮助文本

技术栈

• UI 框架: Naive UI
• 核心组件:
  • NUpload
  • NImage
  • NImageGroup
  • NModal
  • NButton
  • NGrid
  • NInput
• 工具库:
  • @vueuse/core
  • @vben/utils

注意事项

1. 文件状态使用 Naive UI 的状态值：'pending' | 'uploading' | 'finished' | 'error' | 'removed'
2. 所有文件 ID 使用 Naive UI 的 id 字段，而不是 uid
3. 上传前会自动校验文件类型和大小
4. 支持两种上传模式：
   • 客户端直接上传（S3）
   • 通过后端上传
5. 支持自定义上传 API，如果不提供则使用默认的上传接口

迁移指南

从 Ant Design Vue 迁移到 Naive UI 的主要变化：

1. 组件导入:

   // 旧
   import { Upload } from 'ant-design-vue';
   
   // 新
   import { NUpload } from 'naive-ui';
   

2. 文件列表类型:

   // 旧
   import type { UploadFile } from 'ant-design-vue';
   
   // 新
   import type { UploadFileInfo } from 'naive-ui';
   

3. 状态值:

   // 旧
   status: 'done';
   
   // 新
   status: 'finished';
   

4. 事件回调:

   // 旧
   @remove="handleRemove"
   function handleRemove(file: UploadFile) { }
   
   // 新
   @remove="handleRemove"
   function handleRemove(options: { file: UploadFileInfo; fileList: UploadFileInfo[] }) { }
   

5. 自定义上传:

   // 旧
   customRequest(info: UploadRequestOption) {
     info.onSuccess!(res);
   }
   
   // 新
   customRequest(options: UploadCustomRequestOptions) {
     options.onFinish();
   }
   

更新日志

v1.0.0 (2025-01-16)

• ✅ 将所有上传组件从 Ant Design Vue 重构为 Naive UI
• ✅ 保持原有功能和 API 兼容性
• ✅ 优化代码结构和类型定义
• ✅ 修复所有 linter 错误
• ✅ 添加完整的文档说明