URLSearchParams в JavaScript: как читать и изменять параметры URL
URLSearchParams в JavaScript — это встроенный API для работы с параметрами URL, то есть частью адреса после знака вопроса. Например, в адресе /catalog?page=2&sort=price параметры — это page и sort. Такие значения часто используют для поиска, фильтров, пагинации, сортировки и сохранения состояния страницы.
Ключевой поисковый запрос этой статьи — URLSearchParams JavaScript параметры URL. После прочтения вы сможете уверенно читать query-параметры, менять их и аккуратно обновлять адресную строку без лишней перезагрузки страницы.
Что такое query-параметры в URL
Query-параметры идут после символа ? и записываются в формате ключ=значение. Несколько параметров разделяются символом &:
https://site.ru/products?category=books&page=3&sort=price
Здесь:
categoryравенbooks;pageравен3;sortравенprice.
Как получить параметры текущего URL
Для чтения параметров текущей страницы используется window.location.search. Он возвращает строку после знака вопроса, например ?page=3&sort=price.
const params = new URLSearchParams(window.location.search);
const page = params.get('page');
const sort = params.get('sort');
console.log(page); // '3'
console.log(sort); // 'price'
Метод get() возвращает строку или null, если параметра нет. Поэтому для значений по умолчанию удобно использовать оператор ??:
const params = new URLSearchParams(window.location.search);
const page = params.get('page') ?? '1';
const sort = params.get('sort') ?? 'popular';
console.log(page, sort);
Важно: URLSearchParams всегда возвращает строки
Даже если в URL написано ?page=5, метод get('page') вернёт строку '5', а не число. Если нужно число, преобразуйте значение явно:
const params = new URLSearchParams(window.location.search);
const page = Number(params.get('page') ?? 1);
if (Number.isNaN(page) || page < 1) {
console.log('Некорректный номер страницы');
} else {
console.log('Текущая страница:', page);
}
Это особенно важно для пагинации, лимитов, идентификаторов и любых вычислений.
Проверка наличия параметра через has()
Иногда нужно отличать отсутствующий параметр от пустого значения. Для этого есть метод has():
const params = new URLSearchParams('?search=&page=1');
console.log(params.has('search')); // true
console.log(params.get('search')); // ''
console.log(params.has('sort')); // false
console.log(params.get('sort')); // null
Пустая строка и отсутствие параметра — разные ситуации. Например, ?search= может означать, что пользователь очистил поле поиска.
Как перебрать все параметры URL
URLSearchParams можно перебирать через for...of:
const params = new URLSearchParams('?category=books&page=2&sort=price');
for (const [key, value] of params) {
console.log(key, value);
}
Также доступны методы keys(), values() и entries():
const params = new URLSearchParams('?a=1&b=2');
console.log([...params.keys()]); // ['a', 'b']
console.log([...params.values()]); // ['1', '2']
Повторяющиеся параметры: get() и getAll()
В фильтрах часто встречается несколько значений с одним ключом:
/products?tag=js&tag=frontend&tag=beginner
Метод get() вернёт только первое значение, а getAll() — массив всех значений:
const params = new URLSearchParams('?tag=js&tag=frontend&tag=beginner');
console.log(params.get('tag')); // 'js'
console.log(params.getAll('tag')); // ['js', 'frontend', 'beginner']
Используйте getAll() для чекбоксов, тегов, категорий и мультивыбора.
Как добавить или изменить параметр
Для изменения параметров есть методы set(), append() и delete().
const params = new URLSearchParams('?page=1&sort=popular');
params.set('page', '2'); // изменить или создать параметр
params.append('tag', 'js'); // добавить ещё одно значение
params.append('tag', 'web');
params.delete('sort'); // удалить параметр
console.log(params.toString());
// page=2&tag=js&tag=web
Разница между set() и append() важна:
set()заменяет все значения параметра одним новым;append()добавляет ещё одно значение с тем же ключом.
Как изменить URL в адресной строке без перезагрузки
Частая задача: пользователь выбрал фильтр, и нужно обновить URL, чтобы ссылкой можно было поделиться. Для этого удобно использовать объект URL и History API.
const url = new URL(window.location.href);
url.searchParams.set('page', '2');
url.searchParams.set('sort', 'price');
history.pushState({}, '', url);
history.pushState() добавляет новую запись в историю браузера. Если пользователь нажмёт «Назад», он вернётся к предыдущему URL.
Если не нужно добавлять запись в историю, используйте replaceState():
const url = new URL(window.location.href);
url.searchParams.set('search', 'javascript');
history.replaceState({}, '', url);
replaceState() заменяет текущий адрес. Это хорошо подходит для автосохранения состояния поиска или фильтров.
Практический пример: фильтр товаров
Допустим, у нас есть поиск, сортировка и номер страницы. Напишем функцию, которая обновляет URL аккуратно: пустые значения удаляет, остальные записывает.
function updateCatalogUrl(filters) {
const url = new URL(window.location.href);
for (const [key, value] of Object.entries(filters)) {
if (value === null || value === undefined || value === '') {
url.searchParams.delete(key);
} else {
url.searchParams.set(key, String(value));
}
}
history.replaceState({}, '', url);
}
updateCatalogUrl({
search: 'ноутбук',
sort: 'price',
page: 1
});
Такой подход делает ссылку понятной и чистой: если поле пустое, параметр не висит в URL без необходимости.
Кодирование русских букв и спецсимволов
URLSearchParams сам кодирует символы, которые нельзя напрямую хранить в URL:
const params = new URLSearchParams();
params.set('search', 'книга по JavaScript');
console.log(params.toString());
// search=%D0%BA%D0%BD%D0%B8%D0%B3%D0%B0+%D0%BF%D0%BE+JavaScript
При чтении значение автоматически декодируется:
const params = new URLSearchParams('search=%D0%BA%D0%BD%D0%B8%D0%B3%D0%B0+%D0%BF%D0%BE+JavaScript');
console.log(params.get('search'));
// книга по JavaScript
Поэтому не нужно вручную вызывать encodeURIComponent() для значений, которые вы передаёте через set().
Типичные ошибки новичков
- Склеивать URL вручную. Строки вида
'?page=' + page + '&sort=' + sortбыстро приводят к ошибкам с кодированием и лишними символами. - Забывать, что значения строковые. Для чисел и булевых значений делайте явное преобразование.
- Использовать set() для множественных фильтров. Если нужно несколько
tag, используйтеappend()иgetAll(). - Хранить в URL секретные данные. Токены, пароли и приватную информацию нельзя передавать в query-параметрах.
Мини-шпаргалка по URLSearchParams
const params = new URLSearchParams(window.location.search);
params.get('page'); // получить первое значение
params.getAll('tag'); // получить все значения
params.has('sort'); // проверить наличие
params.set('page', '2'); // установить значение
params.append('tag', 'js'); // добавить значение
params.delete('page'); // удалить параметр
params.toString(); // собрать строку параметров
Если вы хотите не просто копировать примеры, а системно разобраться в JavaScript с практикой, задачами и понятным движением от основ к уверенной разработке, посмотрите курс «JavaScript с Нуля до Гуру 2.0» — пошаговый путь к уверенной работе с JS. Тема URL, объектов браузера и современной практики там отлично ложится на общую картину языка.
Вывод
URLSearchParams — простой и безопасный способ работать с параметрами URL в JavaScript. Используйте его для чтения фильтров, поиска, сортировки, пагинации и синхронизации состояния интерфейса с адресной строкой. Главное — не собирать query-строки вручную, помнить про строковый тип значений и выбирать правильные методы: get(), getAll(), set(), append() и delete().
-
Создано 23.11.2026 17:00:57
-
Михаил Русаков

Комментарии (0):
Для добавления комментариев надо войти в систему.
Если Вы ещё не зарегистрированы на сайте, то сначала зарегистрируйтесь.