URLSearchParams: параметры поиска без ручной склейки строк

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

Строим адрес и читаем его обратно

const params = new URLSearchParams();
params.set('q', 'C++ заметки');
params.append('tag', 'php');
params.append('tag', 'linux');
const address = '/search?' + params.toString();
console.log(address);

const restored = new URLSearchParams(params.toString());
console.log(restored.get('q') === 'C++ заметки');
console.log(restored.getAll('tag')); // ['php', 'linux']

Метод set устанавливает одно значение ключа и убирает прежние повторения этого ключа. Метод append добавляет новую пару, поэтому подходит для множества выбранных меток. При чтении get возвращает первое значение, а getAll собирает все. Эти различия должны совпадать с договорённостью серверного обработчика: разные серверные библиотеки могут представлять повторяющиеся ключи по-разному. Формат нужно проверить на реальном маршруте поиска, а не только в консоли браузера.

Не кодируем значение дважды

В методы передают исходную строку, а не результат encodeURIComponent. Сериализатор сам обработает специальные символы. Пробел в таком формате записывается плюсом, а настоящий плюс кодируется отдельно. Если передать уже закодированную строку, знак процента тоже будет закодирован и сервер получит другое значение. При разборе готовой строки запроса плюс, наоборот, трактуется как пробел: это особенно важно для двоичных строк и нестандартных токенов.

URLSearchParams не проверяет допустимость значения для вашей задачи. Параметр page со строкой минус один остаётся строкой, пока приложение не выполнит разбор и проверку диапазона. Инструмент также не делает URL подходящим местом для секретов: адрес может попасть в историю, журналы и копируемые ссылки. При обновлении адреса учитывайте, что форма кодирования может измениться, даже когда пользовательское значение осталось тем же.

Проверяем круговой проход

Прогоните через запись и чтение пустую строку, пробел, плюс, амперсанд и кириллицу. Текст должен вернуться без изменений. Затем проверьте повтор метки и отсутствующий ключ: get вернёт для него null, а для пустого значения — строку. Это различие важно при восстановлении фильтров.

Источники и дальнейшее чтение

• WHATWG: URLSearchParams
• MDN: URLSearchParams