Pular para o conteúdo principal

Primeiros Passos com o Dropup

Dropup é uma biblioteca React leve e headless para upload de arquivos que dá a você controle total sobre sua UI enquanto cuida de toda a lógica complexa de upload.

Por que Dropup?​

  • 🪶 Leve - Core com apenas ~10KB gzipped
  • 🎨 Headless - Controle total sobre sua UI com API baseada em hooks
  • 📁 Arrastar e Soltar - Suporte integrado para arrastar e soltar
  • 📊 Rastreamento de Progresso - Progresso de upload em tempo real para cada arquivo
  • 🔄 Uploads em Partes - Divida arquivos grandes para uploads confiáveis
  • ☁️ Pronto para Nuvem - Helpers pré-construídos para S3, GCS e Azure
  • 🖼️ Processamento de Imagens - Compressão e geração de preview integrados
  • 📱 Multiplataforma - Funciona com React DOM e React Native
  • 🔒 TypeScript - Suporte completo a TypeScript

Instalação​

Instale o Dropup usando seu gerenciador de pacotes preferido:

npm install @samithahansaka/dropup

Dependências de Pares​

Dropup requer React 16.8 ou superior (para suporte a hooks):

npm install react

Início Rápido​

Aqui está um exemplo simples para começar:

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>
      {/* Zona de soltar */}
      <div
        {...getDropProps()}
        style={{
          border: state.isDragging ? '2px dashed blue' : '2px dashed gray',
          padding: 40,
          textAlign: 'center',
          cursor: 'pointer',
        }}
      >
        <input {...getInputProps()} />
        <p>Arraste e solte arquivos aqui, ou clique para selecionar</p>
      </div>

      {/* Lista de arquivos */}
      <ul>
        {files.map((file) => (
          <li key={file.id}>
            {file.name} - {file.status}
            {file.status === 'uploading' && ` (${file.progress}%)`}
            <button onClick={() => actions.remove(file.id)}>Remover</button>
          </li>
        ))}
      </ul>

      {/* Botão de upload */}
      {files.length > 0 && (
        <button onClick={() => actions.upload()}>
          Enviar Todos
        </button>
      )}
    </div>
  );
}

Conceitos Fundamentais​

1. O Hook useDropup​

O hook useDropup é o ponto de entrada principal. Ele retorna tudo que você precisa para construir sua UI de upload de arquivos:

const {
  files,           // Array de arquivos com status, progresso, etc.
  state,           // Estado geral (isDragging, isUploading, progress)
  actions,         // Métodos para upload, remover, cancelar, resetar
  getDropProps,    // Props para seu elemento de zona de soltar
  getInputProps,   // Props para o input de arquivo oculto
} = useDropup(options);

2. Objetos de Arquivo​

Cada arquivo no array files contém:

{
  id: string;          // Identificador único
  file: File;          // Objeto File original
  name: string;        // Nome do arquivo
  size: number;        // Tamanho do arquivo em bytes
  type: string;        // Tipo MIME
  preview?: string;    // URL de preview (para imagens)
  status: 'idle' | 'uploading' | 'complete' | 'error';
  progress: number;    // Progresso do upload (0-100)
  error?: Error;       // Objeto de erro se o upload falhou
  uploadedUrl?: string; // URL após upload bem-sucedido
}

3. Ações​

O objeto actions fornece métodos para controlar uploads:

actions.upload(fileIds?)    // Iniciar upload (todos ou arquivos específicos)
actions.cancel(fileId?)     // Cancelar upload(s)
actions.remove(fileId)      // Remover um arquivo da lista
actions.reset()             // Limpar todos os arquivos
actions.retry(fileIds?)     // Tentar novamente uploads falhos

Configurando Uploads​

Para habilitar uploads reais, forneça uma configuração de upload:

const { files } = useDropup({
  upload: {
    url: '/api/upload',
    method: 'POST',
    headers: {
      'Authorization': 'Bearer token',
    },
  },
  autoUpload: true, // Fazer upload automaticamente quando arquivos são adicionados
});

Próximos Passos​