跳转到主要内容

常见问题

关于 Dropup 的常见问题和解答。

通用问题​

Dropup 是什么？​

Dropup 是一个轻量级的无头 React 文件上传库。它提供拖放功能、文件验证、上传进度追踪和云存储支持——所有这些功能的包大小不到 10KB（gzip 压缩后）。

为什么是"无头"的？​

无头意味着 Dropup 不包含任何 UI 组件。它提供逻辑和状态管理，而您可以按照自己的方式构建 UI。这让您可以完全控制外观和交互。

包大小是多少？​

  • 核心包 (@samithahansaka/dropup)：< 10KB gzip
  • 包含云存储支持：每个提供商 +2KB
  • 包含图片处理：+5KB
  • 包含 tus 协议：+3KB（需要 tus-js-client 作为对等依赖）

支持 TypeScript 吗？​

是的！Dropup 使用 TypeScript 编写，包含完整的类型定义。不需要额外安装 @types 包。

需要什么版本的 React？​

React 16.8+（需要 hooks 支持）。

使用方法​

如何上传文件？​

const { files, actions } = useDropup({
  upload: { url: '/api/upload' },
});

// 上传所有文件
actions.upload();

// 上传特定文件
actions.upload(['file-id-1', 'file-id-2']);

如何处理验证错误？​

useDropup({
  accept: 'image/*',
  maxSize: 5 * 1024 * 1024,

  onValidationError: (errors) => {
    errors.forEach(({ file, errors }) => {
      console.log(`${file.name}: ${errors.join(', ')}`);
    });
  },
});

可以使用自定义上传逻辑吗？​

可以！传入函数而不是配置对象：

useDropup({
  upload: async (file, options) => {
    const { signal, onProgress } = options;

    // 您的自定义上传逻辑
    const response = await customUpload(file.file, {
      signal,
      onProgress,
    });

    return { url: response.url };
  },
});

如何以编程方式添加文件？​

const { actions } = useDropup();

// 从剪贴板
document.addEventListener('paste', (e) => {
  const files = e.clipboardData?.files;
  if (files) {
    actions.addFiles(files);
  }
});

可以有多个拖放区域吗？​

可以！每次调用 useDropup 都会创建一个独立的实例：

const images = useDropup({ accept: 'image/*' });
const documents = useDropup({ accept: '.pdf' });

// 分别使用
<div {...images.getDropProps()}>...</div>
<div {...documents.getDropProps()}>...</div>

上传​

如何显示上传进度？​

const { files } = useDropup({ upload: { url: '/api/upload' } });

{files.map(file => (
  <div key={file.id}>
    {file.name}: {file.progress}%
  </div>
))}

如何取消上传？​

const { actions } = useDropup();

// 取消特定文件
actions.cancel('file-id');

// 取消所有上传
actions.cancel();

如何重试失败的上传？​

const { actions } = useDropup();

// 重试特定文件
actions.retry(['file-id']);

// 重试所有失败的上传
actions.retry();

支持分块上传吗？​

支持！使用 createChunkedUploader：

import { createChunkedUploader } from '@samithahansaka/dropup';

useDropup({
  upload: createChunkedUploader({
    url: '/api/upload/chunk',
    chunkSize: 5 * 1024 * 1024, // 5MB
  }),
});

可以直接上传到 S3 吗？​

可以！使用云上传器：

import { createS3Uploader } from '@samithahansaka/dropup/cloud/s3';

useDropup({
  upload: createS3Uploader({
    getPresignedUrl: async (file) => {
      const res = await fetch('/api/s3/presign', {
        method: 'POST',
        body: JSON.stringify({ filename: file.name }),
      });
      return res.json();
    },
  }),
});

验证​

如何限制文件类型？​

// 按 MIME 类型
useDropup({ accept: 'image/*' });

// 按扩展名
useDropup({ accept: '.pdf, .doc' });

// 多种类型
useDropup({ accept: ['image/*', 'application/pdf'] });

如何设置大小限制？​

useDropup({
  maxSize: 10 * 1024 * 1024, // 最大 10MB
  minSize: 1024,             // 最小 1KB
});

如何限制文件数量？​

useDropup({
  maxFiles: 5,
});

可以添加自定义验证吗？​

可以！使用 customRules：

useDropup({
  customRules: [
    (file) => {
      if (file.name.includes('draft')) {
        return '不允许草稿文件';
      }
      return true;
    },
  ],
});

预览​

如何显示图片预览？​

预览默认启用：

const { files } = useDropup();

{files.map(file => (
  file.preview && <img src={file.preview} alt="" />
))}

需要清理预览 URL 吗？​

不需要！Dropup 会在文件被移除或组件卸载时自动撤销 Object URL。

可以禁用预览吗？​

useDropup({ generatePreviews: false });

故障排除​

文件没有上传​

  1. 检查 upload 是否已配置：

    useDropup({ upload: { url: '/api/upload' } });

  2. 确保调用了 actions.upload()（除非设置了 autoUpload: true）

  3. 检查浏览器控制台的网络错误

预览 URL 不工作​

  1. 确保文件是图片
  2. 检查 generatePreviews 没有设置为 false
  3. 验证文件对象有有效的 preview 属性

拖放不工作​

  1. 确保在容器元素上展开了 getDropProps()
  2. 包含隐藏的输入框：<input {...getInputProps()} />
  3. 检查 disabled 没有设置为 true

TypeScript 错误​

  1. 更新到最新版本的 Dropup
  2. 确保 tsconfig.json 有正确的 moduleResolution
  3. 检查 @samithahansaka/dropup 在 dependencies 中，而不是 devDependencies

内存泄漏​

  1. 确保使用 useDropup 的组件正确卸载
  2. 如果需要，在卸载前调用 actions.reset()
  3. 不要在没有清理的情况下将文件存储在外部状态中

兼容性​

可以与 Next.js 一起使用吗？​

可以！使用 'use client' 指令：

'use client';
import { useDropup } from '@samithahansaka/dropup';

可以与 React Native 一起使用吗？​

可以！使用原生适配器：

import { NativeAdapter } from '@samithahansaka/dropup/native';

useDropup({ adapter: NativeAdapter });

支持 SSR 吗？​

支持！Dropup 是 SSR 安全的。它只在浏览器 API 可用时才使用它们。

浏览器支持？​

所有现代浏览器：

  • Chrome 60+
  • Firefox 55+
  • Safari 12+
  • Edge 79+

贡献​

如何贡献？​

  1. Fork 仓库
  2. 创建功能分支
  3. 提交 Pull Request

详情请参阅 CONTRIBUTING.md。

如何报告 bug？​

在 github.com/samithahansaka/dropup/issues 提交 issue。

有路线图吗？​

请查看 GitHub issues 和 discussions 了解计划中的功能。

编辑此页
最后更新 于 由 Samitha Widanage