Upload 文件上传

文件上传组件。支持4 种展示模式：拖拽区、按钮触发、照片墙、头像。内置上传状态管理、自动/手动上传、图片缩略图预览、类型/大小校验、自定义校验勾子、多语言、插槽定制。

基础用法（拖拽模式）

拖拽文件到卡片区域或点击选择。上传后显示文件列表，状态指示（待上传 / 上传中 / 成功 / 失败）。

vue

<script setup lang="ts">
import { ref } from 'vue'
import { TUpload } from '@gulcc/tabler-vue'
const file = ref(null)
</script>
<template>
  <TUpload v-model="file" />
</template>

按钮模式（button）

点击按钮选择文件，适合嵌入表单工具栏。

vue

<TUpload v-model="files" list-type="button" title="上传附件" :auto-upload="false" action="/api/upload" />

照片墙（picture-card）

图片以网格卡片展示，悬停显示预览/删除操作。

vue

<TUpload v-model="files" list-type="picture-card" multiple accept="image/*" :max-count="8" />

头像上传（avatar）

圆形裁剪容器，适合用户头像上传。

vue

<TUpload list-type="avatar" title="点击上传头像" accept="image/*" />

多文件上传

设置 multiple 允许同时选择多个文件。

vue

<TUpload v-model="files" multiple />

自定义提示文字

title 和 description 属性自定义拖拽区提示内容。

vue

<TUpload v-model="file" title="上传产品图片" description="支持 JPG、PNG" />

最大数量限制

max-count 限制最多选取的文件数。

vue

<TUpload v-model="files" multiple :max-count="3" />

自定义校验

beforeUpload 勾子在上传前进行自定义校验，返回 true 通过，返回字符串显示错误。

vue

<TUpload
  v-model="file"
  :before-upload="(file) => file.size > 1024 ? '文件过大' : true"
/>

多语言

locale 属性传入文本覆盖，支持国际化。

vue

<TUpload
  v-model="files"
  :locale="{
    dropTitle: 'Drag & drop files here',
    clearAll: 'Clear all',
  }"
/>

禁用状态

disabled 使拖拽区不可交互。

vue

<TUpload v-model="file" disabled />

文件状态展示

上传列表支持四种状态：pending（待上传）、uploading（上传中+进度条）、done（成功）、error（失败+错误信息）。

vue

<TUpload v-model="files" list-type="button" />

状态通过 UploadFileInfo.status 控制，error 状态下显示 errorMessage。

草稿预加载

从后台加载草稿时，直接传入 status: 'done' 或 status: 'error' 的文件列表即可。

vue

<script setup lang="ts">
const draftFiles = ref([
  { uid: '1', name: '合同.pdf', size: 1280000, status: 'done', url: '...' },
  { uid: '2', name: '图片.png', size: 2560000, status: 'done', url: '...' },
])
</script>
<TUpload v-model="draftFiles" list-type="button" />

按钮透传属性

upload-button-props 可将任意属性透传到 button 模式的触发按钮上。

vue

<TUpload
  list-type="button"
  title="上传文件"
  :upload-button-props="{ class: 'btn-pill btn-outline-danger' }"
/>

自定义操作按钮

通过 #actions 插槽替换默认的按钮列，暴露 { file, fileList, actions }。

vue

<TUpload v-model="files" list-type="button">
  <template #actions="{ file, fileList, actions }">
    <button @click="actions.preview">预览</button>
    <button @click="actions.remove">删除</button>
    <button @click="handleCustom(file)">编辑</button>
  </template>
</TUpload>

API

Props

参数	类型	默认值	说明
`v-model`	`UploadFileInfo \| UploadFileInfo[] \| null`	`null`	已选择的文件对象
`list-type`	`'drag' \| 'button' \| 'picture-card' \| 'avatar'`	`'drag'`	展示模式
`accept`	`string`	—	允许类型，如 `'image/*,.pdf'`
`max-size`	`number`	—	单文件最大字节数
`max-count`	`number`	—	最多文件数（多选模式）
`multiple`	`boolean`	`false`	多文件
`disabled`	`boolean`	`false`	禁用
`title`	`string`	—	标题，不传显示 locale 默认
`description`	`string`	—	描述，不传显示 locale 默认
`action`	`string`	—	上传地址（POST multipart/form-data）
`name`	`string`	`'file'`	发到后台的文件参数名
`method`	`string`	`'post'`	上传请求方法
`headers`	`Record<string, string>`	—	设置上传的请求头部
`data`	`object \| (file) => object`	—	上传所需参数或返回上传参数的方法
`with-credentials`	`boolean`	`false`	上传请求时是否携带 cookie
`directory`	`boolean`	`false`	支持上传文件夹
`auto-upload`	`boolean`	`true`	选择后自动上传；设为 `false` 显示"开始上传"按钮
`show-upload-list`	`boolean \| { showPreviewIcon, showRemoveIcon, showDownloadIcon }`	`true`	是否展示上传列表，可设为对象单独控制按钮
`open-file-dialog-on-click`	`boolean`	`true`	点击打开文件对话框
`preview`	`boolean`	`true`	是否生成图片缩略图预览
`before-upload`	`(file, fileList) => boolean \| string \| Promise`	—	上传前校验
`on-before-remove`	`(file) => boolean \| Promise`	—	删除前勾子
`custom-request`	`(file, onProgress, onSuccess, onError) => void`	—	自定义上传请求
`is-image-url`	`(file) => boolean`	—	自定义缩略图是否使用 `<img>` 标签
`preview-file`	`(file) => Promise<string>`	—	自定义文件预览逻辑
`upload-button-props`	`Record<string, any>`	—	透传到上传按钮的属性（button 模式，如 `class`, `size`, `variant`）
`locale`	`Partial<UploadLocale>`	中文	国际化文案
`size-error-message`	`string`	—	大小校验提示（优先级高于 locale）
`type-error-message`	`string`	—	类型校验提示（优先级高于 locale）

UploadLocale

字段	默认值	说明
`selectedCount`	`'已选择 {count} 个文件'`	文件计数（`{count}` 替换）
`clearAll`	`'清除全部'`	清空按钮
`continueAdd`	`'继续添加文件'`	多选追加按钮
`retry`	`'重新选择'`	错误状态按钮
`sizeError`	`'文件大小超出限制'`	大小校验失败
`typeError`	`'文件类型不允许'`	类型校验失败
`uploadBtn`	`'上传'`	按钮模式按钮文字
`preview`	`'预览'`	预览按钮 tooltip
`download`	`'下载'`	下载按钮 tooltip
`uploadSuccess`	`'上传成功'`	状态标签
`uploadFailed`	`'上传失败'`	状态标签
`uploading`	`'上传中'`	状态标签

UploadFileInfo

字段	类型	说明
`uid`	`string`	唯一标识
`name`	`string`	文件名
`size`	`number`	字节数
`type`	`string`	MIME 类型
`file`	`File`	原生 File 引用
`status`	`'pending' \| 'uploading' \| 'done' \| 'error'`	上传状态
`percent`	`number`	上传进度 0-100
`thumbUrl`	`string`	图片缩略图 Blob URL
`url`	`string`	外部访问链接
`response`	`any`	上传请求响应数据
`errorMessage`	`string`	错误详情

Slots

插槽名	作用域参数	说明
`icon`	—	拖拽区图标（仅 drag/button 模式）
`title`	—	标题文字
`description`	—	描述文字
`iconRender`	`{ file: UploadFileInfo }`	自定义文件类型图标
`itemRender`	`{ file, fileList, actions: { preview, remove, download } }`	完全自定义上传列表项渲染
`actions`	`{ file, fileList, actions: { preview, remove, download } }`	自定义操作按钮列（预览/删除/下载等）

Emits

事件	参数	说明
`update:modelValue`	`(value)`	v-model 更新
`change`	`{ file: UploadFileInfo, fileList: UploadFileInfo[] }`	文件发生变化时触发
`error`	`(message: string)`	校验失败
`preview`	`(file: UploadFileInfo)`	点击预览按钮
`remove`	`(file: UploadFileInfo)`	删除文件
`download`	`(file: UploadFileInfo)`	点击下载按钮
`success`	`(file: UploadFileInfo)`	单个文件上传成功
`dblclick`	`(file: UploadFileInfo)`	双击文件列表项

Upload 文件上传 ​

基础用法（拖拽模式） ​

按钮模式（button） ​

照片墙（picture-card） ​

头像上传（avatar） ​

多文件上传 ​

自定义提示文字 ​

最大数量限制 ​

自定义校验 ​

多语言 ​

禁用状态 ​

文件状态展示 ​

草稿预加载 ​

按钮透传属性 ​

自定义操作按钮 ​

API ​

Props ​

UploadLocale ​

UploadFileInfo ​

Slots ​

Emits ​