Перейти к основному содержимому

Часто задаваемые вопросы

Распространённые вопросы и ответы о Dropup.

Общие вопросы​

Что такое Dropup?​

Dropup — это легковесная headless-библиотека React для загрузки файлов. Она предоставляет функциональность drag-and-drop, валидацию файлов, отслеживание прогресса загрузки и поддержку облачных хранилищ — всё в пакете менее 10KB в сжатом виде.

Почему "headless"?​

Headless означает, что Dropup не включает никаких UI-компонентов. Библиотека предоставляет логику и управление состоянием, в то время как вы создаёте интерфейс так, как хотите. Это даёт вам полный контроль над внешним видом.

Какой размер бандла?​

  • Ядро (@samithahansaka/dropup): < 10KB gzipped
  • С поддержкой облака: +2KB на провайдера
  • С обработкой изображений: +5KB
  • С протоколом tus: +3KB (требуется tus-js-client как peer)

Поддерживает ли TypeScript?​

Да! Dropup написан на TypeScript и включает полные определения типов. Пакет @types не требуется.

Какая версия React требуется?​

React 16.8+ (требуется поддержка хуков).

Использование​

Как загружать файлы?​

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

Drag and drop не работает​

  1. Убедитесь, что вы передаёте getDropProps() на элемент-контейнер
  2. Включите скрытый input: <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. Сделайте форк репозитория
  2. Создайте ветку для функции
  3. Отправьте pull request

См. CONTRIBUTING.md для деталей.

Как сообщить об ошибках?​

Откройте issue на github.com/samithahansaka/dropup/issues.

Есть ли план развития?​

Проверьте GitHub issues и обсуждения для запланированных функций.