URLSearchParams

Время чтения: меньше 5 мин

Кратко

Секция статьи "Кратко"

URLSearchParams — это класс, предоставляющий удобное API для формирования строки поисковых параметров, которую потом можно использовать для формирования полного адреса. Все параметры в строке будут закодированы для безопасной вставки в адрес. Также этот класс можно встретить как часть класса URL.

Пример

Секция статьи "Пример"

Создаём экземпляр класса параметров поиска:

        
          
          const params = new URLSearchParams({ count: "10" });
          const params = new URLSearchParams({ count: "10" });

        
        
          
        
      

Далее мы можем добавлять или удалять параметры:

        
          
          params.append("size", "lg"); // добавлениеconsole.log(params.toString()); // "count=10&size=lg"params.delete("count"); // удалениеconsole.log(params.toString()); // "size=lg"
          params.append("size", "lg"); // добавление
console.log(params.toString()); // "count=10&size=lg"
params.delete("count"); // удаление
console.log(params.toString()); // "size=lg"

        
        
          
        
      

Повторное добавление параметра с тем же именем добавит ещё одно значение с таким же именем, а получение всех возможных значений вернёт все добавленные значения:

        
          
          params.append("size", "xl");params.getAll("size"); // ['lg', 'xl']
          params.append("size", "xl");
params.getAll("size"); // ['lg', 'xl']

        
        
          
        
      

Получение параметров в виде строки:

        
          
          const paramsString = params.toString(); // 'count=10&size=lg&size=xl'const url = `/catalog/?${paramsSting}`;
          const paramsString = params.toString(); // 'count=10&size=lg&size=xl'
const url = `/catalog/?${paramsSting}`;

        
        
          
        
      

Как это понять

Секция статьи "Как это понять"

Когда нужно сформировать URL, включающий в себя строку поиска, то удобнее всего использовать URLSearchParams. Раньше для той же операции нужно было использовать цикл, в котором строка собиралась вручную, а также делать её безопасной для вставки в адрес с помощью encodeURLComponent. Сейчас же можно использовать специальный класс и управлять им с помощью предоставляемого API.

Как пишется

Секция статьи "Как пишется"

Создание экземпляра класса

Секция статьи "Создание экземпляра класса"

При создании URLSearchParams мы можем передать аргумент в виде объекта, состоящего из полей со строками/цифрами или поисковую строку из адреса страницы. Это создаст новый экземпляр с уже добавленными в него параметрами

        
          
          const emptyParams = new URLSearchParams();const paramsFromUrl = new URLSearchParams(window.location.search);const params = new URLSearchParams({ minPrice: "1000", maxPrice: "2000" });console.log(emptyParams.toString()); // ''console.log(params.toString()); // 'minPrice=1000&maxPrice=2000'
          const emptyParams = new URLSearchParams();
const paramsFromUrl = new URLSearchParams(window.location.search);
const params = new URLSearchParams({ minPrice: "1000", maxPrice: "2000" });

console.log(emptyParams.toString()); // ''
console.log(params.toString()); // 'minPrice=1000&maxPrice=2000'

        
        
          
        
      

Добавление

Секция статьи "Добавление"

Добавление нового параметра в поиск производится с помощью метода append("ключ", "значение") и принимает пару ключ/значение.

        
          
          const params = new URLSearchParams();params.append("color", "red");console.log(params.toString()); // 'color=red'
          const params = new URLSearchParams();

params.append("color", "red");
console.log(params.toString()); // 'color=red'

        
        
          
        
      

Запись

Секция статьи "Запись"

При записи по имени, параметр добавится, если до этого такого не существовало, и заменит значение, если таковой существовал ранее.

        
          
          const params = new URLSearchParams();params.set("size", "lg");console.log(params.toString()); // 'size=lg'params.append("size", "xl");console.log(params.toString()); // 'size=lg&size=xl'params.set("size", "sm");console.log(params.toString()); // 'size=sm'
          const params = new URLSearchParams();

params.set("size", "lg");
console.log(params.toString()); // 'size=lg'
params.append("size", "xl");
console.log(params.toString()); // 'size=lg&size=xl'
params.set("size", "sm");
console.log(params.toString()); // 'size=sm'

        
        
          
        
      

Получение

Секция статьи "Получение"

С помощью методов get("ключ") и getAll("ключ") можно читать уже хранящиеся параметры.
get - вернёт первое добавленное в поле значение
getAll – вернёт все значения, добавленные в поле

        
          
          const params = new URLSearchParams();params.append("size", "lg");console.log(params.get("size")); // 'lg'params.append("size", "xl");console.log(params.get("size")); // 'lg'console.log(params.getAll("size")); // ['lg', 'xl']
          const params = new URLSearchParams();

params.append("size", "lg");
console.log(params.get("size")); // 'lg'
params.append("size", "xl");
console.log(params.get("size")); // 'lg'
console.log(params.getAll("size")); // ['lg', 'xl']

        
        
          
        
      

Проверка наличия

Секция статьи "Проверка наличия"

has("ключ") – проверяет, был ли добавлен параметр с таким именем

        
          
          const params = new URLSearchParams();params.append("size", "lg");console.log(params.has("size")); // trueconsole.log(params.has("count")); // false
          const params = new URLSearchParams();

params.append("size", "lg");
console.log(params.has("size")); // true
console.log(params.has("count")); // false

        
        
          
        
      

Получение имён всех параметров

Секция статьи "Получение имён всех параметров"

Можно получить имена всех параметров, записанных в поиск, используя метод keys(). Результатом выбора будет итератор.

        
          
          const params = new URLSearchParams("count=10&size=lg&size=xl");for (let value of params.keys()) {  console.log(value);}
          const params = new URLSearchParams("count=10&size=lg&size=xl");

for (let value of params.keys()) {
  console.log(value);
}

        
        
          
        
      

Получение всех значений параметров

Секция статьи "Получение всех значений параметров"

Метод values() получает значения параметров аналогично получению имён их параметров из примера выше.

        
          
          const params = new URLSearchParams("count=10&size=lg&size=xl");for (let value of params.values()) {  console.log(value);}
          const params = new URLSearchParams("count=10&size=lg&size=xl");

for (let value of params.values()) {
  console.log(value);
}

        
        
          
        
      

Получение всех параметров

Секция статьи "Получение всех параметров"

По аналогии с предыдущими двумя методами entries() получает итератор, содержащий пары ключ/значение.

        
          
          const params = new URLSearchParams("count=10&size=lg&size=xl");for (let [key, value] of params.entries()) {  console.log(key, value);}
          const params = new URLSearchParams("count=10&size=lg&size=xl");

for (let [key, value] of params.entries()) {
  console.log(key, value);
}

        
        
          
        
      

Удаление

Секция статьи "Удаление"

Удаляет параметр из поиска по ключу delete("ключ")

        
          
          params.delete("size");
          params.delete("size");

        
        
          
        
      

Сортировка

Секция статьи "Сортировка"

Метод sort() предоставляет возможность отсортировать параметры по алфавиту.

        
          
          const params = new URLSearchParams("a=1&z=4&d=2&x=3");params.sort();console.log(params.toString()); // "a=1&d=2&x=3&z=4"
          const params = new URLSearchParams("a=1&z=4&d=2&x=3");

params.sort();
console.log(params.toString()); // "a=1&d=2&x=3&z=4"

        
        
          
        
      

Перебор

Секция статьи "Перебор"

Метод forEach() перебирает значения, содержащиеся в поиске. Функция, переданная в метод, будет вызвана для каждого элемента в поиске и получит три аргумента – название параметра, значение параметра и сам экземпляр поиска.

        
          
          const params = new URLSearchParams("count=10&size=lg&size=xl");params.forEach((key, value, params) => {  console.log(key, value, params);});
          const params = new URLSearchParams("count=10&size=lg&size=xl");

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

        
        
          
        
      

Приведение параметров к строке

Секция статьи "Приведение параметров к строке"

После того как параметры сформированы, можно сохранить их в строку с помощью метода toString() и использовать для обновления адреса страницы.

        
          
          const params = new URLSearchParams();params.append("size", "lg");params.append("size", "xl");params.toString();
          const params = new URLSearchParams();

params.append("size", "lg");
params.append("size", "xl");

params.toString();

        
        
          
        
      

На практике

Секция статьи "На практике"

Павел Минеев

Секция статьи "Павел Минеев"

Формирование url для запроса в API

Секция статьи "Формирование url для запроса в API"

Класс URLSearchParams хорошо подходит для формирования строки адреса при запросе в API. Например, если нужно сделать запрос с фильтрами или другими параметрами поиска.

Без URLSearchParams:

        
          
          const params = {  size: "xl",  count: 10,  page: 2,};// формируем строку вручнуюconst paramsString = Object.entries(params)  .map(    ([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`  )  .join("&");fetch(`/catalog/t-shirts?${paramsString}`);
          const params = {
  size: "xl",
  count: 10,
  page: 2,
};

// формируем строку вручную
const paramsString = Object.entries(params)
  .map(
    ([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`
  )
  .join("&");

fetch(`/catalog/t-shirts?${paramsString}`);

        
        
          
        
      

URLSearchParams упрощает решение этой задачи:

        
          
          const paramsString = new URLSearchParams({  size: "xl",  count: 10,  page: 2,}).toString();fetch(`/catalog/t-shirts?${paramsString}`);
          const paramsString = new URLSearchParams({
  size: "xl",
  count: 10,
  page: 2,
}).toString();

fetch(`/catalog/t-shirts?${paramsString}`);

        
        
          
        
      

Парсинг параметров из URL

Секция статьи "Парсинг параметров из URL"

Так как URLSearchParams может получать параметры в виде строки, то его можно использовать как парсер текущего адреса страницы. Так мы можем без труда модифицировать их и обновлять адрес.

        
          
          const params = new URLSearchParams(window.location.search);params.append("size", "lg");window.location.assign(  `${window.location.origin}${window.location.pathname}?${params.toString()}`);
          const params = new URLSearchParams(window.location.search);

params.append("size", "lg");

window.location.assign(
  `${window.location.origin}${window.location.pathname}?${params.toString()}`
);