JavaScript Academy · Aula

Enviando arquivos com Fetch

Envie arquivos para um servidor com FormData.

Aula 4 de 413 etapas

Enviando arquivos com Fetch é uma aula grátis de JavaScript 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 JavaScript Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de JavaScript Academy inclui 4 aulas no total.

Enviando arquivos com requisições

Para enviar arquivos a um servidor, você faz uma requisição POST com um corpo FormData usando fetch. O navegador cuida da codificação multipart/form-data para você, incluindo o conteúdo dos arquivos.

Criando o FormData

Obtenha o arquivo de uma entrada e anexe-o, junto com quaisquer outros campos, a um objeto FormData.

const file = document.querySelector('#picker').files[0];
const data = new FormData();
data.append('avatar', file);
data.append('userId', '42');

console.log(data.has('avatar'));

A requisição POST básica

Passe o FormData como o body de uma requisição POST feita com fetch. A resposta é uma Promise que você pode aguardar.

async function upload(data) {
  const response = await fetch('/api/upload', {
    method: 'POST',
    body: data
  });
  console.log(response.status);
}

Não defina Content-Type

Um erro comum é definir Content-Type manualmente. Deixe o navegador defini-lo, pois ele precisa incluir a cadeia de caracteres boundary do multipart. Defini-lo manualmente interrompe o envio.

const response = await fetch('/api/upload', {
  method: 'POST',
  body: formData
});

console.log('browser added the boundary automatically');

Lendo a resposta

Verifique response.ok e analise o corpo, geralmente como JSON, depois de um envio bem-sucedido.

async function upload(data) {
  const response = await fetch('/api/upload', { method: 'POST', body: data });
  if (!response.ok) {
    throw new Error('upload failed: ' + response.status);
  }
  const result = await response.json();
  console.log(result);
}

Lidando com erros

Coloque a chamada em um bloco try/catch. Observe que fetch só rejeita a Promise em falhas de rede; portanto, você precisa verificar response.ok para detectar status de erro HTTP.

async function upload(data) {
  try {
    const res = await fetch('/api/upload', { method: 'POST', body: data });
    if (!res.ok) throw new Error('HTTP ' + res.status);
    console.log('uploaded');
  } catch (err) {
    console.log('error:', err.message);
  }
}

Enviando vários arquivos

Anexe vários arquivos usando a mesma chave com append ou percorra uma lista de arquivos para adicioná-los todos.

const files = document.querySelector('#picker').files;
const data = new FormData();
for (const file of files) {
  data.append('photos', file);
}

console.log(data.getAll('photos').length + ' files queued');

Adicionando cabeçalhos, como autenticação

Você pode adicionar cabeçalhos, como Authorization, mas não Content-Type. O corpo continua sendo o FormData.

const response = await fetch('/api/upload', {
  method: 'POST',
  headers: { Authorization: 'Bearer token123' },
  body: formData
});

console.log(response.status);

Enviando um objeto binário gerado

Você pode enviar dados criados no navegador, não apenas arquivos escolhidos. Anexe um objeto binário com um nome de arquivo para enviar um documento gerado.

const blob = new Blob([JSON.stringify({ ok: true })], {
  type: 'application/json'
});
const data = new FormData();
data.append('report', blob, 'report.json');

await fetch('/api/upload', { method: 'POST', body: data });
console.log('generated file sent');

Cancelando um envio

Use um AbortController para cancelar um envio lento, por exemplo, quando o usuário sair da página.

const controller = new AbortController();
fetch('/api/upload', {
  method: 'POST',
  body: formData,
  signal: controller.signal
}).catch(e => console.log(e.name));

controller.abort();

Por que isso é importante

Combinar FormData com fetch é a maneira moderna e padrão de enviar arquivos: anexe campos e arquivos, faça o POST do FormData e deixe o navegador codificar o multipart com o delimitador correto. Evite definir Content-Type, sempre verifique response.ok e libere os recursos usados.

async function submitForm(formEl) {
  const data = new FormData(formEl);
  const res = await fetch('/submit', { method: 'POST', body: data });
  console.log('status', res.status);
}

Verificação rápida

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

Responda na aula interativa

Recapitulação: enviando arquivos com requisições

Você aprendeu a enviar arquivos a um servidor:

Anexe arquivos e campos a um FormData e passe-o como body de fetch.
Nunca defina Content-Type manualmente; o navegador adiciona o delimitador do multipart.
Verifique response.ok, pois fetch só rejeita a Promise em erros de rede.
Você pode enviar vários arquivos e objetos binários gerados, além de cancelar envios com AbortController.

Grátis para começar

Aprenda JavaScript com um tutor de IA — grátis

Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.

Cursos: 59
Aulas: 200

Começar a aprender grátis Ver o curso completo

Perguntas Frequentes

A aula “Enviando arquivos com Fetch” é grátis?

Sim — o texto completo de “Enviando arquivos com Fetch” é 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 JavaScript Academy, atualize para CoddyKit PRO. O curso de JavaScript Academy inclui 4 aulas no total.

O que vou aprender em “Enviando arquivos com Fetch”?

Envie arquivos para um servidor com FormData. Você pratica JavaScript 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 JavaScript Academy?

Nenhuma experiência prévia é necessária. JavaScript 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 “Enviando arquivos com Fetch”?

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 JavaScript Academy?

Sim. Cada aula de JavaScript 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

← Voltar para JavaScript Academy