set() - установка параметра в URLSearchParams

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

Если параметра ещё нет, 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"

Чаще всего set() используют для параметров, у которых должно быть одно текущее значение: страница, сортировка, поисковый запрос, выбранная категория.

Синтаксис

params.set(name, value)

Где:

name - имя параметра
value - новое значение параметра

Метод изменяет текущий объект URLSearchParams и возвращает undefined.

const params = new URLSearchParams();

const result = params.set("page", "2");

console.log(result); // undefined
console.log(params.toString()); // "page=2"

Добавление нового параметра

Если параметра ещё нет, set() добавит его.

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

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

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

Это удобно, когда вы собираете параметры постепенно.

const params = new URLSearchParams();

params.set("category", "courses");
params.set("sort", "new");
params.set("page", "1");

console.log(params.toString());
// "category=courses&sort=new&page=1"

Замена существующего параметра

Если параметр уже есть, set() заменит его значение.

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

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

console.log(params.toString()); // "sort=popular&page=2"

Это основное отличие set() от append().

set() подходит для состояния, где значение должно быть одно.

const params = new URLSearchParams("page=1");

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

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

В результате остаётся последнее установленное значение.

Что происходит с повторяющимися параметрами

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

const params = new URLSearchParams("tag=javascript&tag=dom&tag=async");

console.log(params.getAll("tag")); // ["javascript", "dom", "async"]

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

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

console.log(params.toString()); // "tag=browser"
console.log(params.getAll("tag")); // ["browser"]

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

Если вы хотите добавить ещё одно значение к существующим, используйте append().

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

params.append("tag", "dom");

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

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

На практике set() часто вызывают через searchParams у объекта URL.

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

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

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

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

const url = new URL("https://learn-javascript.ru/search?q=js&page=1");

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

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

Так проще и надёжнее, чем менять строку адреса вручную.

Обновление текущего адреса

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

const url = new URL("https://learn-javascript.ru/catalog?category=books&page=1");

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

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

Параметр category остался на месте, а page изменился.

Такой подход часто используют для пагинации, сортировки и фильтров.

function createCatalogUrl(category, page) {
  const url = new URL("https://learn-javascript.ru/catalog");

  url.searchParams.set("category", category);
  url.searchParams.set("page", String(page));

  return url.href;
}

console.log(createCatalogUrl("courses", 3));
// "https://learn-javascript.ru/catalog?category=courses&page=3"

Значения становятся строками

Параметры URL хранятся как строки. Значение, переданное в set(), будет преобразовано к строке.

const params = new URLSearchParams();

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

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

В реальном коде лучше делать преобразование явно.

const page = 2;

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

Так понятнее, что именно попадёт в URL.

Кодирование значений

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

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

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

console.log(url.searchParams.get("q")); // "уроки javascript"

В итоговом адресе значение будет закодировано корректно, а при чтении через get() вы получите обычную строку.

Когда использовать set()

set() хорошо подходит, когда у параметра должно быть одно значение:

поисковая строка q
номер страницы page
сортировка sort
категория category
режим отображения view

Пример обновления сортировки:

function updateSort(currentUrl, sort) {
  const url = new URL(currentUrl);

  url.searchParams.set("sort", sort);
  url.searchParams.set("page", "1");

  return url.href;
}

console.log(
  updateSort("https://learn-javascript.ru/catalog?sort=new&page=4", "popular"),
);
// "https://learn-javascript.ru/catalog?sort=popular&page=1"

Здесь при смене сортировки страница сбрасывается на первую.

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

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

const params = new URLSearchParams();

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

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

Если нужно сохранить оба значения, используйте append().

params.append("tag", "javascript");
params.append("tag", "dom");

Ожидать, что set() вернёт новый объект

const params = new URLSearchParams();

const result = params.set("page", "2");

console.log(result); // undefined

set() изменяет текущий объект. Новый URLSearchParams он не создаёт.

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

set() устанавливает значение параметра
если параметра нет, он будет добавлен
если параметр уже есть, значение будет заменено
если параметр повторялся несколько раз, останется одно значение
метод изменяет текущий URLSearchParams
set() возвращает undefined
значения параметров становятся строками
для нескольких значений с одним именем используйте append()
с полным адресом удобно работать через url.searchParams.set(...)

Коротко

set() нужен, чтобы добавить или заменить один query-параметр в URLSearchParams. Он оставляет у параметра только одно значение, поэтому хорошо подходит для page, sort, q, category и похожих настроек. Если один ключ должен встречаться несколько раз, лучше использовать append().