A API FormData

FormData é um objeto nativo que representa campos de formulário e seus valores, adequado para envio direto por meio de fetch ou XMLHttpRequest. Ele trata envios de arquivos, codificação multipart e pares arbitrários de chave e valor sem serialização manual.

Passe um elemento <form> ao construtor: const data = new FormData(formElement). O resultado contém cada controle de formulário válido (campos de entrada nomeados, listas de seleção, áreas de texto, caixas de seleção marcadas e arquivos). Controles desativados e desmarcados são excluídos automaticamente.

Passar FormData como corpo de fetch define automaticamente o Content-Type da solicitação como multipart/form-data (com o limite correto). Não defina Content-Type manualmente — fetch precisa gerar o limite por conta própria.

data.append(key, value) adiciona uma chave (permitindo duplicatas). data.set(key, value) substitui qualquer valor existente da chave. data.delete(key) remove todos os valores de uma chave. data.has(key) verifica a presença.

FormData trata arquivos de forma transparente: data.append("avatar", fileInput.files[0]). O servidor recebe um envio multipart com o nome e o tipo MIME do arquivo. Esta é a forma padrão de enviar arquivos com fetch em código moderno.

FormData é iterável: for (const [key, value] of data) { ... }. Use data.entries(), data.keys(), data.values() para iterações específicas. Isso é útil para fazer registros, validar ou construir uma cópia JSON do formulário.

Para enviar como JSON em vez de multipart: Object.fromEntries(data) produz um objeto simples — mas perde chaves duplicadas. Para tratar duplicatas corretamente, percorra as entradas e agrupe-as manualmente. Para interfaces de programação puramente JSON, é mais simples construir o objeto diretamente sem passar por FormData.

Construa um FormData vazio e adicione valores manualmente: const data = new FormData(); data.append("title", title); data.append("file", file);. Isso é útil ao enviar dados que não vieram de um formulário (arquivos arrastados, respostas de interfaces de programação e cargas úteis geradas).

Se houver vários botões de envio, passe o botão que acionou o envio como segundo argumento de FormData: new FormData(form, e.submitter). O nome e o valor desse botão são incluídos nos dados — algo importante para formulários com várias ações.

Para a codificação application/x-www-form-urlencoded (a codificação padrão de formulários sem arquivos), construa um URLSearchParams a partir de FormData: new URLSearchParams(data). É mais econômico do que multipart para formulários somente de texto.

Definir explicitamente o cabeçalho Content-Type da API fetch como "multipart/form-data" interrompe o envio — o navegador deixa de conseguir adicionar o limite necessário. Omita Content-Type ao enviar FormData e deixe fetch cuidar disso.

Por que você deve NOT definir Content-Type manualmente ao enviar FormData com fetch?

FormData representa o conteúdo de formulários e é enviado corretamente com fetch — incluindo envios de arquivos por meio de multipart/form-data. Construa-o a partir de um elemento de formulário, adicione, defina ou exclua entradas e percorra-as conforme necessário. Não defina Content-Type ao enviar — fetch gera o limite automaticamente. Use URLSearchParams para formulários codificados na URL somente com texto.