La API FormData

FormData es un objeto integrado que representa los campos de un formulario y sus valores, adecuado para enviarlos directamente mediante fetch o XMLHttpRequest. Gestiona cargas de archivos, codificación multipart y pares clave-valor arbitrarios sin serialización manual.

Pase un elemento <form> al constructor: const data = new FormData(formElement). El resultado contiene todos los controles de formulario que participan en el envío (inputs con nombre, selects, textareas, casillas marcadas y archivos). Los controles deshabilitados y las casillas sin marcar se excluyen automáticamente.

Pasar FormData como body de fetch establece automáticamente el Content-Type de la solicitud en multipart/form-data (con el boundary correcto). No establezca Content-Type manualmente: fetch necesita generar el boundary por sí mismo.

data.append(key, value) añade una clave (permite duplicados). data.set(key, value) reemplaza cualquier valor existente para esa clave. data.delete(key) elimina todos los valores de una clave. data.has(key) comprueba si está presente.

FormData gestiona los archivos de forma transparente: data.append("avatar", fileInput.files[0]). El servidor recibe una carga multipart con el nombre y el tipo MIME del archivo. Esta es la forma estándar de cargar archivos con fetch en el código moderno.

FormData es iterable: for (const [key, value] of data) { ... }. Use data.entries(), data.keys() y data.values() para realizar iteraciones específicas. Resulta útil para registrar datos, validarlos o construir una copia JSON del formulario.

Para enviarlo como JSON en lugar de multipart: Object.fromEntries(data) produce un objeto simple, pero pierde las claves duplicadas. Para gestionarlas correctamente, recorra las entradas y agrúpelas manualmente. En API de JSON puras, es más sencillo construir el objeto directamente sin pasar por FormData.

Construya un FormData vacío y añada los valores manualmente: const data = new FormData(); data.append("title", title); data.append("file", file);. Resulta útil al enviar datos que no proceden de un formulario (archivos arrastrados, respuestas de API, cargas generadas).

Si existen varios botones de envío, pase el botón que inició el envío como segundo argumento de FormData: new FormData(form, e.submitter). El nombre y el valor de ese botón se incluyen en los datos, algo importante en formularios con varias acciones.

Para la codificación application/x-www-form-urlencoded (la codificación predeterminada de los formularios sin archivos), construya un URLSearchParams a partir de FormData: new URLSearchParams(data). Es más eficiente que multipart para formularios que solo contienen texto.

Establecer explícitamente la cabecera Content-Type de fetch en "multipart/form-data" rompe la carga: el navegador ya no puede añadir el boundary necesario. Omita Content-Type al enviar FormData y deje que fetch lo gestione.

¿Por qué NO debe establecer manualmente Content-Type al enviar FormData con fetch?

FormData representa el contenido de un formulario y se envía correctamente con fetch, incluidas las cargas de archivos mediante multipart/form-data. Constrúyalo a partir de un elemento de formulario, añada, establezca o elimine entradas e itérelo según sea necesario. No establezca Content-Type al enviarlo: fetch genera el boundary automáticamente. Use URLSearchParams para formularios urlencoded que solo contengan texto.