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' }
    ],
    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

| 属性名 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | schema | TreeUploadSchema | 必填 | 组件的核心配置对象 | | mode | 'view' \| 'edit' | 'edit' | 全局视图模式。可被节点级 mode 覆盖 |

Events

| 事件名 | 参数 | 说明 | | --- | --- | --- | | upload-before | { file: File, context: SchemaContext, currentNode?: CategoryNode } | 上传前触发，包含文件对象和当前上下文（如选中节点） | | 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: 是否必须上传文件。
• 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)

| 字段 | 类型 | 说明 | | --- | --- | --- | | action | string | 上传接口地址 | | accept | string | 全局文件类型限制 (会被节点配置覆盖) | | beforeUpload | (payload) => boolean \| void \| Promise<boolean \| void> | 全局上传前校验钩子，返回 false 阻止上传 | | transformResponse | (res: any) => Partial<FileItem> | 将接口响应转换为组件所需的 FileItem 格式 | | ui.showTip | boolean | 是否显示动态提示文案 (自动聚合大小、数量、格式限制) |

上传前钩子执行顺序：

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

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

3. Table Schema (table)

| 字段 | 类型 | 说明 | | --- | --- | --- | | dataSource | { type: 'static' \| 'api', ... } | 表格数据源。api 模式支持动态参数 (如 requirementId: '${currentNode.id}') | | columns | TableColumnSchema[] | 列定义。支持 formatter: 'fileSize' | | actions | TableActionSchema[] | 行操作按钮配置。内置支持 preview / download / delete | | download | TableDownloadSchema | 下载配置。支持自定义文件地址字段、文件名字段和请求头 | | ui.pagination | { enabled: boolean, pageSize: number } | 分页配置 (无数据时自动隐藏) |

行级按钮控制（FileItem）：

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

下载配置（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