Pular para o conteúdo
Formulário

FileUpload

/componentes/file-upload.mdmarkdown cru, para quem lê com agent em vez de olho

Padrão

Com a lista de enviados

  • planilha-de-precos.csv47,1 KB
  • contrato-assinado.pdf1,2 MB
  • foto-da-vitrine.jpg3,3 MB

Desabilitada

Importar
import { FileUpload } from '@rivocode/ui'

Quando usar

A área de anexar: clique abre o seletor, arrastar acende, soltar valida.

A peça não conhece rede, de propósito, como o DataTable não conhece React Query. Subir o arquivo (fetch, progresso real, nova tentativa) é do app, que sabe o endpoint e a autenticação. A peça valida accept e maxSize na entrada, entrega os aceitos em onSelect e os recusados em onReject, cada recusa com o motivo pronto para um toast: "maior que 5 MB", "tipo não aceito". Sem multiple, soltar vários entrega o primeiro, e os outros chegam em onReject com "só um arquivo por vez", em vez de sumirem calados.

A lista é apresentação do estado que o app informar: progress de 0 a 100 vira barra anunciada como progressbar; error vence o progresso, mostra o texto e oferece "Tentar de novo"; sem os dois, o arquivo está pronto. O tamanho sai formatado pela peça (48,2 KB, 1,2 MB), nunca digitado.

A área é um <button> de verdade, então teclado e leitor de tela funcionam sem esforço; o <input type="file"> escondido carrega accept e multiple, e o diálogo do sistema já filtra os tipos.

Quem informa o formato e o limite no hint evita a recusa: a pessoa lê "PNG ou JPG, até 5 MB" antes de escolher errado.

No formulário

A peça entra num Form como os outros controles de valor: value com os arquivos e onValueChange com a lista nova, pelo forValue do @rivocode/ui/form. Com multiple, cada escolha soma os aceitos aos de antes; sem ele, o aceito agora troca o anterior. O ref chega ao botão da área, que é o que recebe o foco quando o envio aponta o erro, e o erro do schema deixa a área com a borda de erro e aria-invalid.

const schema = z.object({
  contratos: z.array(z.instanceof(File)).min(1, 'Anexe o PDF do contrato'),
})

<FormField name="contratos" label="Contratos">
  {(field) => (
    <FileUpload {...forValue(field)} label="Arraste o PDF do contrato" accept="application/pdf" multiple />
  )}
</FormField>

Fora do Form, a peça lê o Field em volta: o name dele vai para o <input type="file"> escondido, e o disabled e o invalid dele valem na área quando as props faltam. Com name e value, o input escondido carrega os arquivos do valor, e um <form> comum os envia no FormData.

Dentro do Field (e do FormField, que é um Field), a área se liga ao campo como os outros controles: o botão recebe o id para onde o FieldLabel aponta, o nome dele começa pelo rótulo do campo e segue com o label da área (“Contratos, Arraste o PDF do contrato”), e o FieldDescription, o FieldError e o hint entram no aria-describedby. Clicar no rótulo abre o seletor.

O erro de envio de cada FileUploadItem sai com role="alert": quem usa leitor de tela ouve que o arquivo falhou, sem ter que voltar à lista para descobrir.

As partes

FileUploadList é a lista do que já entrou, e FileUploadItem é cada arquivo nela, com nome, tamanho, progress e error. A barra de cada arquivo anda até o valor novo pela largura, no tempo --rc-duration-base, em vez de pular de um número para o outro a cada aviso do envio. Subir é do app: a peça valida na entrada e mostra o que o app disser depois. Quem controla o envio é quem sabe quando ele terminou.

Movimento

Cada FileUploadItem entra esmaecendo e subindo 4px (animate-enter, --rc-duration-base), então o arquivo recém-escolhido é visto chegando à lista. A barra de envio anda pela largura.

Quando não usar

Para assinatura na tela (aceite, recebimento, vistoria), use SignaturePad: pedir que a pessoa assine num papel, fotografe e anexe é o caminho mais longo para o mesmo traço. E a foto que a pessoa precisa ampliar depois de anexada se vê no ImageViewer; a área daqui só recebe e lista.

Escolher entre arquivos que já moram no sistema não é anexar: é Combobox, ou TransferList para montar um conjunto. O seletor do sistema operacional não sabe o que está no servidor.

No React Native

Traduz, no caminho próprio @rivocode/ui-native/file-upload: o expo-document-picker é peer opcional e módulo nativo (npx expo install expo-document-picker), e tem caminho separado do Clipboard pela mesma conta: a regra da casa é um subcaminho por peer, e não um por assunto. O que não muda é o principal: a peça continua não conhecendo rede. Ela valida accept e maxSize na entrada, entrega os aceitos em onSelect e os recusados em onReject, cada recusa com o motivo pronto para um aviso.

A área de soltar vira um botão, e isso é a peça inteira mudando de forma. No celular não há arrastar: nada pode ser solto em lugar nenhum, e o retângulo tracejado de 96px do web é, letra por letra, o idioma de "solte aqui": desenhá-lo numa tela de toque promete um gesto que o aparelho não tem. Tirado o soltar, o que sobra daquela caixa é um botão com muito espaço vazio em volta: o espaço era o alvo de soltar, e não a affordance. Então sobra o botão, numa altura de controle. E a altura que ele devolve é da lista, que é onde o arquivo aparece, sobe, falha e é removido. O hint continua existindo, e entra no nome falado do botão pelo mesmo motivo que no web ele mora dentro do <button>: quem ouve a tela precisa saber "XML ou PDF, até 5 MB" antes de abrir o seletor, e não depois de ser recusado.

O accept fala MIME. O seletor do Expo filtra por tipo (text/xml, image/*), e não por extensão: um .xml mandado para lá não casaria nada e abriria o diálogo vazio. Então a extensão com ponto continua valendo (na validação de volta, contra o nome do arquivo), mas não vai para o sistema. E o que volta não é um File: é um PickedFile (uri, name, size?, mimeType?), com o uri local que o app usa para subir. O size pode faltar, porque nem todo provedor de arquivo do Android o informa, e por isso maxSize só recusa o que conseguiu medir. Fechar o seletor devolve canceled e nenhum callback dispara, como fechar a janela do seletor do web.

FileUploadList e FileUploadItem atravessam com o mesmo contrato (progress de 0 a 100 vira barra anunciada, error vence o progresso e oferece "Tentar de novo"), com duas diferenças de plataforma: o corte do nome é numberOfLines, que lá é prop e não classe, e o tamanho sai formatado sem Intl ("47,1 KB", com a vírgula escrita à mão). E o size do item é opcional, como o do PickedFile: sem ele a linha não mostra tamanho, em vez de inventar "0 B". O "Tentar de novo" da linha tem alvo de 44pt.

No formulário entra pelo forFiles, que é o forValue sem o label: value com os PickedFile e onValueChange com a lista nova, somada com multiple. O label é o texto do botão, e é obrigatório; o rótulo do campo chega pelo Field, e o leitor de tela ouve os dois, o do campo antes. Com o forValue, o rótulo do campo tomaria o lugar do texto do botão quando o label vem antes do espalhado. O erro do Field acende a borda de erro e vira a dica que o leitor de tela ouve, e fechar o seletor conta como sair do campo (onBlur). Não há name: no celular não existe <form> para levá-lo.

No iOS e no Android. A escolha do arquivo abre o seletor do sistema: o app Arquivos no iOS e o seletor de documentos no Android. A lista, o progresso e o erro depois da escolha são os da peça.

API

PropTipo
labelobrigatória0.4.0

A frase da área: "Arraste o contrato, ou clique para escolher".

ReactNode
accept0.4.0

Como no seletor nativo: `.xml,application/pdf`, `image/*`.

string
disabled0.4.0boolean
hint0.4.0

A letra miúda: formatos e limite, para a pessoa não descobrir na recusa.

ReactNode
invalid

Marca a área como inválida, com a borda de erro e o `aria-invalid`.

boolean
labels

Os motivos de recusa, para trocar o idioma: `invalidType` e o do tipo fora do `accept`, e `tooLarge` recebe o limite ja escrito ("5 MB") e devolve o do arquivo grande demais, e `tooMany` e o do arquivo que sobra quando `multiple` esta desligado e chegam varios.

Partial<FileUploadLabels>
maxSize0.4.0

Em bytes.

number
multiple0.4.0

Sem ele, entra o primeiro arquivo e os outros viram recusa, com o motivo `tooMany`.

boolean
name

O nome do campo no formulário, no `<input type="file">` escondido.

string
onReject0.4.0

Os que não passaram, cada um com o motivo legível.

((rejections: Rejection[]) => void)
onSelect0.4.0

Os que passaram na validação.

((files: File[]) => void)
onValueChange

Chamado com o valor novo depois de cada escolha: com `multiple`, os de antes somados aos aceitos agora; sem ele, só o aceito agora.

((files: File[]) => void)
ref

Chega ao botão da área, que é o que recebe o foco quando o formulário aponta o erro.

Ref<HTMLButtonElement>
value

Os arquivos do campo, quando quem usa guarda o estado: é o que o `forValue` do `@rivocode/ui/form` entrega.

File[]

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.