Клавиша / esc

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()}`
)