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

Начало работы с Dropup

Dropup — это легковесная headless-библиотека для загрузки файлов в React, которая даёт вам полный контроль над пользовательским интерфейсом, обрабатывая всю сложную логику загрузки.

Почему Dropup?​

  • 🪶 Легковесность — Ядро всего ~10KB в сжатом виде (gzip)
  • 🎨 Headless — Полный контроль над UI с API на основе хуков
  • 📁 Drag & Drop — Встроенная поддержка перетаскивания
  • 📊 Отслеживание прогресса — Прогресс загрузки в реальном времени для каждого файла
  • 🔄 Чанковая загрузка — Разбиение больших файлов для надёжной загрузки
  • ☁️ Готов к облаку — Готовые помощники для S3, GCS и Azure
  • 🖼️ Обработка изображений — Встроенное сжатие и генерация превью
  • 📱 Кроссплатформенность — Работает с React DOM и React Native
  • 🔒 TypeScript — Полная поддержка TypeScript

Установка​

Установите Dropup с помощью вашего предпочитаемого менеджера пакетов:

npm install @samithahansaka/dropup

Peer-зависимости​

Dropup требует React 16.8 или выше (для поддержки хуков):

npm install react

Быстрый старт​

Вот простой пример для начала работы:

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

function FileUploader() {
  const {
    files,
    state,
    actions,
    getDropProps,
    getInputProps
  } = useDropup({
    accept: 'image/*',
    maxSize: 10 * 1024 * 1024, // 10MB
    multiple: true,
  });

  return (
    <div>
      {/* Зона для сброса файлов */}
      <div
        {...getDropProps()}
        style={{
          border: state.isDragging ? '2px dashed blue' : '2px dashed gray',
          padding: 40,
          textAlign: 'center',
          cursor: 'pointer',
        }}
      >
        <input {...getInputProps()} />
        <p>Перетащите файлы сюда или нажмите для выбора</p>
      </div>

      {/* Список файлов */}
      <ul>
        {files.map((file) => (
          <li key={file.id}>
            {file.name} - {file.status}
            {file.status === 'uploading' && ` (${file.progress}%)`}
            <button onClick={() => actions.remove(file.id)}>Удалить</button>
          </li>
        ))}
      </ul>

      {/* Кнопка загрузки */}
      {files.length > 0 && (
        <button onClick={() => actions.upload()}>
          Загрузить все
        </button>
      )}
    </div>
  );
}

Основные концепции​

1. Хук useDropup​

Хук useDropup — это основная точка входа. Он возвращает всё необходимое для создания интерфейса загрузки файлов:

const {
  files,           // Массив файлов со статусом, прогрессом и т.д.
  state,           // Общее состояние (isDragging, isUploading, progress)
  actions,         // Методы для загрузки, удаления, отмены, сброса
  getDropProps,    // Пропсы для вашего элемента зоны сброса
  getInputProps,   // Пропсы для скрытого input файла
} = useDropup(options);

2. Объекты файлов​

Каждый файл в массиве files содержит:

{
  id: string;          // Уникальный идентификатор
  file: File;          // Оригинальный объект File
  name: string;        // Имя файла
  size: number;        // Размер файла в байтах
  type: string;        // MIME-тип
  preview?: string;    // URL для превью (для изображений)
  status: 'idle' | 'uploading' | 'complete' | 'error';
  progress: number;    // Прогресс загрузки (0-100)
  error?: Error;       // Объект ошибки, если загрузка не удалась
  uploadedUrl?: string; // URL после успешной загрузки
}

3. Действия​

Объект actions предоставляет методы для управления загрузками:

actions.upload(fileIds?)    // Начать загрузку (всех или определённых файлов)
actions.cancel(fileId?)     // Отменить загрузку(и)
actions.remove(fileId)      // Удалить файл из списка
actions.reset()             // Очистить все файлы
actions.retry(fileIds?)     // Повторить неудавшиеся загрузки

Настройка загрузки​

Чтобы включить реальную загрузку, укажите конфигурацию загрузки:

const { files } = useDropup({
  upload: {
    url: '/api/upload',
    method: 'POST',
    headers: {
      'Authorization': 'Bearer token',
    },
  },
  autoUpload: true, // Загружать автоматически при добавлении файлов
});

Следующие шаги​