Referência de Valores de Retorno

Tudo que é retornado pelo hook useDropup.

Visão Geral

const {
  files,          // Array de objetos de arquivo
  state,          // Estado atual
  actions,        // Ações disponíveis
  getDropProps,   // Props para zona de drop
  getInputProps,  // Props para elemento input
  openFileDialog, // Abrir seletor de arquivos
} = useDropup();

files

Array de objetos DropupFile representando todos os arquivos adicionados.

const { files } = useDropup();

files.forEach(file => {
  console.log(file.id);          // "abc123"
  console.log(file.name);        // "foto.jpg"
  console.log(file.size);        // 1234567
  console.log(file.type);        // "image/jpeg"
  console.log(file.status);      // "idle" | "uploading" | "complete" | "error"
  console.log(file.progress);    // 0-100
  console.log(file.preview);     // "blob:http://..." (apenas imagens)
  console.log(file.uploadedUrl); // "https://..." (após upload)
  console.log(file.error);       // DropupError (se falhou)
});

Propriedades do DropupFile

Propriedade	Tipo	Descrição
id	string	Identificador único
file	File	Objeto File nativo do navegador
name	string	Nome do arquivo
size	number	Tamanho em bytes
type	string	Tipo MIME
status	FileStatus	Status atual
progress	number	Progresso do upload (0-100)
preview	string | undefined	URL de preview para imagens
uploadedUrl	string | undefined	URL após upload bem-sucedido
response	unknown	Dados da resposta do servidor
error	DropupError | undefined	Erro se o upload falhou
meta	Record<string, unknown>	Metadados personalizados

Valores de FileStatus

Status	Descrição
'idle'	Arquivo adicionado, não enviando
'uploading'	Upload em andamento
'complete'	Upload bem-sucedido
'error'	Upload falhou
'paused'	Upload pausado (uploads retomáveis)

state

Estado atual da dropzone.

const { state } = useDropup();

console.log(state.isDragging);   // true quando arrastando sobre
console.log(state.isDragAccept); // true quando arquivos arrastados são válidos
console.log(state.isDragReject); // true quando arquivos arrastados são inválidos
console.log(state.isUploading);  // true quando algum arquivo está enviando
console.log(state.progress);     // progresso geral 0-100
console.log(state.status);       // 'idle' | 'uploading' | 'complete' | 'error'

Propriedades do State

Propriedade	Tipo	Descrição
isDragging	boolean	Arquivos sendo arrastados sobre a zona de drop
isDragAccept	boolean	Arquivos arrastados passam na validação
isDragReject	boolean	Arquivos arrastados falham na validação
isUploading	boolean	Algum arquivo sendo enviado atualmente
progress	number	Progresso médio de todos os arquivos (0-100)
status	DropupStatus	Status geral do upload

Valores de DropupStatus

Status	Descrição
'idle'	Nenhum upload em andamento
'uploading'	Um ou mais arquivos sendo enviados
'complete'	Todos os uploads finalizados com sucesso
'error'	Um ou mais uploads falharam

actions

Objeto contendo todas as ações disponíveis.

const { actions } = useDropup();

// Iniciar uploads
actions.upload();              // Enviar todos os arquivos idle
actions.upload(['id1', 'id2']); // Enviar arquivos específicos

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

// Remover arquivos
actions.remove('file-id');     // Remover arquivo específico
actions.reset();               // Remover todos os arquivos

// Tentar novamente uploads falhos
actions.retry();               // Tentar novamente todos os falhos
actions.retry(['id1']);        // Tentar novamente arquivos específicos

// Adicionar arquivos programaticamente
actions.addFiles(fileList);    // Adicionar File[] ou FileList

// Atualizar metadados do arquivo
actions.updateFileMeta('file-id', { tag: 'importante' });

Métodos de Ação

upload(fileIds?)

Iniciar upload de arquivos.

// Enviar todos os arquivos idle
actions.upload();

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

Parâmetro	Tipo	Descrição
fileIds	string[] (opcional)	IDs específicos dos arquivos para enviar

cancel(fileId?)

Cancelar uploads em andamento.

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

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

Parâmetro	Tipo	Descrição
fileId	string (opcional)	ID específico do arquivo para cancelar

remove(fileId)

Remover um arquivo da lista.

actions.remove('file-id');

Parâmetro	Tipo	Descrição
fileId	string	ID do arquivo para remover

reset()

Remover todos os arquivos e resetar estado.

actions.reset();

retry(fileIds?)

Tentar novamente uploads falhos.

// Tentar novamente todos os uploads falhos
actions.retry();

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

Parâmetro	Tipo	Descrição
fileIds	string[] (opcional)	IDs específicos dos arquivos para tentar novamente

addFiles(files)

Adicionar arquivos programaticamente.

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

// De outra fonte
actions.addFiles([file1, file2]);

Parâmetro	Tipo	Descrição
files	File[] | FileList	Arquivos para adicionar

updateFileMeta(fileId, meta)

Atualizar metadados do arquivo.

actions.updateFileMeta('file-id', {
  descricao: 'Minha foto',
  tags: ['ferias', '2024'],
});

Parâmetro	Tipo	Descrição
fileId	string	ID do arquivo para atualizar
meta	Record<string, unknown>	Metadados para mesclar

getDropProps

Retorna props para espalhar no elemento da zona de drop.

const { getDropProps, getInputProps } = useDropup();

<div {...getDropProps()}>
  <input {...getInputProps()} />
  Solte arquivos aqui
</div>

Com Props Personalizadas

<div
  {...getDropProps({
    className: 'minha-dropzone',
    onClick: (e) => {
      // Seu handler de clique personalizado
      console.log('Clicado!');
    },
  })}
>
  <input {...getInputProps()} />
</div>

Props Retornadas

Propriedade	Tipo	Descrição
onDragEnter	function	Handler de entrada de arraste
onDragOver	function	Handler de arraste sobre
onDragLeave	function	Handler de saída de arraste
onDrop	function	Handler de soltar
onClick	function	Handler de clique (abre diálogo)
role	string	Role de acessibilidade
tabIndex	number	Tab index para foco

getInputProps

Retorna props para espalhar no input de arquivo oculto.

const { getInputProps } = useDropup();

<input {...getInputProps()} />

Com Props Personalizadas

<input
  {...getInputProps({
    id: 'file-input',
    name: 'files',
  })}
/>

Props Retornadas

Propriedade	Tipo	Descrição
type	'file'	Tipo do input
accept	string	Tipos de arquivo aceitos
multiple	boolean	Permitir múltiplos arquivos
onChange	function	Handler de mudança
style	object	Estilos ocultos

openFileDialog

Função para abrir programaticamente o seletor de arquivos.

const { openFileDialog } = useDropup();

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

Exemplos de Uso

Lista de Arquivos Completa

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

  return (
    <div>
      <h3>Arquivos ({files.length})</h3>

      {files.map(file => (
        <div key={file.id}>
          {file.preview && (
            <img src={file.preview} alt="" width={50} />
          )}
          <span>{file.name}</span>
          <span>{(file.size / 1024).toFixed(1)} KB</span>
          <span>{file.status}</span>

          {file.status === 'uploading' && (
            <progress value={file.progress} max={100} />
          )}

          {file.status === 'error' && (
            <>
              <span style={{ color: 'red' }}>{file.error?.message}</span>
              <button onClick={() => actions.retry([file.id])}>Tentar Novamente</button>
            </>
          )}

          <button onClick={() => actions.remove(file.id)}>Remover</button>
        </div>
      ))}

      {state.isUploading && (
        <p>Enviando... {state.progress}%</p>
      )}

      <button
        onClick={() => actions.upload()}
        disabled={state.isUploading || files.length === 0}
      >
        Enviar Todos
      </button>

      <button onClick={() => actions.reset()}>
        Limpar Todos
      </button>
    </div>
  );
}

Estilização de Estado de Arraste

function StyledDropzone() {
  const { state, getDropProps, getInputProps } = useDropup({
    accept: 'image/*',
  });

  const getStyle = () => {
    if (state.isDragAccept) return { borderColor: 'green', backgroundColor: '#e8f5e9' };
    if (state.isDragReject) return { borderColor: 'red', backgroundColor: '#ffebee' };
    if (state.isDragging) return { borderColor: 'blue', backgroundColor: '#e3f2fd' };
    return { borderColor: 'gray', backgroundColor: 'white' };
  };

  return (
    <div
      {...getDropProps()}
      style={{
        border: '2px dashed',
        borderRadius: 8,
        padding: 40,
        textAlign: 'center',
        transition: 'all 0.2s',
        ...getStyle(),
      }}
    >
      <input {...getInputProps()} />
      {state.isDragReject ? (
        <p>Apenas imagens são aceitas!</p>
      ) : (
        <p>Solte imagens aqui</p>
      )}
    </div>
  );
}