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="edit" 
      @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 }) => {
  console.log('准备上传:', file.name);
  console.log('当前选中节点:', 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: '必填文档', 
          required: true, 
          minCount: 1,
          accept: '.pdf',
          children: [] 
        }
      ]
    },
    ui: { 
      width: 260,
      resizable: true // 开启拖拽调整宽度
    }
  },
  upload: {
    enabled: true,
    action: 'https://api.example.com/upload',
    multiple: true,
    ui: {
      showTip: true // 自动显示 "支持 .pdf (最少 1 个)" 等提示
    }
  },
  table: {
    dataSource: { type: 'static', data: [] },
    columns: [
      { prop: 'name', label: '文件名' },
      { prop: 'size', label: '大小', formatter: 'fileSize' }
    ],
    ui: {
      pagination: { enabled: true, pageSize: 20 }
    }
  }
});
</script>

📖 API

Props

| 属性名 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | schema | TreeUploadSchema | 必填 | 组件的核心配置对象 | | mode | 'view' \| 'edit' | 'edit' | 视图模式。view 模式下隐藏上传和模板区域 |

Events

| 事件名 | 参数 | 说明 | | --- | --- | --- | | upload-before | { file: File, context: SchemaContext } | 上传前触发，包含文件对象和当前上下文（如选中节点） | | upload-success | response: any | 上传成功后触发 | | upload-error | error: any | 上传失败后触发 | | delete-before | file: FileItem | 用户点击删除确认后，执行删除逻辑前触发 | | delete-after | file: FileItem | 删除逻辑执行完毕后触发 |

Methods

| 方法名 | 参数 | 返回值 | 说明 | | --- | --- | --- | --- | | validate() | - | Promise<{ valid: boolean, errors: string[] }> | 校验整个树结构是否满足配置要求（如 required, minCount） |

Schema 配置详解

1. Tree Schema (tree)

| 字段 | 类型 | 说明 | | --- | --- | --- | | dataSource | { type: 'static' \| 'api', ... } | 数据源配置。api 模式需配置 url, method, responsePath | | ui | TreeUISchema | UI 配置，包含 width, resizable, showRoot 等 | | actions | TreeActionSchema[] | 树操作按钮配置（增删改等） |

节点配置 (CategoryNode):

• required: 是否必须上传文件。
• minCount / maxCount: 文件数量限制。
• maxSize: 单个文件大小限制 (Bytes)。
• accept: 允许的文件类型 (如 .jpg,.png)。
• meta.templates: 模板文件列表，选中节点时会自动显示在顶部。

2. Upload Schema (upload)

| 字段 | 类型 | 说明 | | --- | --- | --- | | action | string | 上传接口地址 | | accept | string | 全局文件类型限制 (会被节点配置覆盖) | | ui.showTip | boolean | 是否显示动态提示文案 (自动聚合大小、数量、格式限制) |

3. Table Schema (table)

| 字段 | 类型 | 说明 | | --- | --- | --- | | dataSource | { type: 'static' \| 'api', ... } | 表格数据源。api 模式支持动态参数 (如 requirementId: '${currentNode.id}') | | columns | TableColumnSchema[] | 列定义。支持 formatter: 'fileSize' | | ui.pagination | { enabled: boolean, pageSize: number } | 分页配置 (无数据时自动隐藏) |

🛠 开发与构建

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建库文件
npm run build

📄 License

MIT