getAll() - получение всех значений параметра из URLSearchParams

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

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

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

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

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

Синтаксис

params.getAll(name)

Где name - имя параметра, значения которого нужно получить.

Метод всегда возвращает массив.

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

const tags = params.getAll("tag");

console.log(tags); // ["javascript", "dom"]

Если параметра нет, вернётся пустой массив.

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

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

getAll() и get()

get() возвращает только первое значение параметра.

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

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

getAll() возвращает все значения с таким именем.

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

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

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

Несколько одинаковых параметров в URL

Повторяющиеся параметры выглядят так:

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

Это обычная запись для нескольких значений одного ключа.

const url = new URL(
  "https://learn-javascript.ru/search?tag=javascript&tag=dom&tag=async",
);

const tags = url.searchParams.getAll("tag");

console.log(tags); // ["javascript", "dom", "async"]

Метод сохраняет порядок значений таким, каким они идут в строке параметров.

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

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

Использование вместе с append()

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

const params = new URLSearchParams();

params.append("tag", "javascript");
params.append("tag", "array");
params.append("tag", "object");

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

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

append() добавляет ещё одно значение, а getAll() позволяет получить весь список.

Пустой массив, а не null

Если параметр отсутствует, getAll() возвращает [].

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

const tags = params.getAll("tag");

console.log(tags); // []

Это отличается от get(), который для отсутствующего параметра возвращает null.

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

Благодаря этому результат getAll() удобно сразу перебирать.

for (const tag of params.getAll("tag")) {
  console.log(tag);
}

Если параметров нет, цикл просто не выполнится.

Пустые значения тоже попадают в массив

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

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

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

Это важно, если вы отличаете отсутствующий параметр от пустого значения.

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

console.log(params.has("tag")); // true
console.log(params.getAll("tag")); // [""]

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

Как и другие методы URLSearchParams, getAll() возвращает строки.

const params = new URLSearchParams("id=10&id=20&id=30");

console.log(params.getAll("id")); // ["10", "20", "30"]

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

const ids = params.getAll("id").map(Number);

console.log(ids); // [10, 20, 30]

То же самое относится к boolean-значениям.

const params = new URLSearchParams("active=true&active=false");

const values = params.getAll("active").map((value) => value === "true");

console.log(values); // [true, false]

Практический пример с фильтрами

Допустим, страница каталога умеет фильтровать материалы по темам.

Адрес может выглядеть так:

https://learn-javascript.ru/catalog?topic=dom&topic=async&topic=arrays

Прочитать выбранные темы можно так:

function getSelectedTopics() {
  const url = new URL(window.location.href);

  return url.searchParams.getAll("topic");
}

const topics = getSelectedTopics();

console.log(topics); // ["dom", "async", "arrays"]

Теперь массив можно использовать для подсветки чекбоксов или фильтрации списка.

const selectedTopics = new Set(getSelectedTopics());

console.log(selectedTopics.has("dom")); // true

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

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

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

url.searchParams.append("topic", "основы javascript");
url.searchParams.append("topic", "работа с DOM");

console.log(url.searchParams.getAll("topic"));
// ["основы javascript", "работа с DOM"]

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

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

Ожидать null, если параметра нет

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

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

getAll() возвращает массив. Если совпадений нет, массив будет пустым.

Использовать get(), когда параметр повторяется

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

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

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

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

Забывать преобразовать строки

const params = new URLSearchParams("id=10&id=20");

const ids = params.getAll("id");

console.log(ids); // ["10", "20"]

Если дальше нужны числа, преобразуйте значения.

const ids = params.getAll("id").map(Number);

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

getAll() возвращает все значения параметра
метод принимает имя параметра
результат всегда массив
если параметра нет, вернётся []
если значение пустое, в массиве будет ""
порядок значений сохраняется
все значения возвращаются строками
для одного значения обычно используют get()
для повторяющихся параметров используйте getAll()
повторяющиеся параметры удобно добавлять через append()

Коротко

getAll() нужен, чтобы получить все значения одного query-параметра из URLSearchParams. Он возвращает массив строк: с найденными значениями или пустой массив, если параметра нет. Метод особенно полезен для фильтров, тегов и других URL, где один ключ повторяется несколько раз.