更新记录

1.0.0（2025-12-31） 下载此版本

核心功能

• ✅ 支持配置化上传（uploadUrl）
• ✅ 支持自定义上传函数（customUpload）
• ✅ 支持字段映射，适配任何接口响应格式
• ✅ 支持文件预览（图片、PDF、文件）
• ✅ 支持上传进度显示
• ✅ 支持删除功能（配置删除接口或自定义删除函数）

平台支持

• ✅ 完美兼容 H5、微信小程序、APP
• ✅ 自动处理平台差异
• ✅ 支持 Vue2 和 Vue3

UI 定制

• ✅ 内置常用文件图标（PDF、Word、Excel等）
• ✅ 支持插槽自定义（文件展示、删除按钮、添加按钮）
• ✅ 支持自定义尺寸、最大数量等
• ✅ 支持多选/单选
• ✅ 完整的事件回调（choose、delete、preview、exceed）

平台兼容性

uni-app(4.83)

file-uploader 文件上传组件

简介

一个开箱即用的 uni-app 文件上传组件，支持配置化和自定义两种使用方式，内置上传、删除、预览逻辑，完美兼容 H5、微信小程序、APP。

核心特性

• ✅ 开箱即用：配置上传接口即可使用，零代码
• ✅ 灵活配置：支持简单配置和完全自定义两种方式
• ✅ 平台兼容：自动处理 H5/小程序/APP 平台差异
• ✅ 功能完整：内置上传、删除、预览、进度显示
• ✅ 字段映射：灵活适配任何接口响应格式
• ✅ 插槽定制：支持自定义文件展示、删除按钮、添加按钮
• ✅ 多端支持：完美支持 H5、微信小程序、APP
• ✅ Vue2/Vue3：同时支持 Vue2 和 Vue3

特色功能

1. 两种使用方式

方式一：简单配置（推荐） 配置上传接口，组件自动处理上传逻辑，适合大部分场景。

方式二：完全自定义 提供自定义上传、删除、预览函数，完全控制逻辑，适合复杂场景（如图片压缩、批量上传等）。

2. 核心优势

• 智能字段映射：适配任何接口响应格式，无需修改后端
• 平台差异处理：自动处理 H5/小程序/APP 的上传差异
• 完整功能：上传、删除、预览、进度显示一应俱全

安装

将 file-uploader 文件夹复制到项目的 uni_modules 目录下。

快速开始

方式一：简单配置（推荐）

只需配置上传接口，组件自动处理上传逻辑：

<template>
  <file-uploader
    v-model="fileList"
    uploadUrl="/api/upload"
    deleteUrl="/api/delete"
    :headers="{ token: 'your-token' }"
    :formData="{ type: 'image' }"
    @success="handleSuccess"
    @error="handleError"
  />
</template>

<script setup>
import { ref } from 'vue';

const fileList = ref([]);

const handleSuccess = (e) => {
  console.log('上传成功:', e.file);
};

const handleError = (e) => {
  console.error('上传失败:', e.error);
};
</script>

就这么简单！ 组件会自动：

• ✅ 处理 H5/小程序/APP 平台差异
• ✅ 显示上传进度
• ✅ 上传成功后添加到列表
• ✅ 支持删除（调用删除接口）
• ✅ 支持预览（图片/PDF/文件）

方式二：字段映射

如果接口返回的字段名不是默认的，可以配置字段映射：

<template>
  <file-uploader
    v-model="fileList"
    uploadUrl="/api/upload"

    <!-- 配置响应字段映射 -->
    responseDataKey="data"
    responseUrlKey="url"
    responseNameKey="name"
    responseIdKey="fileId"

    <!-- 配置文件对象字段名 -->
    urlKey="url"
    nameKey="name"
    idKey="fileId"
  />
</template>

示例：假设你的接口返回：

{
  "data": {
    "url": "https://xxx.com/file.jpg",
    "name": "file.jpg",
    "fileId": "123"
  }
}

组件会自动映射为：

{
  url: "https://xxx.com/file.jpg",
  name: "file.jpg",
  fileId: "123"
}

方式三：完全自定义

对于复杂场景（如图片压缩、批量上传等），可以使用自定义函数：

<template>
  <file-uploader
    v-model="fileList"
    :customUpload="handleUpload"
    :customDelete="handleDelete"
    :customPreview="handlePreview"
  />
</template>

<script setup>
import { ref } from 'vue';

const fileList = ref([]);

// 自定义上传逻辑
const handleUpload = async (file, platform) => {
  // file: H5端是 File 对象，小程序端是文件路径
  // platform: 'h5' | 'mp-weixin' | 'app'

  if (platform === 'h5') {
    // 压缩图片
    const compressedFile = await compressImage(file);

    // 上传
    const formData = new FormData();
    formData.append('file', compressedFile);

    const res = await fetch('/api/upload', {
      method: 'POST',
      body: formData
    });

    const data = await res.json();

    // 返回文件对象（会自动添加到列表）
    return {
      url: data.url,
      name: file.name,
      id: data.id
    };
  } else {
    // 小程序端上传
    const res = await uni.uploadFile({
      url: '/api/upload',
      filePath: file,
      name: 'file'
    });

    const data = JSON.parse(res.data);

    return {
      url: data.url,
      name: '文件',
      id: data.id
    };
  }
};

// 自定义删除逻辑
const handleDelete = async (file, index) => {
  // 调用删除接口
  await fetch('/api/delete', {
    method: 'POST',
    body: JSON.stringify({ id: file.id })
  });

  // 返回 true 或不返回，组件会自动从列表中移除
  // 返回 false，组件不会移除
};

// 自定义预览逻辑
const handlePreview = (file, index, fileList) => {
  // 自定义预览逻辑
  console.log('预览文件:', file);
};
</script>

API

Props

基础配置

字段映射配置

上传配置

删除配置

响应字段映射

自定义函数

其他配置

Events

Slots

使用示例

示例1：基础上传

<file-uploader
  v-model="fileList"
  uploadUrl="https://your-api.com/upload"
  :headers="{ token: 'xxx' }"
/>

示例2：适配接口响应格式

假设接口返回：

{
  "code": 200,
  "result": {
    "path": "https://xxx.com/file.jpg",
    "filename": "file.jpg",
    "fileId": "123"
  }
}

配置字段映射：

<file-uploader
  v-model="fileList"
  uploadUrl="/api/upload"
  responseDataKey="result"
  responseUrlKey="path"
  responseNameKey="filename"
  responseIdKey="fileId"
  urlKey="path"
  nameKey="filename"
  idKey="fileId"
/>

示例3：自定义响应验证

假设接口返回：

{
  "code": 1,
  "data": { "url": "xxx", "name": "xxx" },
  "msg": "上传成功"
}

配置响应验证：

<file-uploader
  v-model="fileList"
  uploadUrl="/api/upload"
  responseSuccessKey="code"
  responseSuccessValue="1"
  responseMessageKey="msg"
  responseDataKey="data"
  responseUrlKey="url"
  responseNameKey="name"
/>

示例4：图片压缩后上传

<file-uploader
  v-model="fileList"
  :customUpload="compressAndUpload"
/>

<script setup>
const compressAndUpload = async (file, platform) => {
  if (platform === 'h5') {
    // 压缩图片
    const compressedFile = await compressImage(file);

    // 上传
    const formData = new FormData();
    formData.append('file', compressedFile);

    const res = await fetch('/api/upload', {
      method: 'POST',
      body: formData
    });

    const data = await res.json();
    return data;
  }
};
</script>

示例5：仅选择图片

<file-uploader
  v-model="fileList"
  fileType="image"
  :maxCount="3"
  uploadUrl="/api/upload"
/>

示例6：自定义文件展示

<file-uploader v-model="fileList" uploadUrl="/api/upload">
  <template #file="{ file, index }">
    <view class="custom-file">
      <image :src="file.fileUrl" />
      <text>{{ file.fileName }}</text>
    </view>
  </template>
</file-uploader>

注意事项

1. 配置上传：配置 uploadUrl 即可使用，组件会自动处理上传逻辑
2. 自定义上传：配置 customUpload 可以完全自定义上传逻辑
3. 字段映射：通过 responseXxxKey 适配接口响应格式，通过 xxxKey 适配文件对象格式
4. APP支持：默认不启用，需要设置 enableApp="true"
5. 内置图标：组件内置了常用文件图标（PDF、Word、Excel等）
6. 预览功能：自动支持图片预览、PDF预览（H5/小程序）、文件下载

完整示例

查看 example/example.vue

更新日志

v1.0.0 (2025-12-31)

• 首次发布
• 支持配置化上传
• 支持自定义上传函数
• 支持字段映射
• 支持文件预览
• 支持上传进度显示
• 兼容 H5、微信小程序、APP

许可证

MIT License