DropZone

Área para soltar ou escolher arquivos, com lista de envio e progresso.

O DropZone (do HeroUI Pro) recebe arquivos de duas formas: arrastar e soltar, ou o botão que abre o seletor do sistema. No Admin ele é o passo de arquivo da importação de Pedidos por CSV, e também serve para o logotipo da Loja. A lista de arquivos com progresso, tentar de novo e remover vive junto.

import { DropZone } from "@rastreio-x/ui";

Padrão

DropZone.Area com Icon, Label, Description e Trigger, mais um DropZone.Input oculto para o seletor. O texto do Trigger é o do botão visível.

Arraste o arquivo aquiOu escolha um arquivo do computador.

CSV da importação

accept no Input filtra o seletor, e getDropOperation na Area recusa o que não for CSV ao arrastar. onSelect recebe a lista; no onDrop, busque o arquivo com getFile().

Arraste o CSV aquiColunas: Pedido, Cliente, CEP e Itens. Até 5 MB.

Nenhum arquivo escolhido

Só imagem

Troque o ícone, o tipo aceito e o texto, como para o logotipo da Loja.

Solte o logotipo da LojaPNG, JPG ou SVG, até 2 MB.

Lista de arquivos

DropZone.FileList com FileItem por arquivo. O status (uploading, complete, failed) muda o visual; a barra de progresso só aparece quando faz sentido, e arquivos com falha ganham uma ação de tentar de novo.

Arraste os CSV aquiAté 5 MB por arquivo.

pedidos-outubro.csv184 KB · pronto

pedidos-setembro.csv2,1 MB · lendo 42%

pedidos-agosto.csv8,4 MB · arquivo grande demais

Desabilitado

isDisabled na Area e no Trigger. Diga na descrição o que falta para habilitar.

Importação indisponívelEscolha uma Fonte antes de importar Pedidos.

Anatomia

DropZone
├── DropZone.Area
├── DropZone.Description
├── DropZone.FileFormatIcon
├── DropZone.FileInfo
├── DropZone.FileItem
├── DropZone.FileList
├── DropZone.FileMeta
├── DropZone.FileName
├── DropZone.FileProgress
├── DropZone.FileProgressFill
├── DropZone.FileProgressTrack
├── DropZone.FileRemoveTrigger
├── DropZone.FileRetryTrigger
├── DropZone.Icon
├── DropZone.Input
├── DropZone.Label
└── DropZone.Trigger

DropZone.Area: a área que aceita soltar; recebe onDrop e getDropOperation.
Icon, Label, Description e Trigger: o conteúdo da área.
DropZone.Input: o <input type="file"> oculto, com accept, multiple e onSelect.
FileList, FileItem, FileFormatIcon, FileInfo, FileName, FileMeta, FileProgress e FileRemoveTrigger: a lista de envio.

Propriedades

Raiz (DropZone):

DropZone
Prop	Tipo	Padrão	Descrição
`children`*	`React.ReactNode`	-	Conteúdo do componente.
`className`	`string`	-	Classes CSS aplicadas ao elemento.
`render`	`DOMRenderFunction<E, undefined>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`style`	`React.JSX.IntrinsicElements[E]['style']`	-	Estilos em linha aplicados ao elemento.

Área (DropZone.Area):

DropZone.Area
Prop	Tipo	Padrão	Descrição
`aria-label`	`string`	-	Nome acessível, lido por leitores de tela quando não há rótulo visível.
`children`	`ChildrenOrFunction<DropZoneRenderProps>`	-	Conteúdo do componente.
`className`	`ClassNameOrFunction<DropZoneRenderProps>`	`'react-aria-DropZone'`	Classes CSS aplicadas ao elemento.
`getDropOperation`	`((types: DragTypes, allowedOperations: DropOperation[]) => DropOperation)`	-	Define a operação (copiar, mover ou vincular) ao soltar um arrasto sobre a área.
`isDisabled`	`boolean`	-	Desabilita o componente: sem foco, clique nem envio.
`onDrop`	`((e: DropEvent) => void)`	-	Chamada ao soltar arquivos ou itens sobre a área.
`onDropActivate`	`((e: DropActivateEvent) => void)`	-	Chamada quando um arrasto válido fica parado sobre a área.
`onDropEnter`	`((e: DropEnterEvent) => void)`	-	Chamada quando um arrasto válido entra na área.
`onDropExit`	`((e: DropExitEvent) => void)`	-	Chamada quando um arrasto válido sai da área.
`onDropMove`	`((e: DropMoveEvent) => void)`	-	Chamada enquanto um arrasto válido se move dentro da área.
`render`	`DOMRenderFunction<'div', DropZoneRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`style`	`StyleOrFunction<DropZoneRenderProps>`	-	Estilos em linha aplicados ao elemento.

Seletor (DropZone.Input):

Prop	Tipo	Descrição
`accept`	`string`	Tipos aceitos no seletor, como `.csv,text/csv` ou `image/*`.
`multiple`	`boolean`	Permite escolher mais de um arquivo.
`onSelect`	`(files: FileList) => void`	Chamado com os arquivos escolhidos pelo seletor.

Item de arquivo (DropZone.FileItem):

Prop	Tipo	Descrição
`status`	`"uploading" \| "complete" \| "failed"`	Estado do envio; muda o visual do item.

O FileItem também aceita as propriedades de um div animado do motion; a lista completa tem mais de 300 entradas e fica fora da tabela.

Animações

motion.dev
CSS
indicativo

A lista de arquivos usa o motion do Pro: itens entram e saem com layout animado (AnimatePresence), e a barra de progresso avança com transição curta. A área muda de aparência ao receber um arquivo por cima. Com prefers-reduced-motion, o movimento de layout fica sem deslocamento e a folha global da fachada reduz as transições de CSS a 0,01 ms.

Acessibilidade

A área solta é construída sobre o DropZone do React Aria, e o Trigger é um botão comum: quem não arrasta (teclado, leitor de tela) usa o botão e o seletor do sistema.
O DropZone.Input precisa de aria-label, já que fica oculto.
Progresso por DropZone.FileProgress com aria-label próprio (Leitura de pedidos-outubro.csv); anuncie o resultado e as falhas em uma região aria-live.
O botão de remover leva o nome do arquivo (Remover pedidos-outubro.csv).
Estado nunca só em cor: o status vem em texto na linha de meta (pronto, lendo, falhou).

Boas práticas

Faça

Dizer o formato, o tamanho máximo e o que acontece com o arquivo (lido para a prévia, não fica guardado).

Evite

Aceitar qualquer arquivo e só reclamar depois do envio.

Valide o tipo e o tamanho antes de enviar, e no servidor também.
Mostre o motivo da falha e a próxima ação (tentar de novo, escolher outro).
Sempre ofereça o botão: arrastar não é acessível a todo mundo.
Para ações sobre a lista de arquivos, mantenha o foco ao remover um item.

Relacionados

EmptyState para o vazio antes do primeiro envio em telas maiores.
Alert o aviso de erro de leitura do arquivo.
Button a base do botão de tentar de novo.
Toast para confirmar um envio concluído.