Разбираем строку запроса в JavaScript

Разбираем строку запроса в JavaScriptручной парсер, его тонкости и URLSearchParams вместо него

Достать параметр из адреса страницы кажется делом одной строки. На деле мешают плюсы, кодировка и повторяющиеся ключи. Показываем старый парсер и современный API, который решает всё это сам.

Раздел
JavaScript
Стек
JavaScriptURLSearchParamsURLHistory API
Уровень
Новичок
Опубликовано
Обновлено
Чтение
7 мин
Коротко
  • Плюс в строке запроса означает пробел, decodeURIComponent его не трогает.
  • Один ключ может прийти несколько раз, берите getAll.
  • URLSearchParams и new URL() заменяют любой самописный парсер.
  • Фильтры без перезагрузки пишите в адрес через history.replaceState.
Как решаем
  1. Возьмите location.search или полный адрес через new URL()
  2. Читайте значения через get, списки через getAll
  3. Меняйте параметры через set, append и delete
  4. Собирайте строку методом toString, без ручной склейки
  5. Обновляйте адрес через history.replaceState

Задача: достать параметры из адреса#

Страница каталога открывается по адресу вида /catalog?tag=css&tag=js&q=sticky+footer, и скрипту нужно понять, какие фильтры выбраны. В браузере эта часть адреса лежит в location.search: строка начинается со знака вопроса, пары разделены амперсандом, ключ и значение разделены знаком равенства. Кажется, что хватит двух вызовов split, и долгие годы именно так и писали.

Подвох в том, что у строки запроса есть свои правила кодирования. Пробел из HTML-формы приходит как +, кириллица и спецсимволы приходят в процентной кодировке, а один и тот же ключ может повториться, если в форме несколько чекбоксов с одинаковым именем. Самописный парсер должен учесть всё это, иначе он работает только на «удобных» адресах.

Ручной парсер, как писали раньше#

Вот функция, которую мы держали в утилитах в эпоху, когда о встроенном API в браузерах можно было только мечтать. Она переживает пустые пары, ключи без значения, плюсы и повторы:

JavaScript
// 2012: разбор location.search вручную
function parseQuery(search) {
  var result = {};
  var query = search.charAt(0) === '?' ? search.slice(1) : search;
  if (!query) return result;

  var pairs = query.split('&');
  for (var i = 0; i < pairs.length; i++) {
    if (!pairs[i]) continue;                 // пропускаем "a=1&&b=2"
    var idx = pairs[i].indexOf('=');
    var key = idx > -1 ? pairs[i].slice(0, idx) : pairs[i];
    var val = idx > -1 ? pairs[i].slice(idx + 1) : '';

    key = decodeURIComponent(key.replace(/\+/g, ' '));
    val = decodeURIComponent(val.replace(/\+/g, ' '));

    if (result.hasOwnProperty(key)) {        // повторяющийся ключ
      if (!(result[key] instanceof Array)) result[key] = [result[key]];
      result[key].push(val);
    } else {
      result[key] = val;
    }
  }
  return result;
}

parseQuery('?tag=css&tag=js&q=sticky+footer');
// { tag: ['css', 'js'], q: 'sticky footer' }

Несколько деталей, на которых чаще всего ошибались:

  • Плюс как пробел. decodeURIComponent декодирует только процентные последовательности, а + оставляет как есть. Поэтому замена плюсов идёт до декодирования: если сделать её после, настоящий плюс, пришедший как %2B, тоже превратится в пробел.
  • Знак равенства в значении. Делить пару нужно по первому =, а не через split('='), иначе значение a=b=c потеряет хвост.
  • Ошибки декодирования. Битая последовательность вроде %E0%A4%A заставит decodeURIComponent бросить URIError. В боевом коде вызов стоит обернуть в try.
  • Повторы. Если просто присваивать result[key] = val, из трёх отмеченных тегов останется последний.
  • Хеш. Всё после # в location.search не попадает, но если разбирать произвольную строку адреса, фрагмент нужно отрезать заранее.

Отдельная неприятность: тип результата зависит от данных. Один тег даёт строку, два тега дают массив, и каждый потребитель функции вынужден это проверять. Похожие проблемы с формами и параметрами на стороне сервера мы разбирали в заметке о пагинации со строкой запроса в CodeIgniter.

URLSearchParams: тот же разбор одной строкой#

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

JavaScript
const params = new URLSearchParams(location.search); // "?" в начале не мешает

params.get('q');        // 'sticky footer' (плюс уже стал пробелом)
params.get('page');     // null, если ключа нет
params.getAll('tag');   // ['css', 'js']
params.has('tag');      // true

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

// объект для удобства; при повторах останется последнее значение
const flat = Object.fromEntries(params);

Объект перебирается в цикле for...of и отдаёт пары в исходном порядке. Когда нужен обычный объект, удобно вызвать Object.fromEntries(params), но помните, что при повторяющихся ключах там останется только последнее значение. Для списков всегда используйте getAll, он возвращает массив даже для единственного значения, и проверки типа больше не нужны.

Сравнение старого и нового подхода по типичным случаям:

СлучайРучной splitURLSearchParams
q=sticky+footerнужна замена + до декодированияпробел сразу
tag=css&tag=jsсвоя логика для массивовgetAll('tag')
ключ без значениянадо обработать отдельнопустая строка
нет ключаundefinednull из get
сборка строкиручная склейка и encodeURIComponenttoString()

Собираем адрес через new URL()#

Обратная задача, собрать адрес с параметрами, раньше решалась конкатенацией строк, и в ней легко было забыть про кодирование или поставить второй знак вопроса. Класс URL разбирает адрес целиком, а его свойство searchParams это живой экземпляр URLSearchParams: изменения в нём сразу отражаются в url.search и url.href.

JavaScript
const url = new URL('/search?q=grid&page=2', 'https://example.test');

url.searchParams.set('page', '3');      // заменить значение
url.searchParams.append('tag', 'css');  // добавить ещё одно
url.searchParams.delete('q');           // убрать ключ

url.toString();
// 'https://example.test/search?page=3&tag=css'

Второй аргумент конструктора задаёт базу для относительных путей. Без него строка вроде /search?q=grid вызовет TypeError, потому что относительный адрес нельзя разобрать без базы. В браузере базой обычно служит location.origin или location.href.

Метод set удаляет все прежние значения ключа и оставляет одно, append добавляет ещё одно к существующим, delete убирает ключ целиком. При сериализации пробел станет плюсом, а не %20, это нормальное поведение формата application/x-www-form-urlencoded, и сервер его понимает.

Что изменилось к 2026 году#

Самописные парсеры строки запроса в новом коде больше не нужны: URL и URLSearchParams есть во всех актуальных браузерах, в Node.js и в Deno, а также в средах вроде Cloudflare Workers. Что стоит взять на вооружение:

  • Фильтры в адресе без перезагрузки. Состояние списка (сортировка, страница, теги) удобно хранить в строке запроса: ссылку можно отправить коллеге, а кнопка «назад» работает предсказуемо. Обновлять адрес нужно через History API.
  • Проверка адреса без исключений. Статический метод URL.canParse() отвечает, разберётся ли строка, без блока try. В свежих браузерах есть и URL.parse(), который возвращает null вместо исключения.
  • Счётчик параметров. У URLSearchParams появилось свойство size, а метод has научился принимать второй аргумент со значением.
  • Фреймворки. В React Router, Next.js и других роутерах для чтения параметров есть свои хуки, но внутри они отдают тот же URLSearchParams, и все приёмы из этой заметки к нему применимы.
JavaScript
function applyFilter(name, value) {
  const url = new URL(location.href);
  if (value) {
    url.searchParams.set(name, value);
  } else {
    url.searchParams.delete(name);
  }
  url.searchParams.delete('page');            // при смене фильтра начинаем с первой страницы
  history.replaceState(null, '', url);        // адрес обновлён, перезагрузки нет
  renderList(Object.fromEntries(url.searchParams));
}

select.addEventListener('change', (e) => applyFilter('sort', e.target.value));

history.replaceState подменяет текущую запись в истории, поэтому переключение сортировки не засоряет кнопку «назад». Если каждое изменение фильтра должно быть отдельным шагом истории, используйте pushState и слушайте событие popstate, чтобы перерисовать список при возврате. Частые изменения, например ввод в поле поиска, стоит пропускать через задержку, об этом наша заметка про debounce и throttle. А если фильтры переключаются кнопками внутри большого списка, обработчик удобно повесить один на контейнер, как в разборе делегирования событий.

Короткий чек-лист#

  1. Не разбирайте строку запроса регулярками и split в новом коде, берите URLSearchParams.
  2. Для параметров, которые могут повторяться, используйте getAll, а не get.
  3. Проверяйте отсутствие ключа сравнением с null: пустая строка означает, что ключ есть, но без значения.
  4. Числа и булевы значения приводите явно, URLSearchParams всегда отдаёт строки.
  5. Собирайте адреса через new URL() и searchParams, не склеивайте строки руками.
  6. Значения из адреса это пользовательский ввод: не вставляйте их в innerHTML и проверяйте на сервере.

Больше рецептов для браузера собрано в разделе JavaScript.

+в форме означает пробел
getAllвсе значения повторяющегося ключа
nullget() для отсутствующего ключа

«Строка запроса только выглядит как набор пар ключ=значение; её правила проще доверить URLSearchParams.»

Главный вывод заметки

Вопросы и ответы

Вопросы и ответы

Почему decodeURIComponent не превращает плюс в пробел?
Эта функция декодирует только процентные последовательности вроде %20. Замена плюса на пробел относится к формату отправки HTML-форм, поэтому в ручном парсере её делают отдельно и до декодирования. URLSearchParams учитывает это правило сам.
Как получить все значения параметра, который встречается несколько раз?
Используйте метод getAll: он вернёт массив строк в порядке появления в адресе, даже если значение одно. Метод get отдаёт только первое значение, а Object.fromEntries при повторах сохраняет последнее.
Чем set отличается от append в URLSearchParams?
Метод set удаляет все существующие значения ключа и записывает одно новое. Метод append добавляет ещё одно значение, не трогая прежние. Для одиночных фильтров подходит set, для списков вроде тегов append.
Как поменять параметры в адресе, не перезагружая страницу?
Создайте new URL(location.href), измените его searchParams и передайте объект в history.replaceState или history.pushState. Адрес в строке браузера обновится, страница не перезагрузится, а ссылку можно будет скопировать и открыть с теми же фильтрами.
Заметка обновлена 12 ноября 2026: код проверен на актуальных версиях, добавлены современные варианты.

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