/ ↲
    Расширенный поиск

    JavaScript

    URLSearchParams

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

    1. Кратко
    2. Пример
    3. Как это понять
    4. Как пишется
      1. Создание экземпляра класса
      2. Добавление
      3. Запись
      4. Получение
      5. Проверка наличия
      6. Получение имён всех параметров
      7. Получение всех значений параметров
      8. Получение всех параметров
      9. Удаление
      10. Сортировка
      11. Перебор
      12. Приведение параметров к строке
    5. На практике
      1. akellbl4
      2. Формирование url для запроса в API
      3. Парсинг параметров из URL

    Кратко

    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();

    На практике

    akellbl4

    Формирование 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

    Так как 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()}`
);