0Pricing
React Academy · Aula

Carregando arquivos para uma API de back-end

Use FormData e fetch para enviar arquivos com POST e acompanhar o progresso do carregamento.

Carregando arquivos para uma API de back-end é uma aula grátis de React Academy no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de React Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de React Academy inclui 4 aulas no total.

Boas-vindas

Nesta lição, você usará a API FormData e fetch para fazer POST dos arquivos em um backend, acompanhar o progresso do carregamento com XMLHttpRequest e exibir o estado do carregamento em React.

API FormData

FormData é uma API do navegador que cria corpos de requisição multipart/form-data — o formato que os servidores esperam para carregamentos de arquivos. Anexe o arquivo e todos os campos de metadados a um objeto FormData.
const formData = new FormData();
formData.append('file', selectedFile);
formData.append('description', 'Profile photo');

Carregando com fetch

Passe o objeto FormData como corpo de fetch. NÃO defina Content-Type manualmente — o navegador define automaticamente o limite multipart correto.
const response = await fetch('/api/upload', {
  method: 'POST',
  body: formData,
  // Do not set Content-Type header here!
});

Gerenciamento do estado do carregamento

Acompanhe o estado do carregamento com três variáveis de estado: `uploading` (booleano), `progress` (0–100) e `error` (texto ou nulo). Exiba indicadores de carregamento, barras de progresso e mensagens de erro com base nesses valores.
const [uploading, setUploading] = useState(false);
const [progress, setProgress] = useState(0);
const [error, setError] = useState(null);

Progresso do carregamento com XMLHttpRequest

A API fetch não oferece suporte a eventos de progresso do carregamento. Use o evento `upload.onprogress` de XMLHttpRequest para obter atualizações percentuais.
const xhr = new XMLHttpRequest();
xhr.upload.onprogress = (e) => {
  if (e.lengthComputable) {
    setProgress(Math.round((e.loaded / e.total) * 100));
  }
};
xhr.open('POST', '/api/upload');
xhr.send(formData);

Encapsulando XHR em uma Promise

Encapsule a chamada XMLHttpRequest em uma Promise para poder aguardá-la e usar o tratamento de erros com async/await.
function uploadFile(file) {
  return new Promise((resolve, reject) => {
    const xhr = new XMLHttpRequest();
    xhr.onload = () => resolve(xhr.response);
    xhr.onerror = () => reject(new Error('Upload failed'));
    xhr.upload.onprogress = (e) => setProgress(Math.round(e.loaded / e.total * 100));
    xhr.open('POST', '/api/upload');
    xhr.send(new FormData().set && (() => { const f = new FormData(); f.append('file', file); xhr.send(f); })());
  });
}

Tratando a resposta do servidor

Analise a resposta JSON do servidor após um carregamento bem-sucedido. Atualize o estado da interface com a URL ou o ID retornado.
const res = await fetch('/api/upload', { method: 'POST', body: fd });
if (!res.ok) throw new Error('Upload failed');
const { url } = await res.json();
setUploadedUrl(url);

Tratamento de erros

Sempre capture erros de rede e do servidor. Exiba uma mensagem de erro clara para o usuário e permita tentar novamente. Redefina o progresso e o estado uploading no bloco catch.
try {
  setUploading(true);
  await uploadToServer(file);
} catch (err) {
  setError(err.message);
} finally {
  setUploading(false);
}

Cancelando um carregamento

Use um AbortController com fetch para cancelar um carregamento em andamento. Armazene o controlador em uma referência para poder chamar abort() a partir de um botão de cancelamento.
const abortRef = useRef();

const start = async () => {
  abortRef.current = new AbortController();
  await fetch('/api/upload', { body: fd, signal: abortRef.current.signal });
};
const cancel = () => abortRef.current?.abort();

Carregamento de vários arquivos

Carregue vários arquivos em paralelo usando Promise.all ou sequencialmente com um laço for-of. Acompanhe o progresso individual de cada arquivo com um objeto indexado pelo nome do arquivo.

Verificação rápida

Por que você NÃO deve definir manualmente o cabeçalho Content-Type ao usar fetch com FormData?

Recapitulação

Use FormData para criar os dados de carregamento. Use fetch sem Content-Type para que o limite seja definido automaticamente. Use upload.onprogress de XMLHttpRequest para acompanhar o progresso. Trate os erros de forma adequada e ofereça cancelamento com AbortController.

Curso concluído

Parabéns! Você concluiu **Componentes não controlados e carregamentos de arquivos**. Agora você sabe lidar com campos de entrada não controlados, seleção de arquivos, arrastar e soltar e carregamentos multipart com acompanhamento do progresso.

Perguntas Frequentes

A aula “Carregando arquivos para uma API de back-end” é grátis?

Sim — o texto completo de “Carregando arquivos para uma API de back-end” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de React Academy, atualize para CoddyKit PRO. O curso de React Academy inclui 4 aulas no total.

O que vou aprender em “Carregando arquivos para uma API de back-end”?

Use FormData e fetch para enviar arquivos com POST e acompanhar o progresso do carregamento. Você pratica React Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar React Academy?

Nenhuma experiência prévia é necessária. React Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.

Quanto tempo leva a aula “Carregando arquivos para uma API de back-end”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de React Academy?

Sim. Cada aula de React Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Entradas não controladas com useRef
  2. Entrada de arquivo e leitura de dados de arquivos
  3. Interface de envio de arquivos por arrastar e soltar
  4. Carregando arquivos para uma API de back-end
← Voltar para React Academy