La FormData API

FormData è un oggetto integrato che rappresenta i campi di un modulo e i relativi valori, adatto all'invio diretto tramite fetch o XMLHttpRequest. Gestisce il caricamento dei file, la codifica multipart e coppie chiave-valore arbitrarie senza serializzazione manuale.

Passi un elemento <form> al costruttore: const data = new FormData(formElement). Il risultato contiene tutti i controlli del modulo inclusi nell'invio: input con nome, select, textarea, checkbox selezionate e file. I controlli disabilitati e quelli non selezionati vengono esclusi automaticamente.

Passare FormData come body di fetch imposta automaticamente il Content-Type della richiesta su multipart/form-data, con il boundary corretto. Non imposti Content-Type manualmente: fetch deve generare il boundary autonomamente.

data.append(key, value) aggiunge una chiave, consentendo duplicati. data.set(key, value) sostituisce qualsiasi valore esistente per la chiave. data.delete(key) rimuove tutti i valori di una chiave. data.has(key) verifica la presenza.

FormData gestisce i file in modo trasparente: data.append("avatar", fileInput.files[0]). Il server riceve un caricamento multipart con il nome e il tipo MIME del file. Questo è il modo standard per caricare file con fetch nel codice moderno.

FormData è iterabile: for (const [key, value] of data) { ... }. Usi data.entries(), data.keys() e data.values() per iterazioni specifiche. È utile per registrare dati, eseguire validazioni o costruire una copia JSON del modulo.

Per inviare JSON anziché multipart: Object.fromEntries(data) produce un oggetto semplice, ma perde le chiavi duplicate. Per gestire correttamente i duplicati, iteri sulle entries e le raggruppi manualmente. Per le API esclusivamente JSON, è più semplice costruire direttamente l'oggetto senza passare da FormData.

Costruisca un FormData vuoto e aggiunga manualmente i valori: const data = new FormData(); data.append("title", title); data.append("file", file);. È utile quando si inviano dati che non provengono da un modulo, come file trascinati, risposte API o payload generati.

Se sono presenti più pulsanti di invio, passi il submitter come secondo argomento a FormData: new FormData(form, e.submitter). Il nome e il valore del submitter vengono inclusi nei dati, un aspetto importante per i moduli con più azioni.

Per la codifica application/x-www-form-urlencoded, ovvero la codifica predefinita dei moduli senza file, costruisca un URLSearchParams da FormData: new URLSearchParams(data). È meno oneroso di multipart per i moduli costituiti solo da testo.

Impostare esplicitamente l'header Content-Type di fetch su "multipart/form-data" interrompe il caricamento: il browser non può più aggiungere il boundary richiesto. Ometta Content-Type quando invia FormData e lasci che sia fetch a gestirlo.

Perché NON deve impostare manualmente Content-Type quando invia FormData con fetch?

FormData rappresenta il contenuto di un modulo e lo invia correttamente con fetch, inclusi i caricamenti di file tramite multipart/form-data. Lo costruisca da un elemento modulo, aggiunga, sostituisca o elimini le entries e le iteri secondo necessità. Non imposti Content-Type durante l'invio: fetch genera automaticamente il boundary. Usi URLSearchParams per i moduli urlencoded composti solo da testo.