Manipulação de Arquivos

O Dropup oferece uma experiência perfeita para manipular arquivos desde o momento em que são selecionados até serem enviados.

Métodos de Seleção de Arquivos

Arrastar e Soltar

Use getDropProps() para habilitar arrastar e soltar em qualquer elemento:

function DropZone() {
  const { getDropProps, getInputProps, state } = useDropup();

  return (
    <div
      {...getDropProps()}
      style={{
        border: state.isDragging ? '2px dashed blue' : '2px dashed gray',
        backgroundColor: state.isDragging ? '#f0f8ff' : 'transparent',
      }}
    >
      <input {...getInputProps()} />
      <p>Solte arquivos aqui</p>
    </div>
  );
}

Clique para Selecionar

A zona de drop também é clicável por padrão:

<div {...getDropProps()}>
  <input {...getInputProps()} />
  <p>Clique ou arraste arquivos aqui</p>
</div>

Seleção Programática

Abra o diálogo de arquivos programaticamente:

const { openFileDialog } = useDropup();

<button onClick={openFileDialog}>
  Selecionar Arquivos
</button>

Adição Programática de Arquivos

Adicione arquivos diretamente (útil para eventos de colar ou integrações):

const { actions } = useDropup();

// Da área de transferência
document.addEventListener('paste', (e) => {
  const files = e.clipboardData?.files;
  if (files?.length) {
    actions.addFiles(files);
  }
});

Estrutura do Objeto de Arquivo

Cada arquivo no array files tem esta estrutura:

interface DropupFile {
  // Identificação
  id: string;              // Identificador único (gerado automaticamente)
  file: File;              // Objeto File nativo do navegador

  // Metadados
  name: string;            // Nome do arquivo
  size: number;            // Tamanho em bytes
  type: string;            // Tipo MIME (ex: "image/png")

  // Preview (para imagens)
  preview?: string;        // Object URL para preview

  // Estado do Upload
  status: FileStatus;      // 'idle' | 'uploading' | 'complete' | 'error' | 'paused'
  progress: number;        // 0-100

  // Resultados
  uploadedUrl?: string;    // URL após upload bem-sucedido
  response?: unknown;      // Resposta do servidor
  error?: DropupError;     // Detalhes do erro se falhou

  // Dados personalizados
  meta?: Record<string, unknown>;
}

Ciclo de Vida do Status do Arquivo

idle → uploading → complete
                 ↘ error → (retry) → uploading
                 ↘ paused → (resume) → uploading

Valores de Status

Status	Descrição
idle	Arquivo adicionado mas ainda não enviando
uploading	Enviando atualmente
complete	Upload bem-sucedido
error	Upload falhou
paused	Upload pausado (para uploads retomáveis)

Trabalhando com Arquivos

Acessando Arquivos

const { files } = useDropup();

// Todos os arquivos
console.log(files);

// Filtrar por status
const enviando = files.filter(f => f.status === 'uploading');
const completos = files.filter(f => f.status === 'complete');
const falhos = files.filter(f => f.status === 'error');

Removendo Arquivos

const { files, actions } = useDropup();

// Remover arquivo individual
actions.remove(files[0].id);

// Remover todos os arquivos
actions.reset();

Atualizando Metadados do Arquivo

const { actions } = useDropup();

// Adicionar metadados personalizados
actions.updateFileMeta(fileId, {
  campoPersonalizado: 'valor',
  categoria: 'documentos',
});

Previews de Arquivos

Para arquivos de imagem, o Dropup pode gerar URLs de preview:

const { files } = useDropup({
  generatePreviews: true, // padrão: true
});

// Use o preview na sua UI
{files.map(file => (
  file.preview && (
    <img
      src={file.preview}
      alt={file.name}
      style={{ maxWidth: 100, maxHeight: 100 }}
    />
  )
))}

Gerenciamento de Memória

URLs de preview são Object URLs que consomem memória. O Dropup as revoga automaticamente quando os arquivos são removidos ou quando o componente é desmontado.

Formatação de Tamanho de Arquivo

Auxiliar para exibir tamanhos de arquivo:

function formatFileSize(bytes: number): string {
  if (bytes === 0) return '0 Bytes';
  const k = 1024;
  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
  const i = Math.floor(Math.log(bytes) / Math.log(k));
  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
}

// Uso
{files.map(file => (
  <span>{formatFileSize(file.size)}</span>
))}

Manipulando Arquivos Grandes

Para arquivos grandes, considere uploads em partes:

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

const { files } = useDropup({
  upload: createChunkedUploader({
    url: '/api/upload',
    chunkSize: 5 * 1024 * 1024, // Partes de 5MB
  }),
});

Veja Uploads em Partes para mais detalhes.