FileManager 文件管理

avue-file-manager 提供前端文件夹与文件管理界面，内置图片、音视频、PDF、文本预览以及下载能力。默认上传会生成浏览器临时地址；生产环境请通过 upload-request 接入自己的上传服务。

基础用法

效果预览可直接操作下方示例

正在加载示例…

<template>
  <avue-file-manager
    v-model="files"
    v-model:folders="folders"
    :height="620"
    accept="image/*,.txt,.json,.pdf"
    :max-size="10"
    @select="handleSelect"
    @change="handleChange"
    @error="handleError"
  />
  <el-alert :title="selected ? '当前文件：' + selected : '根目录有使用说明；切换产品文档查看子目录文件'" :closable="false" />
  <p>当前文件数据：</p>
  <pre>{{ JSON.stringify(files, null, 2) }}</pre>
</template>

<script setup>
import { ref } from 'vue'
import { ElMessage } from 'element-plus'

const selected = ref('');
const folders = ref([
  { id: 'design', name: '设计素材' },
  { id: 'documents', name: '产品文档' },
  { id: 'archive', name: '历史归档', parentId: 'documents' }
])
const files = ref([
  { id: 'readme', name: '使用说明.txt', type: 'text/plain', content: '点击文件查看内容。目录只显示直属文件；上传和编辑仅在此本地示例中保存。' },
  {
    id: 'config',
    name: 'component-config.json',
    type: 'application/json',
    size: 158,
    folderId: 'documents',
    content: JSON.stringify({ preview: true, manager: true }, null, 2)
  },
  {
    id: 'brief',
    name: '项目说明.txt',
    type: 'text/plain',
    size: 96,
    folderId: 'archive',
    content: '双击文件可触发预览事件；单击后可移动、重命名或删除。'
  }
])

function handleSelect(file) {
  selected.value = file.name
}

function handleChange(value) {
  console.log('文件列表更新', value)
}

function handleError(error) {
  ElMessage.error(error.message || '文件操作失败')
}
</script>

<style scoped>
pre {
  max-height: 180px;
  padding: 12px;
  overflow: auto;
  color: #d6e4ff;
  background: #1e293b;
  border-radius: 6px;
}
</style>

文件与文件夹数据

文件至少建议提供 id、name、type、size、folderId，并按预览需求提供 url、downloadUrl 或 content。文件夹使用 id、name、parentId 表示层级关系。

const folders = [{ id: 'documents', name: '产品文档' }]
const files = [
  {
    id: 'guide',
    name: '使用说明.txt',
    type: 'text/plain',
    size: 128,
    folderId: 'documents',
    content: '文本文件内容'
  }
]

对接上传服务

upload-request 接收原生 File 和上下文，返回 URL 字符串或包含 url、status 等字段的对象。组件会在上传期间维护文件状态；失败时触发 error。

const uploadRequest = async (file, { folderId }) => {
  const formData = new FormData()
  formData.append('file', file)
  formData.append('folderId', folderId)
  const { data } = await api.upload(formData)
  return { url: data.url, status: 'success' }
}

Attributes

参数	说明	类型	默认值
modelValue / v-model	文件列表	array	[]
folders / v-model:folders	文件夹列表	array	[]
rootLabel	根目录名称	string	全部文件
height	管理区域最小高度	number / string	560
accept	原生文件选择器的类型限制	string	''
multiple	是否允许一次选择多个文件	boolean	true
maxSize	单文件最大体积，单位 MB；0 不限制	number	0
showUpload / showPreview / download	是否显示上传、预览和下载能力	boolean	true
disabled / readonly	是否禁用或只读	boolean	false
uploadRequest	自定义上传函数	function	-

Events

事件名	说明	参数
update:modelValue / change	文件列表更新	files
update:folders	文件夹列表更新	扁平 folders 数组
select / preview / download / remove	选中、预览、下载或删除文件	file
upload	选择文件并开始上传	rawFile, file
error	上传或大小校验失败	error, rawFile（原生 File）
error	文本或媒体预览失败	error, file（组件文件对象，可能为 null）
folder-change	当前文件夹切换	folderId
folder-create / folder-rename / folder-remove	文件夹新增、重命名、删除	folder

文件数据字段

字段	说明
id	稳定且唯一的文件标识；缺失时尝试使用 uid，否则生成本地标识
name	文件名；缺失时尝试取 URL 末尾名称
type	MIME 类型，用于识别预览方式；也会参考扩展名
size	文件大小，单位为字节
folderId	所属目录 ID；省略时归入根目录 __avue_root__
url / downloadUrl	预览地址 / 下载地址；只有 content 的文件可预览文本，但没有可下载 URL
content	可直接提供的文本内容，不需要再请求 URL
status	uploading / success / error，默认 success
errorMessage	上传错误说明

文件夹用 { id, name, parentId } 表示，顶层 parentId 可省略或为空字符串；输入也支持嵌套 children，更新事件始终输出扁平数组。请避免使用保留的根目录 ID __avue_root__。

根目录虽然默认名为“全部文件”，实际只展示根目录直属文件；目录切换和搜索均在当前目录内进行，不会递归检索子目录。重命名和移动文件通过 update:modelValue / change 返回新列表，没有独立的文件重命名或移动事件。文件夹只有不包含文件和子目录时才能删除。

上传与持久化

uploadRequest(rawFile, { folderId, file }) 中的 file 是组件已创建的文件记录。回调可异步返回 URL 字符串，或包含 url / downloadUrl / id / status 等字段的对象；抛出异常后组件记录错误并触发 error。

upload 在文件加入列表、开始上传时触发，不代表服务端上传成功。上传过程中和完成后都可能触发 change。未提供上传函数时使用浏览器临时 URL，组件销毁后会回收；持久化需保存服务端返回的数据，目录和文件的增删改也需在业务层对接接口。

accept 只传给浏览器文件选择器，maxSize 按 MB × 1024 × 1024 检查体积；服务端仍需按自己的业务规则校验文件。

Methods 与 Slots

方法	参数	说明
selectFiles	无	打开文件选择器
addFile	rawFile: File	异步加入并处理一个文件，返回 Promise
selectFolder	folderId	切换目录并清除已选文件；根目录为 __avue_root__
selectFile	file	选择文件并触发 select
previewFile	file	选择文件并触发 preview
downloadSelected	无	下载当前文件并触发 download
removeSelectedFile	无	移除当前文件并触发文件更新及 remove
openCreateFolder	parentId?	打开新建目录窗口，默认当前目录
openRenameFolder / openRemoveFolder	folder	打开目录重命名 / 删除确认窗口
openRenameDialog / openMoveDialog	无	打开当前选中文件的重命名 / 移动窗口

方法通过 ref 调用，传入的文件对象应来自当前文件列表或事件。disabled / readonly 用于限制界面编辑，业务仍应管理自己主动调用的方法。组件没有插槽。