FaFileUpload 文件上传

支持拖拽、点击、粘贴、自定义上传请求和文件夹上传的文件上传组件，带进度显示和文件管理功能。

使用场景

• 附件文件上传
• 批量文件上传
• 资料文件上传
• 证据/凭证上传
• 文档上传
• 文件夹批量上传

Props

属性	类型	默认值	说明
action	string	''	默认上传请求地址，使用 httpRequest 时可不传
method	string	'post'	默认上传请求方法
headers	Headers | Record<string, any>	{}	默认上传请求头
data	Record<string, any>	{}	默认上传附加表单数据
name	string	'file'	默认上传文件字段名
afterUpload	(response: any) => string | Promise<string>	-	上传成功后从响应中提取文件 URL
beforeUpload	(file: File) => boolean | Promise<boolean>	-	上传前钩子，返回 false 时跳过该文件
httpRequest	(options: FileUploadRequestOptions) => any | Promise<any>	-	自定义上传请求，返回值会传给 afterUpload 和 onSuccess
multiple	boolean	false	是否支持多选文件
max	number	0	最大上传数量，0 表示不限制
directory	boolean	false	是否选择文件夹；启用后只能选择文件夹，文件夹内文件会扁平化上传
disabled	boolean	false	是否禁用

interface FileUploadRequestOptions {
  action: string
  method: string
  headers: Headers | Record<string, any>
  data: Record<string, any>
  name: string
  file: File
  onProgress: (percent: number) => void
}

Model

名称	类型	说明
modelValue	FileItem[]	已上传的文件列表（必需）

FileItem

interface FileItem {
  name: string
  size: number
  url?: string
  status?: 'uploading' | 'success' | 'error'
  progress?: number
  file?: File
}

Slots

名称	说明
default	自定义上传区域内容

Events

事件名	参数	说明
onSuccess	response: any, file: File	单个文件上传成功时触发
onClick	fileItem: FileItem, index: number	点击文件项时触发

粘贴上传

将鼠标移入当前组件，或通过 Tab 聚焦当前组件后，可直接按 Ctrl+V / Cmd+V 粘贴剪贴板中的文件。启用 directory 后，粘贴上传不可用。

示例

基础用法

<script setup lang="ts">
import type { FileItem } from '@fantastic-admin/components'

const fileList = ref<FileItem[]>([])

function afterUpload(response: any) {
  return response.data.url
}
</script>

<template>
  <FaFileUpload
    v-model="fileList"
    action="/api/upload"
    :after-upload="afterUpload"
  />
</template>

上传前校验

组件不再内置文件格式或大小校验。如需校验，请通过 beforeUpload 实现。

<script setup lang="ts">
import type { FileItem } from '@fantastic-admin/components'

const fileList = ref<FileItem[]>([])

function beforeUpload(file: File) {
  const isLt2M = file.size <= 2 * 1024 * 1024
  const isPdf = file.type === 'application/pdf'

  if (!isPdf) {
    useFaToast().error('只能上传 PDF 文件')
    return false
  }
  if (!isLt2M) {
    useFaToast().error('文件不能超过 2MB')
    return false
  }
  return true
}
</script>

<template>
  <FaFileUpload
    v-model="fileList"
    action="/api/upload"
    :before-upload="beforeUpload"
  />
</template>

自定义上传请求

<script setup lang="ts">
import type { FileItem, FileUploadRequestOptions } from '@fantastic-admin/components'

const fileList = ref<FileItem[]>([])

async function httpRequest({ file, onProgress }: FileUploadRequestOptions) {
  onProgress(50)

  const formData = new FormData()
  formData.append('file', file)

  const response = await fetch('/api/custom-upload', {
    method: 'POST',
    body: formData,
  })

  onProgress(100)
  return await response.json()
}
</script>

<template>
  <FaFileUpload
    v-model="fileList"
    :http-request="httpRequest"
    :after-upload="response => response.url"
  />
</template>

文件夹上传

启用 directory 后，文件选择器只能选择文件夹。选择文件夹后，文件夹内的文件会作为扁平文件列表逐个上传。

<script setup lang="ts">
import type { FileItem } from '@fantastic-admin/components'

const fileList = ref<FileItem[]>([])
</script>

<template>
  <FaFileUpload
    v-model="fileList"
    action="/api/upload"
    directory
    :max="0"
  />
</template>

注意事项

1. 文件列表：modelValue 是必需的双向绑定属性。
2. 上传进度：默认上传请求会自动更新进度；自定义 httpRequest 可调用 onProgress 更新进度。
3. 状态显示：上传中、成功、失败状态会自动显示。
4. 重新上传：失败的文件可以点击重试。
5. 删除文件：上传成功的文件可以删除。
6. 上传校验：组件不再内置格式、大小校验，请使用 beforeUpload 自行处理。