Pular para o conteúdo principal

Perguntas Frequentes

Perguntas e respostas comuns sobre o Dropup.

Geral​

O que é o Dropup?​

Dropup é uma biblioteca React leve e headless para upload de arquivos. Ela fornece funcionalidade de arrastar e soltar, validação de arquivos, rastreamento de progresso de upload e suporte para armazenamento em nuvem - tudo em um pacote com menos de 10KB gzipped.

Por que "headless"?​

Headless significa que o Dropup não inclui nenhum componente de UI. Ele fornece a lógica e o gerenciamento de estado, enquanto você constrói a UI da forma que desejar. Isso lhe dá controle total sobre a aparência.

Qual é o tamanho do bundle?​

  • Core (@samithahansaka/dropup): < 10KB gzipped
  • Com suporte a nuvem: +2KB por provedor
  • Com processamento de imagens: +5KB
  • Com protocolo tus: +3KB (requer tus-js-client como peer)

Suporta TypeScript?​

Sim! O Dropup é escrito em TypeScript e inclui definições de tipos abrangentes. Nenhum pacote @types é necessário.

Qual versão do React é necessária?​

React 16.8+ (requer suporte a hooks).

Uso​

Como faço upload de arquivos?​

const { files, actions } = useDropup({
  upload: { url: '/api/upload' },
});

// Upload de todos os arquivos
actions.upload();

// Upload de arquivos específicos
actions.upload(['file-id-1', 'file-id-2']);

Como lido com erros de validação?​

useDropup({
  accept: 'image/*',
  maxSize: 5 * 1024 * 1024,

  onValidationError: (errors) => {
    errors.forEach(({ file, errors }) => {
      console.log(`${file.name}: ${errors.join(', ')}`);
    });
  },
});

Posso usar lógica de upload personalizada?​

Sim! Passe uma função em vez de um objeto de configuração:

useDropup({
  upload: async (file, options) => {
    const { signal, onProgress } = options;

    // Sua lógica de upload personalizada
    const response = await customUpload(file.file, {
      signal,
      onProgress,
    });

    return { url: response.url };
  },
});

Como adiciono arquivos programaticamente?​

const { actions } = useDropup();

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

Posso ter múltiplas zonas de soltar?​

Sim! Cada chamada useDropup cria uma instância independente:

const images = useDropup({ accept: 'image/*' });
const documents = useDropup({ accept: '.pdf' });

// Use separadamente
<div {...images.getDropProps()}>...</div>
<div {...documents.getDropProps()}>...</div>

Uploads​

Como mostro o progresso do upload?​

const { files } = useDropup({ upload: { url: '/api/upload' } });

{files.map(file => (
  <div key={file.id}>
    {file.name}: {file.progress}%
  </div>
))}

Como cancelo um upload?​

const { actions } = useDropup();

// Cancelar arquivo específico
actions.cancel('file-id');

// Cancelar todos os uploads
actions.cancel();

Como tento novamente uploads que falharam?​

const { actions } = useDropup();

// Tentar novamente arquivos específicos
actions.retry(['file-id']);

// Tentar novamente todos que falharam
actions.retry();

Suporta uploads em partes?​

Sim! Use createChunkedUploader:

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

useDropup({
  upload: createChunkedUploader({
    url: '/api/upload/chunk',
    chunkSize: 5 * 1024 * 1024, // 5MB
  }),
});

Posso fazer upload diretamente para o S3?​

Sim! Use o uploader de nuvem:

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();
    },
  }),
});

Validação​

Como restrinjo tipos de arquivo?​

// Por tipo MIME
useDropup({ accept: 'image/*' });

// Por extensão
useDropup({ accept: '.pdf, .doc' });

// Múltiplos
useDropup({ accept: ['image/*', 'application/pdf'] });

Como defino limites de tamanho?​

useDropup({
  maxSize: 10 * 1024 * 1024, // 10MB máx
  minSize: 1024,             // 1KB mín
});

Como limito o número de arquivos?​

useDropup({
  maxFiles: 5,
});

Posso adicionar validação personalizada?​

Sim! Use customRules:

useDropup({
  customRules: [
    (file) => {
      if (file.name.includes('draft')) {
        return 'Arquivos de rascunho não são permitidos';
      }
      return true;
    },
  ],
});

Previews​

Como mostro previews de imagens?​

Previews são habilitados por padrão:

const { files } = useDropup();

{files.map(file => (
  file.preview && <img src={file.preview} alt="" />
))}

Preciso limpar as URLs de preview?​

Não! O Dropup revoga automaticamente as Object URLs quando os arquivos são removidos ou o componente é desmontado.

Posso desabilitar previews?​

useDropup({ generatePreviews: false });

Solução de Problemas​

Arquivos não estão sendo enviados​

  1. Verifique se upload está configurado:

    useDropup({ upload: { url: '/api/upload' } });

  2. Certifique-se de chamar actions.upload() (a menos que autoUpload: true)

  3. Verifique o console do navegador para erros de rede

URLs de preview não funcionam​

  1. Certifique-se de que o arquivo é uma imagem
  2. Verifique se generatePreviews não está false
  3. Verifique se o objeto de arquivo tem uma propriedade preview válida

Arrastar e soltar não funciona​

  1. Certifique-se de espalhar getDropProps() em um elemento container
  2. Inclua o input oculto: <input {...getInputProps()} />
  3. Verifique se disabled não está true

Erros de TypeScript​

  1. Atualize para a versão mais recente do Dropup
  2. Certifique-se de que tsconfig.json tem moduleResolution adequado
  3. Verifique se @samithahansaka/dropup está em dependencies, não devDependencies

Vazamentos de memória​

  1. Certifique-se de que componentes usando useDropup são desmontados corretamente
  2. Chame actions.reset() antes de desmontar se necessário
  3. Não armazene arquivos em estado externo sem limpeza

Compatibilidade​

Funciona com Next.js?​

Sim! Use a diretiva 'use client':

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

Funciona com React Native?​

Sim! Use o adaptador nativo:

import { NativeAdapter } from '@samithahansaka/dropup/native';

useDropup({ adapter: NativeAdapter });

Suporta SSR?​

Sim! O Dropup é seguro para SSR. Ele só usa APIs do navegador quando estão disponíveis.

Suporte a navegadores?​

Todos os navegadores modernos:

  • Chrome 60+
  • Firefox 55+
  • Safari 12+
  • Edge 79+

Contribuindo​

Como posso contribuir?​

  1. Faça um fork do repositório
  2. Crie uma branch de feature
  3. Envie um pull request

Veja CONTRIBUTING.md para detalhes.

Como reporto bugs?​

Abra uma issue em github.com/samithahansaka/dropup/issues.

Existe um roadmap?​

Verifique as issues e discussões do GitHub para recursos planejados.