Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

FormData — criar e inspecionar dados de formulário

FormData armazena pares nome-valor ordenados, incluindo nomes repetidos. Aprende a diferença entre append() e set(), a iterar com entries() e a enviar os dados através de fetch().

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

const data = new FormData();
data.append(name, value);
data.set(name, value);
data.set(name, blob, filename);
for (const [name, value] of data.entries()) { /* ... */ }

FormData é uma interface da Web API, não faz parte do próprio ECMAScript. Armazena uma lista ordenada de pares nome-valor; os nomes podem repetir-se. Os valores são cadeias de caracteres ou objetos File. Podes fornecer um Blob, que é armazenado como ficheiro. Aos restantes valores aplicam-se as regras de conversão em cadeias de caracteres do Web IDL. Passar um valor do tipo Symbol a append() ou set() lança uma exceção TypeError durante essa conversão; não é armazenada nenhuma cadeia de caracteres.

append(name, value) acrescenta uma entrada, mantendo as entradas anteriores com o mesmo nome. FormData.set, chamado como data.set(name, value), substitui a primeira entrada correspondente e remove as restantes entradas com esse nome. Se o nome não existir, acrescenta uma entrada no final. Para um Blob, podes fornecer um terceiro argumento, filename.

FormData.entries, chamado como data.entries(), devolve um iterador de pares [name, value] pela ordem das entradas. No exemplo, set("tag", "api") deixa uma única entrada tag na posição da primeira entrada, pelo que aparece antes de name. Não é um objeto simples: ao convertê-lo num objeto, não serão preservados vários valores com o mesmo nome.

Ao enviar com fetch(url, { method: "POST", body: data }), não definas manualmente o cabeçalho Content-Type: o browser cria multipart/form-data com um parâmetro boundary correspondente. O exemplo não envia qualquer pedido. Verifica a disponibilidade da API no browser de destino; a presença de Node 24 num repositório não comprova o suporte nos browsers.

Exemplos

const data = new FormData();
data.append("tag", "javascript");
data.append("tag", "web");
data.set("name", "Ada");
data.set("tag", "api");

for (const [name, value] of data.entries()) {
  console.log(`${name}=${value}`);
}

Resultado

tag=api
name=Ada

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes