FileUpload
Padrão
Com a lista de enviados
- planilha-de-precos.csv47,1 KB
- contrato-assinado.pdf1,2 MB
- foto-da-vitrine.jpg3,3 MB
A conexão caiu.
Desabilitada
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
| Prop | Tipo |
|---|---|
labelobrigatória0.4.0A frase da área: "Arraste o contrato, ou clique para escolher". | ReactNode |
accept0.4.0Como no seletor nativo: `.xml,application/pdf`, `image/*`. | string |
disabled0.4.0 | boolean |
hint0.4.0A letra miúda: formatos e limite, para a pessoa não descobrir na recusa. | ReactNode |
invalidMarca a área como inválida, com a borda de erro e o `aria-invalid`. | boolean |
labelsOs 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.0Em bytes. | number |
multiple0.4.0Sem ele, entra o primeiro arquivo e os outros viram recusa, com o motivo `tooMany`. | boolean |
nameO nome do campo no formulário, no `<input type="file">` escondido. | string |
onReject0.4.0Os que não passaram, cada um com o motivo legível. | ((rejections: Rejection[]) => void) |
onSelect0.4.0Os que passaram na validação. | ((files: File[]) => void) |
onValueChangeChamado 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) |
refChega ao botão da área, que é o que recebe o foco quando o formulário aponta o erro. | Ref<HTMLButtonElement> |
valueOs 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.