tree-upload-vue3

Tree Upload Vue 3

基于 Vue 3 + Element Plus 的 Schema 驱动型树形文件管理组件。支持左侧树形导航、右侧文件上传与列表管理，提供高度可配置的 JSON Schema 接口。

✨ 特性

• Schema 驱动: 通过 JSON 配置生成完整界面。
• 树形导航:
  • 支持静态数据与 API 动态加载。
  • 支持 CRUD 操作（增删改）。
  • 支持拖拽调整宽度。
• 文件管理:
  • 集成文件上传（拖拽、多选、格式限制、大小限制）。
  • 列表展示（分页、排序、自定义列）。
  • 自动根据配置生成上传提示文案。
• 校验机制: 内置 validate() 方法，支持验证必填项、最小/最大文件数量等。
• 生命周期事件: 暴露上传前/后、删除前/后等关键钩子，支持上下文透传。
• 文件预览: 内置多种文件格式预览功能。
• 权限控制: 细粒度的按钮级别权限控制。
• 模式切换: 支持“查看模式”与“编辑模式”。

📦 安装

npm install tree-upload-vue3 element-plus @element-plus/icons-vue file-preview-vue3-ts

确保你的项目中已经安装了 Vue 3。

🚀 快速上手

在你的 Vue 组件中引入并使用：

<template>
  <div style="height: 600px;">
    <TreeUpload 
      ref="treeUploadRef"
      :schema="mySchema" 
      mode="view" 
      @upload-before="handleBeforeUpload"
      @upload-success="handleUploadSuccess"
    />
  </div>
</template>

<script setup lang="ts">
import { reactive, ref } from 'vue';
import { TreeUpload, type TreeUploadSchema } from 'tree-upload-vue3';
import 'tree-upload-vue3/dist/tree-upload-vue3.css'; // 引入样式

const treeUploadRef = ref();

const handleBeforeUpload = ({ file, context, currentNode }) => {
  console.log('准备上传:', file.name);
  console.log('当前选中节点:', currentNode || context.variables.currentNode);
};

const handleUploadSuccess = (response) => {
  console.log('上传成功:', response);
};

const mySchema = reactive<TreeUploadSchema>({
  version: '1.0.0',
  tree: {
    dataSource: {
      type: 'static',
      data: [
        { 
          id: '1', 
          label: '必填文档', 
          mode: 'edit',
          required: true, 
          minCount: 1,
          accept: '.pdf',
          beforeUpload: ({ file }) => {
            return !file.name.startsWith('tmp_');
          },
          meta: {
            upload: {
              beforeUpload: ({ file }) => file.name.endsWith('.pdf')
            }
          },
          children: [] 
        }
      ]
    },
    ui: { 
      width: 260,
      resizable: true // 开启拖拽调整宽度
    }
  },
  upload: {
    enabled: true,
    action: 'https://api.example.com/upload',
    multiple: true,
    beforeUpload: ({ file }) => {
      return file.size < 20 * 1024 * 1024;
    },
    // 可选：转换接口响应为组件所需的 FileItem 格式
    transformResponse: (response) => {
      return {
        id: response.data.id,
        name: response.data.filename,
        url: response.data.url
      };
    },
    ui: {
      showTip: true // 自动显示 "支持 .pdf (最少 1 个)" 等提示
    }
  },
  table: {
    dataSource: { type: 'static', data: [] },
    columns: [
      { prop: 'name', label: '文件名' },
      { prop: 'size', label: '大小', formatter: 'fileSize' },
      { prop: 'type', label: '类型', formatter: 'fileType' }
    ],
    actions: [
      { key: 'preview', label: '预览', type: 'primary' },
      { key: 'download', label: '下载' },
      { key: 'delete', label: '删除', type: 'danger' }
    ],
    download: {
      // 可选，默认从 row.url / row.name 读取
      urlField: 'url',
      nameField: 'name',
      // 文件接口需要鉴权时可透传请求头
      requestOptions: {
        headers: {
          Authorization: 'Bearer xxx'
        }
      }
    },
    ui: {
      pagination: { enabled: true, pageSize: 20 }
    }
  }
});
</script>

📖 API

Props

Events

Methods

Schema 配置详解

1. Tree Schema (tree)

节点配置 (CategoryNode):

• required: 是否必须上传文件。
• mode: 节点模式。可单独设置为 view 或 edit，优先级高于组件 mode。
• minCount / maxCount: 文件数量限制。
• maxSize: 单个文件大小限制 (Bytes)。
• accept: 允许的文件类型 (如 .jpg,.png)。
• beforeUpload: 节点级上传前校验钩子，返回 false 可阻止上传。
• meta.upload.beforeUpload: 节点 meta 内上传前校验钩子，返回 false 可阻止上传。
• meta.templates: 模板文件列表，选中节点时会自动显示在顶部。

模式优先级：

• currentNode.mode
• currentNode.meta.mode
• 组件 mode（<TreeUpload mode="...">）

当最终模式为 view 时，上传区隐藏且文件删除操作不可用；为 edit 时可上传并可删除。

2. Upload Schema (upload)

上传前钩子执行顺序：

• upload.beforeUpload（全局）
• currentNode.meta.upload.beforeUpload（节点 meta）
• currentNode.beforeUpload（节点字段）

任意一个钩子返回 false 都会取消上传。

3. Table Schema (table)

行级按钮控制（FileItem）：

• actions: 当前行允许的操作列表，支持字符串数组或对象数组。
• disabledActions: 当前行禁用的操作 key 列表。

列格式化器：

• fileSize: 将字节数格式化为 B / KB / MB。
• fileType: 将 MIME 或冗长类型值显示为标准后缀名，如 vnd.openxmlformats-officedocument.wordprocessingml.document -> docx。

下载配置（table.download）：

• urlField: 下载地址字段名，默认 url。
• nameField: 下载文件名字段名，默认 name。
• 默认行为：统一通过请求文件流后触发浏览器下载，避免部分图片 / PDF / 跨域直链在当前窗口打开。
• requestOptions.headers: 需要鉴权时透传请求头。
• requestOptions.method: 下载请求方法，默认 GET。
• requestOptions.withCredentials: 是否携带 Cookie。

🛠 开发与构建

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建库文件
npm run build

📄 License

MIT