Learn JavaScript
Справочник / URLSearchParams

URLSearchParams - работа с параметрами URL в JavaScript

URLSearchParams - это встроенный объект для работы с параметрами URL, то есть с частью адреса после ?.

Например, в таком адресе:

https://learn-javascript.ru/search?q=javascript&page=2

параметры - это:

  • q=javascript
  • page=2

URLSearchParams помогает читать, добавлять, изменять и удалять такие параметры без ручной склейки строк через ?, & и =.

Синтаксис

Создать объект можно через new URLSearchParams().

new URLSearchParams(init)

Где init - необязательные начальные данные.

Самый простой вариант:

const params = new URLSearchParams();

params.set("q", "javascript");
params.set("page", "2");

console.log(params.toString()); // "q=javascript&page=2"

Создание из строки

Часто параметры уже есть в виде строки.

const params = new URLSearchParams("q=javascript&page=2");

console.log(params.get("q")); // "javascript"
console.log(params.get("page")); // "2"

Строку можно передавать как с ?, так и без него.

const params = new URLSearchParams("?q=javascript&page=2");

console.log(params.get("q")); // "javascript"

Это удобно, когда вы работаете с window.location.search.

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

const page = params.get("page") || "1";

Создание из объекта

Если параметры известны заранее, можно передать обычный объект.

const params = new URLSearchParams({
  q: "javascript",
  page: "2",
});

console.log(params.toString()); // "q=javascript&page=2"

Значения в URL всегда становятся строками.

const params = new URLSearchParams({
  page: 2,
  active: true,
});

console.log(params.toString()); // "page=2&active=true"

Для простых параметров это удобно. Если нужны несколько значений с одним именем, лучше использовать массив пар или append().

Создание из массива пар

URLSearchParams можно создать из массива пар [ключ, значение].

const params = new URLSearchParams([
  ["q", "javascript"],
  ["page", "2"],
]);

console.log(params.toString()); // "q=javascript&page=2"

Такой вариант полезен, когда один параметр встречается несколько раз.

const params = new URLSearchParams([
  ["tag", "js"],
  ["tag", "frontend"],
]);

console.log(params.toString()); // "tag=js&tag=frontend"

Получение параметров через get()

Метод get() возвращает первое значение параметра.

const params = new URLSearchParams("q=javascript&page=2");

console.log(params.get("q")); // "javascript"
console.log(params.get("page")); // "2"

Если параметра нет, результатом будет null.

const params = new URLSearchParams("q=javascript");

console.log(params.get("sort")); // null

Поэтому для значений по умолчанию часто используют || или ??.

const page = params.get("page") || "1";

getAll() для нескольких значений

Один и тот же параметр может встретиться в URL несколько раз.

const params = new URLSearchParams("tag=js&tag=frontend");

console.log(params.get("tag")); // "js"
console.log(params.getAll("tag")); // ["js", "frontend"]

get() берёт только первое значение, а getAll() возвращает массив всех значений.

Это полезно для фильтров:

const params = new URLSearchParams("color=black&color=white");

const colors = params.getAll("color");

console.log(colors); // ["black", "white"]

Проверка параметра через has()

Метод has() проверяет, есть ли параметр.

const params = new URLSearchParams("q=javascript&page=2");

console.log(params.has("q")); // true
console.log(params.has("sort")); // false

Это отличается от проверки значения, потому что параметр может существовать, но быть пустым.

const params = new URLSearchParams("q=");

console.log(params.has("q")); // true
console.log(params.get("q")); // ""

set() заменяет значение

Метод set() устанавливает значение параметра.

const params = new URLSearchParams("q=js&page=1");

params.set("q", "javascript");
params.set("page", "2");

console.log(params.toString()); // "q=javascript&page=2"

Если параметр уже был, значение заменится.

Если параметра не было, он будет добавлен.

const params = new URLSearchParams("q=javascript");

params.set("page", "2");

console.log(params.toString()); // "q=javascript&page=2"

Если у параметра было несколько значений, set() оставит только одно.

const params = new URLSearchParams("tag=js&tag=frontend");

params.set("tag", "javascript");

console.log(params.toString()); // "tag=javascript"

append() добавляет ещё одно значение

Метод append() не заменяет старое значение, а добавляет новое.

const params = new URLSearchParams();

params.append("tag", "js");
params.append("tag", "frontend");

console.log(params.toString()); // "tag=js&tag=frontend"

Это нужно, когда сервер или ваш код ожидает несколько значений с одним именем.

console.log(params.getAll("tag")); // ["js", "frontend"]

delete() удаляет параметр

Метод delete() удаляет параметр.

const params = new URLSearchParams("q=javascript&page=2");

params.delete("page");

console.log(params.toString()); // "q=javascript"

Если параметр встречался несколько раз, будут удалены все значения с этим именем.

const params = new URLSearchParams("tag=js&tag=frontend&page=1");

params.delete("tag");

console.log(params.toString()); // "page=1"

Перебор параметров

URLSearchParams можно перебирать через for...of.

const params = new URLSearchParams("q=javascript&page=2");

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

Результат:

q javascript
page 2

Также есть методы keys(), values() и entries().

const params = new URLSearchParams("q=javascript&page=2");

console.log([...params.keys()]); // ["q", "page"]
console.log([...params.values()]); // ["javascript", "2"]
console.log([...params.entries()]); // [["q", "javascript"], ["page", "2"]]

toString() превращает параметры в строку

Метод toString() возвращает строку параметров без ?.

const params = new URLSearchParams();

params.set("q", "javascript");
params.set("page", "2");

console.log(params.toString()); // "q=javascript&page=2"

Если нужно собрать полный адрес, ? добавляют отдельно или используют объект URL.

const params = new URLSearchParams({
  q: "javascript",
  page: "2",
});

const url = `https://learn-javascript.ru/search?${params.toString()}`;

console.log(url);
// "https://learn-javascript.ru/search?q=javascript&page=2"

URLSearchParams кодирует значения

Если значение содержит пробелы, русские буквы или специальные символы, URLSearchParams подготовит его для URL.

const params = new URLSearchParams();

params.set("q", "уроки javascript");

console.log(params.toString());

В итоговой строке значение будет закодировано так, чтобы его можно было безопасно использовать в адресе.

При чтении параметра вы получите обычное значение.

const params = new URLSearchParams("q=%D1%83%D1%80%D0%BE%D0%BA%D0%B8");

console.log(params.get("q")); // "уроки"

Использование вместе с URL

У объекта URL уже есть свойство searchParams, которое является объектом URLSearchParams.

const url = new URL("https://learn-javascript.ru/search");

url.searchParams.set("q", "javascript");
url.searchParams.set("page", "2");

console.log(url.href);
// "https://learn-javascript.ru/search?q=javascript&page=2"

Это самый удобный вариант, если вы собираете целый адрес.

Если у вас есть только параметры без домена и пути, можно работать с URLSearchParams отдельно.

const params = new URLSearchParams();

params.set("sort", "price");
params.set("page", "3");

console.log(params.toString()); // "sort=price&page=3"

Когда это полезно

URLSearchParams используют, когда нужно аккуратно работать с query-параметрами:

  • прочитать фильтры из текущего адреса
  • добавить параметры к ссылке
  • собрать строку для GET-запроса
  • обновить page, sort, q или другие параметры
  • обработать несколько значений одного параметра

Пример функции для сборки ссылки на поиск:

function createSearchUrl(query, page) {
  const url = new URL("https://learn-javascript.ru/search");

  url.searchParams.set("q", query);
  url.searchParams.set("page", String(page));

  return url.href;
}

console.log(createSearchUrl("массивы", 2));
// "https://learn-javascript.ru/search?q=%D0%BC%D0%B0%D1%81%D1%81%D0%B8%D0%B2%D1%8B&page=2"

Частые ошибки

Ожидать, что toString() добавит вопросительный знак

const params = new URLSearchParams("q=javascript");

console.log(params.toString()); // "q=javascript"

toString() возвращает только параметры. Символ ? в результат не входит.

Использовать get() там, где нужно несколько значений

const params = new URLSearchParams("tag=js&tag=frontend");

console.log(params.get("tag")); // "js"

Если нужны все значения, используйте getAll().

console.log(params.getAll("tag")); // ["js", "frontend"]

Путать set() и append()

const params = new URLSearchParams("tag=js&tag=frontend");

params.set("tag", "javascript");

console.log(params.toString()); // "tag=javascript"

set() заменяет значения, а append() добавляет ещё одно.

Быстрая памятка

  • URLSearchParams работает с параметрами после ?
  • объект создают через new URLSearchParams()
  • параметры можно создать из строки, объекта или массива пар
  • get() возвращает первое значение
  • getAll() возвращает все значения с одним именем
  • has() проверяет наличие параметра
  • set() добавляет или заменяет значение
  • append() добавляет ещё одно значение
  • delete() удаляет параметр
  • toString() возвращает строку без ?
  • значения автоматически кодируются для URL
  • у объекта URL есть готовое свойство searchParams

Коротко

URLSearchParams нужен для удобной работы с query-параметрами URL. Он позволяет читать, добавлять, заменять, удалять и перебирать параметры без ручной сборки строк. В связке с URL это самый аккуратный способ собирать адреса с фильтрами, поиском, пагинацией и другими параметрами.

← URL.revokeObjectURL() - освобождение временного blob URL в JavaScript
append() - добавление параметра в URLSearchParams →