URLSearchParams: чтение и изменение повторяющихся параметров

Назначение

URLSearchParams предоставляет операции над строкой запроса. Он помогает работать с кодированием и повторяющимися именами без ручного разбиения по амперсандам.

Как это работает

Get возвращает первое значение, getAll — все значения имени. Append добавляет ещё одно, set заменяет набор значений указанного имени. Связанный объект url.searchParams изменяет соответствующий URL.

Пример

const url = new URL("https://example.com/search?tag=html&tag=css");
console.assert(url.searchParams.get("tag") === "html");
console.assert(url.searchParams.getAll("tag").length === 2);
url.searchParams.append("tag", "js");
url.searchParams.set("q", "HTML & CSS");
console.assert(url.searchParams.get("q") === "HTML & CSS");
url.searchParams.set("tag", "web");
console.assert(url.searchParams.getAll("tag").join(",") === "web");
console.log(url.href);

Что должно получиться

Повторяющиеся tag сначала сохраняются, затем заменяются одним значением. Амперсанд внутри q кодируется как часть значения и не становится разделителем нового параметра.

Граница применения и частая ошибка

Конструктор URLSearchParams не разбирает произвольный полный URL как объект URL. Не кодируйте значение вручную перед set без причины: это может дать двойное кодирование. Параметры остаются пользовательскими данными и требуют прикладной проверки.

Самостоятельная проверка

Добавьте значение с пробелом, плюсом и кириллицей. Сравните исходное значение через get и сериализованную строку. Отдельно решите, допустимы ли повторяющиеся имена для каждого параметра вашего приложения.

Пример JavaScript проверяйте в собственном учебном файле или консоли своего проекта. Встроенная песочница справочника JavaScript не выполняет. Успешное выполнение в одной среде не гарантирует поддержку метода во всех браузерах.

Связанные материалы

• Параметры URL
• Обработка ошибок
• Коллекция Map