FormData en JavaScript se utiliza principalmente para dos propósitos:

• Serializar los datos de los elmeentos de un formulario combinando sus nombres y valores, lo que simplifica el manejo y reduce la necesidad de concatenación manual.
• Permitir la carga asíncrona de archivos, como imágenes o documentos, en el servidor.

Creación de un objeto FormData

Generación de una instancia vacía

Se puede crear un objeto FormData sin parámetros utilizando su constructor. Luego, se emplean métodos como agregar para insertar datos y obtener para recuperarlos.

// Instancia vacía de FormData
const datosFormulario = new FormData();

// Agregar datos con el método agregar
datosFormulario.agregar("nombre", "Pedro");

// Recuperar el valor mediante obtener
console.log(datosFormulario.obtener("nombre")); // Pedro

// Modificar el valor con establecer
datosFormulario.establecer("nombre", "Luis");
console.log(datosFormulario.obtener("nombre")); // Luis

Inicialización desde un formulario HTML

Consideremos un formulario con campos para nombre de anuncio, tipo e imagen. Se puede inicializar FormData pasando el elemento del formulario al constructor.

<form id="formularioPublicidad">
    <p>Nombre del anuncio: <input type="text" name="nombreAnuncio" value="promo1"></p>
    <p>Tipo: <select name="tipoAnuncio">
        <option value="A1">Banner principal</option>
        <option value="A2">Banner secundario</option>
    </select></p>
    <p><input type="button" id="enviarBtn" value="Enviar"></p>
</form>

// Obtener el botón y asignar un evento de clic
const boton = document.getElementById("enviarBtn");
boton.addEventListener("click", function() {
    // Capturar el formulario por su ID
    const formulario = document.getElementById("formularioPublicidad");
    // Inicializar FormData con el formulario
    const datos = new FormData(formulario);
    
    // Recuperar valores específicos
    console.log(datos.obtener("nombreAnuncio")); // promo1
    console.log(datos.obtener("tipoAnuncio")); // A1
});

Métodos de operación

Obtener datos con obtener y obtenerTodos

El método obtener(clave) devuelve el primer valor asociado a una clave, minetras que obtenerTodos(clave) retorna un arreglo con todos los valores si existen múltiples.

const info = new FormData();
info.agregar("edad", "30");
info.agregar("edad", "25");

// Primer valor de la clave "edad"
console.log(info.obtener("edad")); // 30

// Todos los valores de la clave "edad"
console.log(info.obtenerTodos("edad")); // ["30", "25"]

Agregar datos con agregar

El método agregar(clave, valor) añade un par clave-valor al final de la colección. Si la clave ya existe, se agrega un nuevo valer sin sobrescribir los anteriores.

const registro = new FormData();
registro.agregar("ciudad", "Madrid");
registro.agregar("ciudad", "Barcelona");
registro.agregar("ciudad", "Valencia");

console.log(registro.obtener("ciudad")); // Madrid
console.log(registro.obtenerTodos("ciudad")); // ["Madrid", "Barcelona", "Valencia"]

Modificar datos con establecer

El método establecer(clave, valor) establece un valor para una clave. Si la clave no existe, se crea una nueva entrada; si ya existe, reemplaza todos los valores anteriores por el nuevo.

// Caso 1: Clave nueva
const config = new FormData();
config.establecer("tema", "oscuro");
console.log(config.obtener("tema")); // oscuro

// Caso 2: Clave existente
const ajustes = new FormData();
ajustes.agregar("idioma", "español");
ajustes.agregar("idioma", "inglés");
console.log(ajustes.obtenerTodos("idioma")); // ["español", "inglés"]

ajustes.establecer("idioma", "francés");
console.log(ajustes.obtener("idioma")); // francés
console.log(ajustes.obtenerTodos("idioma")); // ["francés"]

Verificar claves con contiene

El método contiene(clave) retorna un booleano indicando si la clave está presente en el FormData.

const datosUsuario = new FormData();
datosUsuario.agregar("correo", "ejemplo@dominio.com");

console.log(datosUsuario.contiene("correo")); // true
console.log(datosUsuario.contiene("telefono")); // false

Eliminar datos con eliminar

El método eliminar(clave) borra todos los valores asociados a la clave especificada.

const historial = new FormData();
historial.agregar("acción", "compra");
console.log(historial.obtener("acción")); // compra

historial.eliminar("acción");
console.log(historial.obtener("acción")); // null

Envío de datos mediante XMLHttpRequest

FormData es ideal para enviar datos de formularios, incluyendo archivos, a un servidor usando XMLHttpRequest.

<form id="formularioEnvio">
    <p>Nombre: <input type="text" name="nombre" value="Ana"></p>
    <p>Archivo: <input type="file" name="documento"></p>
    <p><input type="button" id="enviarDatos" value="Enviar"></p>
</form>

const botonEnvio = document.getElementById("enviarDatos");
botonEnvio.addEventListener("click", function() {
    // Capturar el formulario y crear FormData
    const form = document.getElementById("formularioEnvio");
    const datosEnvio = new FormData(form);
    
    // Configurar la solicitud XMLHttpRequest
    const solicitud = new XMLHttpRequest();
    solicitud.open("POST", "https://ejemplo.com/api/datos");
    solicitud.send(datosEnvio);
    
    // Manejar la respuesta
    solicitud.onload = function() {
        if (solicitud.status === 200) {
            console.log("Datos enviados exitosamente");
        }
    };
});