FxUpload 文件上传

通过点击或拖拽上传文件。不依赖任何 UI 框架。

FxUpload 属于 @fx/components。

基础用法

使用 slot 自定义上传按钮的类型与文字。设置 limit 和 on-exceed 限制最大上传数量并定义超限时的处理方式。还可在 before-remove 钩子中中止移除。

<template>
  <FxUpload
    v-model:file-list="fileList"
    class="upload-demo"
    action="https://run.mocky.io/v3/9d059bf9-4660-45f2-925d-ce80ad6c4d15"
    multiple
    :on-preview="handlePreview"
    :on-remove="handleRemove"
    :before-remove="beforeRemove"
    :limit="3"
    :on-exceed="handleExceed"
  >
    <FxBtn type="primary">点击上传</FxBtn>
    <template #tip>
      <div class="fx-upload__tip">只能上传 jpg/png 文件，且不超过 500KB</div>
    </template>
  </FxUpload>
</template>

<script lang="ts" setup>
import { ref } from "vue"
import { FxUpload } from "@fx/components"
import { FxBtn } from "@fx/components"
import { fxMsg } from "@fx/components"
import { fxMsgBox } from "@fx/components"
import type { UploadProps, UploadUserFile } from "@fx/components"

const fileList = ref<UploadUserFile[]>([
  {
    name: "element-plus-logo.svg",
    url: "https://element-plus.org/images/element-plus-logo.svg",
  },
  {
    name: "element-plus-logo2.svg",
    url: "https://element-plus.org/images/element-plus-logo.svg",
  },
])

const handleRemove: UploadProps["onRemove"] = (file, uploadFiles) => {
  console.log(file, uploadFiles)
}

const handlePreview: UploadProps["onPreview"] = (uploadFile) => {
  console.log(uploadFile)
}

const handleExceed: UploadProps["onExceed"] = (files, uploadFiles) => {
  fxMsg.warning(
    `当前限制选择 3 个文件，本次选择了 ${files.length} 个文件，共选择了 ${
      files.length + uploadFiles.length
    } 个文件`,
  )
}

const beforeRemove: UploadProps["beforeRemove"] = (uploadFile) => {
  return fxMsgBox.confirm(`确定移除 ${uploadFile.name} ?`).then(
    () => true,
    () => false,
  )
}
</script>

覆盖前一个文件

设置 limit 和 on-exceed，在选择新文件时自动替换前一个文件。

<template>
  <FxUpload
    ref="upload"
    class="upload-demo"
    action="https://run.mocky.io/v3/9d059bf9-4660-45f2-925d-ce80ad6c4d15"
    :limit="1"
    :on-exceed="handleExceed"
    :auto-upload="false"
  >
    <template #trigger>
      <FxBtn type="primary">选取文件</FxBtn>
    </template>
    <FxBtn class="ml-3" type="success" @click="submitUpload">
      上传到服务器
    </FxBtn>
    <template #tip>
      <div class="fx-upload__tip" style="color: var(--fx-color-danger)">
        只能上传 1 个文件，新文件会覆盖旧文件
      </div>
    </template>
  </FxUpload>
</template>

<script lang="ts" setup>
import { ref } from "vue"
import { FxUpload, genFileId } from "@fx/components"
import { FxBtn } from "@fx/components"
import type {
  UploadInstance,
  UploadProps,
  UploadRawFile,
} from "@fx/components"

const upload = ref<UploadInstance>()

const handleExceed: UploadProps["onExceed"] = (files) => {
  upload.value!.clearFiles()
  const file = files[0] as UploadRawFile
  file.uid = genFileId()
  upload.value!.handleStart(file)
}

const submitUpload = () => {
  upload.value!.submit()
}
</script>

用户头像

使用 before-upload 钩子限制上传文件的格式与大小。

<template>
  <FxUpload
    class="avatar-uploader"
    action="https://run.mocky.io/v3/9d059bf9-4660-45f2-925d-ce80ad6c4d15"
    :show-file-list="false"
    :on-success="handleAvatarSuccess"
    :before-upload="beforeAvatarUpload"
  >
    <img v-if="imageUrl" :src="imageUrl" class="avatar" />
    <span v-else class="avatar-uploader-icon">
      <FxIcon name="ep:plus" :size="28" color="" />
    </span>
  </FxUpload>
</template>

<script lang="ts" setup>
import { ref } from "vue"
import { FxUpload } from "@fx/components"
import { FxIcon } from "@fx-core/icon"
import { fxMsg } from "@fx/components"
import type { UploadProps } from "@fx/components"

const imageUrl = ref("")

const handleAvatarSuccess: UploadProps["onSuccess"] = (_response, uploadFile) => {
  imageUrl.value = URL.createObjectURL(uploadFile.raw!)
}

const beforeAvatarUpload: UploadProps["beforeUpload"] = (rawFile) => {
  if (rawFile.type !== "image/jpeg") {
    fxMsg.error("头像图片必须是 JPG 格式!")
    return false
  } else if (rawFile.size / 1024 / 1024 > 2) {
    fxMsg.error("头像图片大小不能超过 2MB!")
    return false
  }
  return true
}
</script>

<style scoped>
.avatar-uploader .avatar {
  width: 178px;
  height: 178px;
  display: block;
  /* 防御外部通用 img 规则（.avatar-uploader .avatar 为 0,2,0，加 scoped [data-v] 后 0,3,0） */
  margin: 0;
  border: 0;
}
</style>

<style>
.avatar-uploader .fx-upload {
  border: 1px dashed var(--fx-border-color);
  border-radius: 6px;
  cursor: pointer;
  position: relative;
  overflow: hidden;
  transition: var(--fx-transition-duration-normal);
}

.avatar-uploader .fx-upload:hover {
  border-color: var(--fx-color-primary);
}

.avatar-uploader-icon {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 178px;
  height: 178px;
  color: var(--fx-text-color-placeholder);
}
</style>

照片墙

使用 list-type 改变文件列表样式。

<template>
  <FxUpload
    v-model:file-list="fileList"
    action="https://run.mocky.io/v3/9d059bf9-4660-45f2-925d-ce80ad6c4d15"
    list-type="picture-card"
    :on-preview="handlePictureCardPreview"
    :on-remove="handleRemove"
  >
    <FxIcon name="ep:plus" :size="28" color="" />
  </FxUpload>
</template>

<script lang="ts" setup>
import { ref } from "vue"
import { FxUpload, previewImage } from "@fx/components"
import type { UploadProps, UploadUserFile } from "@fx/components"
import { FxIcon } from "@fx-core/icon"

const foodUrl =
  "https://fuss10.elemecdn.com/3/63/4e7f3a15429bfda99bce42a18cdd1jpeg.jpeg?imageMogr2/thumbnail/360x360/format/webp/quality/100"
const logoUrl = "https://element-plus.org/images/element-plus-logo.svg"

const fileList = ref<UploadUserFile[]>([
  { name: "food.jpeg", url: foodUrl },
  { name: "plant-1.png", url: logoUrl },
  { name: "food.jpeg", url: foodUrl },
  { name: "plant-2.png", url: logoUrl },
  { name: "food.jpeg", url: foodUrl },
  { name: "figure-1.png", url: logoUrl },
  { name: "food.jpeg", url: foodUrl },
  { name: "figure-2.png", url: logoUrl },
])

const handleRemove: UploadProps["onRemove"] = (uploadFile, uploadFiles) => {
  console.log(uploadFile, uploadFiles)
}

const handlePictureCardPreview: UploadProps["onPreview"] = (uploadFile) => {
  previewImage(uploadFile.url!)
}
</script>

自定义缩略图

使用 file 作用域插槽自定义缩略图模板。

<template>
  <FxUpload action="#" list-type="picture-card" :auto-upload="false">
    <FxIcon name="ep:plus" :size="28" color="" />

    <template #file="{ file }">
      <div>
        <img class="fx-upload-list__item-thumbnail" :src="file.url" alt="" />
        <span class="fx-upload-list__item-actions">
          <span
            class="fx-upload-list__item-preview"
            @click="handlePictureCardPreview(file)"
          >
            <FxIcon name="ep:zoom-in" :size="20" color="" />
          </span>
          <span
            v-if="!disabled"
            class="fx-upload-list__item-delete"
            @click="handleDownload(file)"
          >
            <FxIcon name="ep:download" :size="20" color="" />
          </span>
          <span
            v-if="!disabled"
            class="fx-upload-list__item-delete"
            @click="handleRemove(file)"
          >
            <FxIcon name="ep:delete" :size="20" color="" />
          </span>
        </span>
      </div>
    </template>
  </FxUpload>
</template>

<script lang="ts" setup>
import { ref } from "vue"
import { FxUpload, previewImage } from "@fx/components"
import { FxIcon } from "@fx-core/icon"
import type { UploadFile } from "@fx/components"

const disabled = ref(false)

const handleRemove = (file: UploadFile) => {
  console.log(file)
}

const handlePictureCardPreview = (file: UploadFile) => {
  previewImage(file.url!)
}

const handleDownload = (file: UploadFile) => {
  console.log(file)
}
</script>

文件列表缩略图

<template>
  <FxUpload
    v-model:file-list="fileList"
    class="upload-demo"
    action="https://run.mocky.io/v3/9d059bf9-4660-45f2-925d-ce80ad6c4d15"
    :on-preview="handlePreview"
    :on-remove="handleRemove"
    list-type="picture"
  >
    <FxBtn type="primary">点击上传</FxBtn>
    <template #tip>
      <div class="fx-upload__tip">只能上传 jpg/png 文件，且不超过 500KB</div>
    </template>
  </FxUpload>
</template>

<script lang="ts" setup>
import { ref } from "vue"
import { FxUpload } from "@fx/components"
import { FxBtn } from "@fx/components"
import type { UploadProps, UploadUserFile } from "@fx/components"

const fileList = ref<UploadUserFile[]>([
  {
    name: "food.jpeg",
    url: "https://fuss10.elemecdn.com/3/63/4e7f3a15429bfda99bce42a18cdd1jpeg.jpeg?imageMogr2/thumbnail/360x360/format/webp/quality/100",
  },
  {
    name: "food2.jpeg",
    url: "https://fuss10.elemecdn.com/3/63/4e7f3a15429bfda99bce42a18cdd1jpeg.jpeg?imageMogr2/thumbnail/360x360/format/webp/quality/100",
  },
])

const handleRemove: UploadProps["onRemove"] = (uploadFile, uploadFiles) => {
  console.log(uploadFile, uploadFiles)
}

const handlePreview: UploadProps["onPreview"] = (file) => {
  console.log(file)
}
</script>

文件列表控制

使用 on-change 钩子控制上传文件列表。

<template>
  <FxUpload
    v-model:file-list="fileList"
    class="upload-demo"
    action="https://run.mocky.io/v3/9d059bf9-4660-45f2-925d-ce80ad6c4d15"
    :on-change="handleChange"
  >
    <FxBtn type="primary">点击上传</FxBtn>
    <template #tip>
      <div class="fx-upload__tip">只能上传 jpg/png 文件，且不超过 500KB</div>
    </template>
  </FxUpload>
</template>

<script lang="ts" setup>
import { ref } from "vue"
import { FxUpload } from "@fx/components"
import { FxBtn } from "@fx/components"
import type { UploadProps, UploadUserFile } from "@fx/components"

const fileList = ref<UploadUserFile[]>([
  {
    name: "food.jpeg",
    url: "https://fuss10.elemecdn.com/3/63/4e7f3a15429bfda99bce42a18cdd1jpeg.jpeg?imageMogr2/thumbnail/360x360/format/webp/quality/100",
  },
  {
    name: "food2.jpeg",
    url: "https://fuss10.elemecdn.com/3/63/4e7f3a15429bfda99bce42a18cdd1jpeg.jpeg?imageMogr2/thumbnail/360x360/format/webp/quality/100",
  },
])

const handleChange: UploadProps["onChange"] = () => {
  fileList.value = fileList.value.slice(-3)
}
</script>

拖拽上传

把文件拖到指定区域即可上传。

<template>
  <FxUpload
    class="upload-demo"
    drag
    action="https://run.mocky.io/v3/9d059bf9-4660-45f2-925d-ce80ad6c4d15"
    multiple
  >
    <FxIcon name="ep:upload-filled" :size="67" color="" class="fx-icon--upload" />
    <div class="fx-upload__text">将文件拖到此处，或<em>点击上传</em></div>
    <template #tip>
      <div class="fx-upload__tip">只能上传 jpg/png 文件，且不超过 500KB</div>
    </template>
  </FxUpload>
</template>

<script lang="ts" setup>
import { FxUpload } from "@fx/components"
import { FxIcon } from "@fx-core/icon"
</script>

目录上传

通过 directory 开启文件夹上传。开启后只能选择文件夹，选择后其中的文件会被拍平。

<template>
  <FxUpload
    class="upload-demo"
    drag
    action="https://run.mocky.io/v3/9d059bf9-4660-45f2-925d-ce80ad6c4d15"
    directory
    multiple
    :on-change="handleChange"
  >
    <FxIcon name="ep:upload-filled" :size="67" color="" class="fx-icon--upload" />
    <div class="fx-upload__text">将目录拖到此处，或<em>点击上传</em></div>
  </FxUpload>
</template>

<script lang="ts" setup>
import { FxUpload } from "@fx/components"
import { FxIcon } from "@fx-core/icon"
import type { UploadFile, UploadFiles } from "@fx/components"

const handleChange = (uploadFile: UploadFile, uploadFiles: UploadFiles) => {
  console.log(uploadFile, uploadFiles)
}
</script>

手动上传

<template>
  <FxUpload
    ref="uploadRef"
    class="upload-demo"
    action="https://run.mocky.io/v3/9d059bf9-4660-45f2-925d-ce80ad6c4d15"
    :auto-upload="false"
  >
    <template #trigger>
      <FxBtn type="primary">选取文件</FxBtn>
    </template>
    <FxBtn class="ml-3" type="success" @click="submitUpload">
      上传到服务器
    </FxBtn>
    <template #tip>
      <div class="fx-upload__tip">只能上传 jpg/png 文件，且不超过 500KB</div>
    </template>
  </FxUpload>
</template>

<script lang="ts" setup>
import { ref } from "vue"
import { FxUpload } from "@fx/components"
import { FxBtn } from "@fx/components"
import type { UploadInstance } from "@fx/components"

const uploadRef = ref<UploadInstance>()

const submitUpload = () => {
  uploadRef.value!.submit()
}
</script>

局部引入

import { FxUpload, FxUploadDragger } from "@fx/components"

API

Attributes

属性	说明	类型	默认值
action（必填）	请求 URL	string	'#'
headers	请求头	Headers | Record<string, any>	—
method	设置上传请求方法	string	'post'
multiple	是否允许多文件上传	boolean	false
data	附带的表单数据，支持 Awaitable 与函数	Record<string, any> | Awaitable<Record<string, any>> | ((rawFile: UploadRawFile) => Awaitable<Record<string, any>>)	{}
name	上传文件字段名	string	'file'
with-credentials	是否发送 cookie	boolean	false
show-file-list	是否显示已上传文件列表	boolean	true
drag	是否开启拖拽上传	boolean	false
accept	接受的文件类型	string	''
crossorigin	原生属性 crossorigin	'' | 'anonymous' | 'use-credentials'	—
on-preview	点击已上传文件时的钩子	(uploadFile: UploadFile) => void	—
on-remove	文件移除时的钩子	(uploadFile: UploadFile, uploadFiles: UploadFiles) => void	—
on-success	上传成功时的钩子	(response: any, uploadFile: UploadFile, uploadFiles: UploadFiles) => void	—
on-error	上传失败时的钩子	(error: Error, uploadFile: UploadFile, uploadFiles: UploadFiles) => void	—
on-progress	上传进度时的钩子	(evt: UploadProgressEvent, uploadFile: UploadFile, uploadFiles: UploadFiles) => void	—
on-change	文件状态改变时的钩子（选择 / 成功 / 失败）	(uploadFile: UploadFile, uploadFiles: UploadFiles) => void	—
on-exceed	超出限制时的钩子	(files: File[], uploadFiles: UploadUserFile[]) => void	—
before-upload	上传前钩子，返回 false 或被 reject 的 Promise 将中止上传	(rawFile: UploadRawFile) => Awaitable<void | undefined | null | boolean | File | Blob>	—
before-remove	删除前钩子，返回 false 或被 reject 的 Promise 将中止删除	(uploadFile: UploadFile, uploadFiles: UploadFiles) => Awaitable<boolean>	—
file-list / v-model:file-list	默认已上传文件列表	UploadUserFile[]	[]
list-type	文件列表类型	'text' | 'picture' | 'picture-card'	'text'
auto-upload	是否自动上传	boolean	true
http-request	覆盖默认 xhr 行为，自定义上传请求	(options: UploadRequestOptions) => XMLHttpRequest | Promise<unknown>	ajaxUpload
disabled	是否禁用上传	boolean	false
limit	最大上传数量	number	—
directory	是否支持目录上传。开启后只能选择文件夹，选择后其中的文件会被拍平	boolean	false

Slots

名称	说明	类型
default	自定义默认内容	—
trigger	触发文件对话框的内容	—
tip	提示内容	—
file	缩略图模板内容	{ file: UploadFile, index: number }

Exposes

名称	说明	类型
abort	取消上传请求。指定 file 则取消对应挂起上传；未指定则取消所有	(file?: UploadFile) => void
submit	手动上传文件列表	() => void
clearFiles	清空文件列表（此方法在 before-upload 钩子中不支持）	(status?: UploadStatus[]) => void
handleStart	手动选择文件	(rawFile: UploadRawFile) => void
handleRemove	手动移除文件。file 与 rawFile 已合并	(file: UploadFile | UploadRawFile, rawFile?: UploadRawFile) => void

类型声明

展开声明

type UploadFiles = UploadFile[]

type UploadUserFile = Omit<UploadFile, "status" | "uid"> &
  Partial<Pick<UploadFile, "status" | "uid">>

type UploadStatus = "ready" | "uploading" | "success" | "fail"

type Awaitable<T> = Promise<T> | T

interface UploadFile {
  name: string
  percentage?: number
  status: UploadStatus
  size?: number
  response?: unknown
  uid: number
  url?: string
  raw?: UploadRawFile
}

interface UploadProgressEvent extends ProgressEvent {
  percent: number
}

interface UploadRawFile extends File {
  uid: number
  isDirectory?: boolean
}

interface UploadRequestOptions {
  action: string
  method: string
  data: Record<string, string | Blob | [string | Blob, string] | string[]>
  filename: string
  file: UploadRawFile
  headers: Headers | Record<string, string | number | null | undefined>
  onError: (evt: UploadAjaxError) => void
  onProgress: (evt: UploadProgressEvent) => void
  onSuccess: (response: any) => void
  withCredentials: boolean
}

实现说明

• 4 件套结构：FxUpload 组装 upload-content（触发器 + <input type="file">）与 upload-list（文件列表），FxUploadDragger 提供拖拽容器；use-handlers 管理文件状态机与 v-model:file-list 双向绑定。
• 类名由 useNamespace('upload' / 'icon' / 'list') 生成；样式走 @fx/styles token（--color-* / --duration-*）。
• 图标使用 FxIcon（@fx-core/icon），图标名 ep:document / ep:check / ep:circle-check / ep:close / ep:delete / ep:zoom-in / ep:upload-filled 等；图标颜色由 scss 按状态/位置控制，故 FxIcon 传 color="" 禁用内联色、size 仍用 prop。
• 进度条使用 FxProgress；上传请求默认基于 XMLHttpRequest + FormData，可通过 http-request 覆盖。
• before-upload 返回 false / reject / 返回新 File/Blob 可中止或替换上传文件。