Cómo agregar y actualizar parámetros de cadena de consulta usando URLSearchParams

Como desarrollador frontend, debe saber cómo manipular los parámetros de la cadena de consulta en el lado del cliente. Hoy veremos el URLSearchParams interfaz que se puede usar para agregar, actualizar o eliminar parámetros de cadena de consulta en JavaScript.

Iniciando URLSearchParams

Para crear una nueva instancia de URLSearchParams , simplemente pase la parte de la cadena de consulta de la URL (con o sin el ? inicial ) a su constructor.

Si está trabajando en un navegador, puede acceder a la parte de la cadena de consulta de la URL actual con window.location.search :

const params = new URLSearchParams(window.location.search);

Alternativamente, puede crear un nuevo objeto de URL y recuperar todos los parámetros de consulta como se muestra a continuación:

// current URL
const url = "http://example.com?size=M&color=blue&price=29&sort=desc";

// create a URL object
const urlObj = new URL(url);

// initialize URLSearchParams
const params = new URLSearchParams(urlObj.search);

El URLSearchParams constructor también acepta un objeto JavaScript y automáticamente lo convierte en una cadena de consulta:

const obj = {
    size: 'M',
    color: 'blue',
    price: 29,
    sort: 'desc'
};

// initialize URLSearchParams from object
const params = new URLSearchParams(obj);

Acceder a los parámetros

Para obtener el valor de un parámetro de consulta, puede usar el get() método. Si el parámetro no existe o está vacío, obtendrá un null valor:

params.get('price')   // 29
params.get('page')  // null

Para verificar si un determinado parámetro de consulta está presente, puede usar el has() método:

params.has('size')  // true
params.has('user')   // false

Siempre debes usar el has() método para comprobar la existencia del parámetro antes de acceder a su valor. Evita un falso positivo cuando el parámetro está presente en la URL pero no tiene valor, es decir, size=&rows=12 .

Obtener múltiples parámetros

A veces, una URL puede contener más de un valor de un solo parámetro. Miremos la siguiente URL:

http://example.com?size=M&size=XL&color=blue

La URL anterior es 100% válida. Si analiza la URL anterior con URLSearchParams , creará una matriz de valores para el size parámetro.

Sin embargo, si usa el get() método para acceder a size , solo obtendrá el primer valor M . Para obtener todos los valores de un parámetro de cadena de consulta, debe usar getAll() método:

params.getAll('size') // [ 'M', 'XL' ]

Modificación de parámetros

El set() El método se puede utilizar para añadir un nuevo parámetro de consulta o actualización el valor del parámetro existente:

// add new param
params.set('page', 2)

// update existing param
param.set('price', 9)

Tenga en cuenta que si el parámetro contiene más de valores, el set() el método los eliminará a todos y establecerá el nuevo valor:

// URL: http://example.com?size=M&size=XL&color=blue&price=29&sort=desc

// change `size` to `L`
params.set('size', 'L');

console.log([...params.keys()]); // [ 'size', 'color', 'price', 'sort' ]
console.log([...params.values()]); // [ 'L', 'blue', '29', 'desc' ]

Para evitar anular los valores de los parámetros existentes, debe usar el append() método en su lugar. Como su nombre indica, append() agregará un nuevo parámetro si aún no existe. De lo contrario, le agregará un nuevo valor.

Aquí hay un ejemplo:

// URL: http://example.com?size=M&size=XL&color=blue&price=29&sort=desc

// append a new color
params.append('color', 'pink');

console.log([...params.entries()]);

// [ [ 'size', 'M' ],
//   [ 'size', 'XL' ],
//   [ 'color', 'blue' ],
//   [ 'price', '29' ],
//   [ 'sort', 'desc' ],
//   [ 'color', 'pink' ] ]

Para eliminar un parámetro de cadena de consulta de la URL, URLSearchParams proporciona el delete() método:

// URL: http://example.com?size=M&size=XL&color=blue&price=29&sort=desc

// remove size
params.delete('size');

console.log([...params.entries()]);

// [ [ 'color', 'blue' ], [ 'price', '29' ], [ 'sort', 'desc' ] ]

Como puede ver arriba, el delete() elimina todos los valores de size parámetro.

Iterando a través de Parámetros

Hay varias formas de iterar sobre todos los parámetros incluidos en el URLSearchParams objeto. La primera forma es usar el bucle for...of:

for (const p of params) {
    console.log(p);
}

// [ 'size', 'M' ]
// [ 'size', 'XL' ]
// [ 'color', 'blue' ]
// [ 'price', '29' ]
// [ 'sort', 'desc' ]

URLSearchParams también es compatible con el bucle forEach() que se puede usar para recorrer en iteración todos los valores contenidos en el objeto con una función de devolución de llamada:

params.forEach((value, key) => {
    console.log(`${key} => ${value}`);
});

// size => M
// size => XL
// color => blue
// price => 29
// sort => desc

También puedes usar el key() , values() y entries() métodos para obtener un iterador de todas las claves, valores o pares clave-valor disponibles en URLSearchParams .

Obtención de cadena de consulta

Una vez que haya terminado con las modificaciones, puede obtener todos los parámetros como una cadena de consulta utilizando el toString() método:

// URL: http://example.com?size=M&size=XL&color=blue&price=29&sort=desc

// remove size
params.delete('size');

// add page
params.set('page', 1);

console.log(params.toString());

// color=blue&price=29&sort=desc&page=1

Observe el ? que falta delante de la cadena de consulta. El toString() no lo agrega. Necesitas usar manualmente ? al actualizar la URL con la nueva cadena de consulta.

Compatibilidad del navegador

Al momento de escribir, el URLSearchParams El objeto es compatible con todos los principales navegadores excepto IE y Opera Mini. Sin embargo, puede usar un polyfill para asegurarse de que su aplicación continúe funcionando incluso en navegadores antiguos.