JavaScript Academy · Aula

O objeto FormData

Crie cargas multipart a partir de formulários.

O objeto FormData é uma aula grátis de JavaScript Academy no CoddyKit. Esta é a aula 1 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.

O que é FormData?

FormData é uma API do navegador para criar um conjunto de pares de chave e valor que representam os campos de um formulário e seus valores. É a maneira padrão de empacotar dados, incluindo arquivos, para enviá-los a um servidor.

Ele é codificado como multipart/form-data, que permite o envio de dados binários.

Criando um FormData vazio

Crie um FormData vazio e adicione os campos um por vez com append.

const data = new FormData();
data.append('username', 'ada');
data.append('email', 'ada@example.com');

console.log(data.get('username'));

Criando a partir de um elemento de formulário

Passe um elemento <form> ao construtor, e todas as entradas nomeadas serão capturadas automaticamente. Esse é o uso mais comum.

const form = document.querySelector('#signup');
const data = new FormData(form);

for (const [key, value] of data.entries()) {
  console.log(key, value);
}

append versus set

append adiciona um valor mesmo que a chave já exista, permitindo vários valores por chave. set substitui todos os valores existentes para essa chave.

const data = new FormData();
data.append('tag', 'a');
data.append('tag', 'b');
console.log(data.getAll('tag'));

data.set('tag', 'only');
console.log(data.getAll('tag'));

Lendo valores

get retorna o primeiro valor de uma chave, getAll retorna todos os valores como uma matriz, e has verifica se ela existe.

const data = new FormData();
data.append('color', 'red');
data.append('color', 'blue');

console.log(data.get('color'));
console.log(data.getAll('color'));
console.log(data.has('color'));

Excluindo campos

delete remove todos os valores de uma chave. É útil para remover campos antes do envio.

const data = new FormData();
data.append('keep', '1');
data.append('remove', '2');

data.delete('remove');
console.log(data.has('remove'));
console.log(data.has('keep'));

Percorrendo entradas

FormData pode ser percorrido. Use entries, keys ou values, ou um laço for...of, para percorrer todos os pares.

const data = new FormData();
data.append('a', '1');
data.append('b', '2');

for (const key of data.keys()) {
  console.log('field: ' + key);
}

Anexando arquivos

append pode receber um File ou Blob como valor. Um terceiro argumento opcional define o nome do arquivo enviado ao servidor.

const fileInput = document.querySelector('#avatar');
const data = new FormData();
data.append('avatar', fileInput.files[0], 'profile.png');

console.log(data.get('avatar').name);

Por que usar multipart/form-data

FormData serializa os dados como multipart/form-data, que pode transportar campos de texto e conteúdo de arquivos binários no corpo de uma única requisição. Por isso, esse é o formato preferido para enviar arquivos.

const data = new FormData();
data.append('title', 'Vacation Photo');
data.append('photo', new Blob(['binary'], { type: 'image/png' }), 'pic.png');

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

Convertendo em um objeto

Para formulários simples que contêm apenas texto, Object.fromEntries pode transformar FormData em um objeto simples. Observe que isso mantém apenas um valor por chave repetida.

const form = document.querySelector('#login');
const data = new FormData(form);
const plain = Object.fromEntries(data.entries());

console.log(plain);

Por que FormData é importante

FormData é a ponte entre formulários HTML e requisições de rede. Ele reúne campos e arquivos, aceita chaves repetidas e codifica dados binários com segurança. Em seguida, você lerá o conteúdo de arquivos com FileReader e depois enviará FormData com fetch.

const form = document.querySelector('#contact');
const data = new FormData(form);
data.append('source', 'web');

console.log([...data.keys()]);

Verificação rápida

Qual é a diferença entre append e set em um FormData?

Recapitulação: o objeto FormData

Você aprendeu a empacotar dados de formulários:

new FormData(form) captura automaticamente as entradas nomeadas.
append permite chaves repetidas; set as substitui.
Leia com get, getAll e has; percorra com entries.
Os dados são codificados como multipart/form-data, que aceita arquivos e dados binários.

Perguntas Frequentes

A aula “O objeto FormData” é grátis?

Sim — o texto completo de “O objeto FormData” é 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 “O objeto FormData”?

Crie cargas multipart a partir de formulários. 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 1 de 4.

Quanto tempo leva a aula “O objeto FormData”?

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