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

Чтение и запись query string (?page=2&sort=asc) через нативный URLSearchParams — без ручного split и decode.

Задача

Нужно прочитать параметры из URL (например, текущую страницу или фильтры), а также обновить URL при навигации без перезагрузки страницы.

Решение

Чтение параметров:

// URL: https://example.com/products?page=3&sort=price&order=asc&tag=js

const params = new URLSearchParams(window.location.search);

const page  = params.get('page');    // '3' (всегда строка или null)
const sort  = params.get('sort');    // 'price'
const order = params.get('order');   // 'asc'
const tag   = params.get('tag');     // 'js'
const missing = params.get('foo');   // null

// Преобразование в число
const pageNum = Number(params.get('page')) || 1;

// Проверка наличия
params.has('sort'); // true

// Несколько значений одного ключа: ?tag=js&tag=css
const tags = params.getAll('tag'); // ['js', 'css']

// Итерация
for (const [key, value] of params) {
  console.log(key, value);
}

Изменение URL без перезагрузки:

function updateParams(updates) {
  const params = new URLSearchParams(window.location.search);

  Object.entries(updates).forEach(([key, value]) => {
    if (value === null || value === undefined || value === '') {
      params.delete(key);
    } else {
      params.set(key, value);
    }
  });

  const newUrl = `${window.location.pathname}?${params.toString()}`;
  window.history.pushState({}, '', newUrl); // добавить в историю
  // или window.history.replaceState({}, '', newUrl); // заменить текущую
}

// Перейти на страницу 2 с сортировкой
updateParams({ page: 2, sort: 'price' });
// Убрать параметр
updateParams({ tag: null });

Утилита для типизированного чтения:

function getParam<T extends string = string>(
  key: string,
  defaultValue?: T
): T | null {
  const value = new URLSearchParams(window.location.search).get(key);
  return (value as T | null) ?? defaultValue ?? null;
}

const page = getParam('page', '1'); // всегда строка

Ключевые моменты

  • URLSearchParams автоматически декодирует %20 → пробел и %2B → +; не нужен ручной decodeURIComponent.
  • params.get всегда возвращает строку или null; числа конвертируй явно через Number или parseInt.
  • pushState добавляет запись в историю (работает «назад»); replaceState — заменяет текущую.
  • params.toString() возвращает готовую query string без ? — добавляй ? вручную при формировании URL.

Связанные рецепты / темы