跳至主要內容

常見問題

關於 Dropup 的常見問題與解答。

一般問題​

什麼是 Dropup？​

Dropup 是一個輕量級、無樣式的 React 檔案上傳函式庫。它提供拖放功能、檔案驗證、上傳進度追蹤，以及雲端儲存支援 - 所有功能都包含在一個壓縮後小於 10KB 的套件中。

為什麼是「無樣式」？​

無樣式意味著 Dropup 不包含任何 UI 元件。它提供邏輯和狀態管理，而您可以隨心所欲地建構 UI。這讓您完全控制外觀和感覺。

套件大小是多少？​

  • 核心套件（@samithahansaka/dropup）：壓縮後 < 10KB
  • 含雲端支援：每個供應商 +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。

如何回報錯誤？​

在 github.com/samithahansaka/dropup/issues 開啟 issue。

有路線圖嗎？​

查看 GitHub issues 和討論區了解計劃中的功能。