Enter
    Расширенный поиск
    Клавиша / esc

    JavaScript

    URLSearchParams

    Получить или отформатировать поисковые параметры из URL без боли.

    Время чтения: меньше 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')console.log(params.getAll('size'))// ['lg', 'xl']
          params.append('size', 'xl')
console.log(params.getAll('size'))
// ['lg', 'xl']

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

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

const url = `/catalog/?${paramsSting}`
console.log(url)
// '/catalog/?count=10&size=lg&size=xl'

    Как понять

    Скопировано

    Когда нужно сформировать 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)}// 'count'// 'size'// 'size'
          const params = new URLSearchParams('count=10&size=lg&size=xl')

for (let value of params.keys()) {
  console.log(value)
}
// 'count'
// 'size'
// 'size'

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

    Скопировано

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

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

for (let value of params.values()) {
  console.log(value)
}
// '10'
// 'lg'
// 'xl'

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

    Скопировано

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

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

for (let [key, value] of params.entries()) {
  console.log(key, value)
}
// count 10
// size lg
// size xl

    Удаление

    Скопировано

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

            
          
          params.delete('size')console.log(params.toString())// 'count=10'
          params.delete('size')

console.log(params.toString())
// 'count=10'

    Сортировка

    Скопировано

    Метод 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

    Скопировано

    Класс 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()}`
)

    Читайте также

    • fetch()

      Модно и современно отправляем запросы на сервер.

    • window.location

      Читаем информацию о текущем URL страницы.

    • Паттерны Gateway и Backend-for-Frontend

      Gateway — единое окно для разных API. Backend-for-Frontend использует Gateway для обработки запросов и подготовки ответов, предназначенных для фронтенда.