Upload 上传

通过点击或者拖拽上传文件。

基础用法

最常规的上传方式，支持多选。

yh-ui-manual.pdf
business-report.docx
example-image.png

[
  {
    "name": "yh-ui-manual.pdf",
    "status": "success",
    "uid": 1,
    "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
  },
  {
    "name": "business-report.docx",
    "status": "success",
    "uid": 3,
    "url": "data:application/vnd.openxmlformats-officedocument.wordprocessingml.document;base64,UEsDBBQAAAAIA..."
  },
  {
    "name": "example-image.png",
    "status": "success",
    "uid": 2,
    "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="
  }
]

照片墙模式

适用于头像或商品图上传。

[
  {
    "name": "nature.jpeg",
    "url": "https://images.unsplash.com/photo-1472214103451-9374bd1c798e?w=200",
    "status": "success",
    "uid": 1
  }
]

拖拽上传

[]

上传目录

通过 directory 属性启用文件夹上传。开启后，只能选择文件夹；选择文件夹后，文件夹内的文件将被展开并依次上传。

[]

手动上传

通过设置 auto-upload 属性为 false 来关闭自动上传，然后通过调用组件实例的 submit 方法来手动触发上传。

[]

图片列表模式

food.jpeg

[
  {
    "name": "food.jpeg",
    "url": "https://images.unsplash.com/photo-1498050108023-c5249f4df085?w=200",
    "status": "success",
    "uid": 1
  }
]

自定义上传

通过 http-request 属性可以完全自定义上传的实现逻辑，如使用自己的 axios 实例或者对接特定的云存储 SDK。

下载与自定义下载

通过 show-download 属性可以显示下载按钮。点击下载按钮会触发 download 事件。

TIP

关于下载功能： 组件内置了基于 Blob 的强制下载逻辑。但请注意，如果文件存储在第三方服务器且未开启跨域资源共享 (CORS)，浏览器出于安全策略可能会降级为“在新窗口打开预览”模式。建议在生产环境中确保静态资源服务器已配置 Access-Control-Allow-Origin 响应头。

yh-ui-manual.pdf
business-report.docx
example-image.png

业务进阶：上传前校验与压缩

在实际业务中，我们通常需要在上传前检查文件大小、类型，甚至进行图片压缩。

[]

自定义缩略图

通过 thumbnail-request 属性您可以完全控制预览图的生成逻辑。例如在前端对大图进行质量压缩后再展示，或者根据文件扩展名返回不同的默认占位图。

thumb-demo.jpg

用户头像上传 (单图替换)

这是一个非常实用的案例。通过 limit="1" 限制上传数量，并结合 exceed 事件实现新图直接替换旧图的“头像上传”效果。

照片墙位置与预览下载

通过 trigger-position 属性可以控制上传按钮相对于列表的位置（top | bottom | left | right）。同时，在 picture-card 模式下，开启 show-download 后，鼠标悬浮预览图中也会出现下载按钮。

覆盖前一个文件

通过设置 limit="1" 并监听 exceed 事件，可以实现在选择新文件时自动替换掉前一个文件的效果。

文件类型图标

组件会自动根据文件后缀名匹配对应的图标（Word、Excel、PDF、视频、音频、文本等）。对于未知类型，默认展示“附件”图标。您也可以通过 file-icon 插槽进行完全自定义。

财务报表.xlsx
项目规范.pdf
需求文档.docx
演示视频.mp4
背景音乐.mp3
readme.txt
未知文件.dat

财务报表.xlsx
项目规范.pdf
需求文档.docx
演示视频.mp4
背景音乐.mp3
readme.txt
未知文件.dat

自定义文件列表插槽

使用 file 作用域插槽可以完全自定义文件列表的每一项，满足更复杂的 UI 需求。

文件预览功能

通过监听 preview 事件，您可以实现点击文件时的预览逻辑。对于图片文件，组件已经内置了 viewerjs 预览引擎。

Nuxt.js 使用说明

由于 YhUpload 组件内部使用了 Viewer.js 和 FileReader 等浏览器特有 API，在 Nuxt 3 (SSR) 环境中使用时，请务必将其放置在 <ClientOnly> 组件内，或者确保仅在客户端生命周期（如 onMounted）中触发相关交互。

vue

<template>
  <ClientOnly>
    <yh-upload action="/api/upload">
      <yh-button type="primary">Nuxt 上传文件</yh-button>
    </yh-upload>
  </ClientOnly>
</template>

API

Props

属性名	说明	类型	默认值
v-model:file-list	已上传的文件列表	`UploadFile[]`	`[]`
action	上传的地址	`string`	-
method	上传的 HTTP 方法	`string`	`'POST'`
headers	设置上传的请求头部	`Record<string, string>`	`{}`
data	上传时附带的额外参数	`Record<string, unknown>`	`{}`
name	上传文件的字段名	`string`	`'file'`
multiple	是否支持多选文件	`boolean`	`false`
drag	是否启用拖拽上传	`boolean`	`false`
accept	接受上传的文件类型	`string`	-
showFileList	是否显示已上传文件列表	`boolean`	`true`
limit	限制上传数量	`number`	-
autoUpload	是否在选取文件后立即进行上传	`boolean`	`true`
listType	文件列表类型	`'text' \| 'picture' \| 'picture-card'`	`'text'`
withCredentials	支持发送 cookie 凭证信息	`boolean`	`false`
httpRequest	覆盖默认的上传行为	`(options: UploadRequestOptions) => void`	-
beforeUpload	上传文件之前的钩子	`(file: UploadRawFile) => boolean \| Promise<boolean \| Blob>`	-
beforeRemove	删除文件之前的钩子	`(file: UploadFile, fileList: UploadFile[]) => boolean \| Promise<boolean>`	-
disabled	是否禁用上传	`boolean`	`false`
thumbnailRequest	自定义缩略图生成逻辑	`(file: UploadRawFile) => Promise<string> \| string`	-
maxSize	文件大小限制 (KB)	`number`	-
directory	是否开启文件夹上传。启用后，只能选择文件夹；文件夹内的文件将被扁平化处理。	`boolean`	`false`
showDownload	是否显示下载按钮	`boolean`	`false`
triggerPosition	触发器相对于列表的位置	`'top' \| 'bottom' \| 'left' \| 'right'`	`'top'`
fileIcon	自定义文件图标或图标生成函数	`string \| ((file: UploadFile) => string)`	-
crossorigin	原生属性 crossorigin	`'anonymous' \| 'use-credentials' \| ''`	-

Events

事件名	说明	回调参数
update:fileList	当文件列表更新时触发 (支持 v-model)	`(fileList: UploadFile[])`
change	文件状态改变时触发	`(file: UploadFile, fileList: UploadFile[])`
success	文件上传成功时触发	`(response: unknown, file: UploadFile, fileList: UploadFile[])`
error	文件上传失败时触发	`(error: Error, file: UploadFile, fileList: UploadFile[])`
progress	文件上传进度改变时触发	`(event: UploadProgressEvent, file: UploadFile, fileList: UploadFile[])`
remove	文件列表移除文件时触发	`(file: UploadFile, fileList: UploadFile[])`
preview	点击文件预览时触发	`(file: UploadFile)`
download	点击文件下载时触发	`(file: UploadFile)`
exceed	当选取文件超出限制数量时触发	`(files: File[], fileList: UploadFile[])`

Slots

插槽名	说明	参数
default	默认插槽，用于放置触发上传的内容	-
trigger	触发上传的元素 (仅在非拖拽模式有效)	-
tip	提示说明文字	-
file	自定义文件列表项内容	`{ file: UploadFile }`
file-icon	自定义文件类型图标	`{ file: UploadFile }`

Expose

方法名	说明	参数
submit	手动上传待上传文件列表	-
triggerInput	手动唤起文件选择框	-
handleRemove	手动移除指定文件	`(file: UploadFile)`
handlePreview	手动触发文件预览	`(file: UploadFile)`
handleDownload	手动触发文件下载	`(file: UploadFile)`
handleFiles	手动添加并处理文件列表	`(files: File[])`

主题变量 (CSS Variables)

所有颜色变量已与全局主题系统对接，自动支持暗黑模式：

变量名	说明	默认值
`--yh-upload-dragger-bg`	拖拽区域背景色	`var(--yh-bg-color)`
`--yh-upload-dragger-border`	拖拽区域边框颜色	`var(--yh-border-color-light)`
`--yh-upload-dragger-hover-border`	拖拽区域悬停边框颜色	`var(--yh-color-primary)`
`--yh-upload-item-bg`	列表项背景色	`var(--yh-fill-color-blank)`
`--yh-upload-item-hover-bg`	列表项悬停背景色	`var(--yh-fill-color-light)`
`--yh-upload-text-color`	文字颜色	`var(--yh-text-color-regular)`
`--yh-upload-text-secondary`	次要文字颜色	`var(--yh-text-color-secondary)`
`--yh-upload-progress-bg`	进度条背景色	`var(--yh-color-primary)`
`--yh-upload-card-radius`	照片墙卡片圆角	`var(--yh-radius-md)`

Upload 上传 ​

基础用法 ​

照片墙模式 ​

拖拽上传 ​

上传目录 ​

手动上传 ​

图片列表模式 ​

自定义上传 ​

下载与自定义下载 ​

业务进阶：上传前校验与压缩 ​

自定义缩略图 ​

用户头像上传 (单图替换) ​

照片墙位置与预览下载 ​

覆盖前一个文件 ​

文件类型图标 ​

自定义文件列表插槽 ​

文件预览功能 ​

Nuxt.js 使用说明 ​

API ​

Props ​

Events ​

Slots ​

Expose ​

主题变量 (CSS Variables) ​