append() - добавление параметра в URLSearchParams

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

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

Например:

const params = new URLSearchParams();

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

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

В отличие от set(), метод append() не заменяет старое значение, а добавляет ещё одну пару имя=значение.

Синтаксис

params.append(name, value)

Где:

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

Метод ничего не возвращает. Он изменяет сам объект URLSearchParams.

const params = new URLSearchParams();

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

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

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

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

const params = new URLSearchParams();

params.append("q", "javascript");
params.append("page", "1");

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

Так можно постепенно собрать строку параметров для ссылки или GET-запроса.

const params = new URLSearchParams();

params.append("category", "courses");
params.append("sort", "new");

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

console.log(url);
// "https://learn-javascript.ru/catalog?category=courses&sort=new"

Несколько значений с одним именем

Главная причина использовать append() - несколько значений у одного параметра.

Так часто передают фильтры:

const params = new URLSearchParams();

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

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

В URL это выглядит как несколько одинаковых параметров:

https://learn-javascript.ru/search?tag=javascript&tag=dom&tag=async

Это нормальная форма записи. Сервер или ваш код могут прочитать все значения с помощью getAll().

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

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

Если использовать get(), вернётся только первое значение.

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

append() и set()

append() и set() похожи тем, что оба добавляют параметр, если его ещё нет.

Разница появляется, когда параметр уже существует.

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

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

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

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

set() заменяет значение и удаляет остальные значения с таким же именем:

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

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

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

Практическое правило простое:

нужен один параметр page=2 - чаще подходит set()
нужны несколько фильтров tag=js&tag=dom - подходит append()

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

Чаще всего append() используют через свойство searchParams у объекта URL.

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

url.searchParams.append("tag", "javascript");
url.searchParams.append("tag", "functions");

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

Так удобнее, чем вручную добавлять ?, & и =.

Например, можно собрать ссылку на страницу поиска:

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

  for (const tag of tags) {
    url.searchParams.append("tag", tag);
  }

  return url.href;
}

console.log(createSearchUrl(["javascript", "array"]));
// "https://learn-javascript.ru/search?tag=javascript&tag=array"

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

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

const params = new URLSearchParams();

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

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

Обычно лучше делать преобразование явно, чтобы код было проще читать.

const page = 2;

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

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

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

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

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

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

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

Порядок добавления сохраняется

append() добавляет параметр в конец списка.

const params = new URLSearchParams();

params.append("q", "javascript");
params.append("tag", "dom");
params.append("tag", "events");
params.append("page", "2");

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

Обычно порядок параметров не влияет на работу запроса, но он важен, если вы выводите строку, сравниваете её в тестах или хотите получить предсказуемый URL.

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

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

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

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

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

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

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

Читать только get(), когда значений несколько

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

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

get() возвращает первое значение. Чтобы получить все значения, нужен getAll().

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

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

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

Коротко

append() нужен, чтобы добавить параметр в URLSearchParams без замены старых значений. Он особенно полезен для фильтров и других случаев, где один ключ может повторяться несколько раз: tag=javascript&tag=dom. Если параметр должен быть только один, чаще удобнее использовать set().