FileUploader 文件上传

用法

基础

accept 限定类型，max 限定总数。

示例加载中...

选择后上传

add 只含本次新增的文件；change 与 update:modelValue 带完整列表。

<script setup lang="ts">
import type { FileUploaderFile } from '@talex-touch/tuffex/file-uploader'
import { ref } from 'vue'

const files = ref<FileUploaderFile[]>([])

async function uploadAdded(added: FileUploaderFile[]) {
  await Promise.all(added.map(item => uploadFile(item.file)))
}
</script>

<template>
  <TxFileUploader v-model="files" accept="image/*" :max="3" @add="uploadAdded" />
</template>

命令式打开

pick() 打开原生选择器，禁用时不执行。

<script setup lang="ts">
const uploader = ref<{ pick: () => void }>()
</script>

<template>
  <TxFileUploader ref="uploader" v-model="files" />
  <TxButton @click="uploader?.pick()">浏览文件</TxButton>
</template>

最佳实践

上传时用 FileUploaderFile.file 作 payload，其余字段只驱动界面。
服务端仍要校验数量、大小、MIME 与内容；accept 与 max 只是界面约束。
上传副作用监听 add；需要完整列表时监听 change。
生成的 id 只在当前界面会话内有效，不要持久化。
误拖入代价高的紧凑表单设置 allowDrop=false。

API 参考

属性

属性名	类型	默认值	说明
`modelValue`	`FileUploaderFile[]`	`[]`	已选文件列表（受控）。
`multiple`	`boolean`	`true`	透传给原生 input。
`accept`	`string`	`'/'`	可接受的文件类型；透传给原生 input，也按同一规则过滤拖入的文件。
`disabled`	`boolean`	`false`	禁止浏览、删除与拖入。
`max`	`number`	`10`	已选文件总数上限。
`showSize`	`boolean`	`true`	在列表中显示文件大小。
`allowDrop`	`boolean`	`true`	允许拖入添加文件。
`buttonText`	`string`	`'Choose files'`	浏览按钮文案。
`dropText`	`string`	`'Drop files here'`	拖拽区主文案。
`hintText`	`string`	`'or click to browse'`	拖拽区提示文案。

事件

事件名	参数	说明
`update:modelValue`	`FileUploaderFile[]`	新增或删除后的完整列表。
`change`	`FileUploaderFile[]`	与 `update:modelValue` 同时触发。
`add`	`FileUploaderFile[]`	本次新增且被接受的文件。
`remove`	`{ id: string, value: FileUploaderFile[] }`	被删除的 id 与删除后的列表。

暴露方法

名称	类型	说明
`pick`	`() => void`	打开原生文件选择器；禁用时不执行。

类型

FileUploaderFile，列表中的一项：

字段	类型	说明
`id`	`string`	生成的唯一 id，用作列表 key 与删除参数。
`name`	`string`	原始文件名。
`size`	`number`	文件大小（字节）。
`type`	`string`	MIME 类型。
`file`	`File`	浏览器 `File` 对象。

概述

拖拽区是原生 <button type="button">，点击调用 pick()；隐藏的 <input type="file"> 接收 multiple、accept、disabled。
每次选择后清空原生 input，同一文件可以再次选择。
multiple 时新增数量受剩余容量 max - modelValue.length 限制，容量为零时不派发事件；单选时新文件替换原文件。
新增依次派发 add、update:modelValue、change；删除依次派发 remove、update:modelValue、change。
allowDrop=false 或 disabled 时忽略拖入；拖入期间根节点带 is-dragging。
showSize 时大小显示为 B、KB 或 MB。

技术实现

源码：packages/tuffex/packages/components/src/file-uploader/。

查看源码

packages/tuffex/packages/components/src/file-uploader/index.ts