URLSearchParams

Базовая Широко доступна *

Эта функция хорошо зарекомендовала себя и работает на многих устройствах и версиях браузера. Она доступна во всех браузерах с июля 2015 года.

* Некоторые части этой функции могут иметь разный уровень поддержки.

Примечание: Эта функция доступна в Потоках веб-приложений.

Интерфейс URLSearchParams определяет служебные методы для работы со строкой запроса URL.

Объекты URLSearchParams являются итерируемыми, поэтому их можно напрямую использовать в структуре for...of для итерирования по парам ключ/значение в том же порядке, что и в строке запроса. Например, следующие две строки эквивалентны:

for (const [key, value] of mySearchParams) {
}
for (const [key, value] of mySearchParams.entries()) {
}

Хотя URLSearchParams функционально похож на Map, при итерировании он может столкнуться с некоторыми особенностями, которых Map не имеет благодаря своей реализации.

Конструктор

URLSearchParams(): Возвращает экземпляр объекта URLSearchParams.

Свойства экземпляра

size Только для чтения: Указывает общее количество записей параметров запроса.

Методы экземпляра

URLSearchParams[Symbol.iterator](): Возвращает iterator, позволяющий итерироваться по всем парам ключ/значение, содержащимся в этом объекте, в том же порядке, что и в строке запроса.
URLSearchParams.append(): Добавляет заданную пару ключ/значение в качестве нового параметра запроса.
URLSearchParams.delete(): Удаляет параметры запроса, соответствующие имени и (необязательно) значению, из списка всех параметров запроса.
URLSearchParams.entries(): Возвращает iterator, позволяющий итерироваться по всем парам ключ/значение, содержащимся в этом объекте, в том же порядке, что и в строке запроса.
URLSearchParams.forEach(): Позволяет итерироваться по всем значениям, содержащимся в этом объекте, с помощью функции обратного вызова.
URLSearchParams.get(): Возвращает первое значение, связанное с данным параметром запроса.
URLSearchParams.getAll(): Возвращает все значения, связанные с данным параметром запроса.
URLSearchParams.has(): Возвращает логическое значение, указывающее, существует ли данный параметр или пара ключ/значение.
URLSearchParams.keys(): Возвращает iterator, позволяющий итерироваться по всем ключам пар ключ/значение, содержащимся в этом объекте.
URLSearchParams.set(): Устанавливает значение, связанное с заданным параметром запроса, на заданное значение. Если есть несколько значений, остальные удаляются.
URLSearchParams.sort(): Сортирует все пары ключ/значение (если таковые имеются) по их ключам.
URLSearchParams.toString(): Возвращает строку, содержащую строку запроса, подходящую для использования в URL.
URLSearchParams.values(): Возвращает iterator, позволяющий итерироваться по всем значениям пар ключ/значение, содержащимся в этом объекте.

Примеры

const paramsString = "q=URLUtils.searchParams&topic=api";
const searchParams = new URLSearchParams(paramsString);

// Iterating the search parameters
for (const p of searchParams) {
  console.log(p);
}

console.log(searchParams.has("topic")); // true
console.log(searchParams.has("topic", "fish")); // false
console.log(searchParams.get("topic") === "api"); // true
console.log(searchParams.getAll("topic")); // ["api"]
console.log(searchParams.get("foo") === null); // true
console.log(searchParams.append("topic", "webdev"));
console.log(searchParams.toString()); // "q=URLUtils.searchParams&topic=api&topic=webdev"
console.log(searchParams.set("topic", "More webdev"));
console.log(searchParams.toString()); // "q=URLUtils.searchParams&topic=More+webdev"
console.log(searchParams.delete("topic"));
console.log(searchParams.toString()); // "q=URLUtils.searchParams"

// Search parameters can also be an object
const paramsObj = { foo: "bar", baz: "bar" };
const searchParams = new URLSearchParams(paramsObj);

console.log(searchParams.toString()); // "foo=bar&baz=bar"
console.log(searchParams.has("foo")); // true
console.log(searchParams.get("foo")); // "bar"

Дублирующиеся параметры запроса

const paramStr = "foo=bar&foo=baz";
const searchParams = new URLSearchParams(paramStr);

console.log(searchParams.toString()); // "foo=bar&foo=baz"
console.log(searchParams.has("foo")); // true
console.log(searchParams.get("foo")); // bar, only returns the first value
console.log(searchParams.getAll("foo")); // ["bar", "baz"]

Отсутствие парсинга URL

Конструктор URLSearchParams не анализирует полные URL. Однако он удалит начальный ? из строки, если он есть.

const paramsString1 = "http://example.com/search?query=%40";
const searchParams1 = new URLSearchParams(paramsString1);

console.log(searchParams1.has("query")); // false
console.log(searchParams1.has("http://example.com/search?query")); // true

console.log(searchParams1.get("query")); // null
console.log(searchParams1.get("http://example.com/search?query")); // "@" (equivalent to decodeURIComponent('%40'))

const paramsString2 = "?query=value";
const searchParams2 = new URLSearchParams(paramsString2);
console.log(searchParams2.has("query")); // true

const url = new URL("http://example.com/search?query=%40");
const searchParams3 = new URLSearchParams(url.search);
console.log(searchParams3.has("query")); // true

Сохранение знаков плюс

Конструктор URLSearchParams интерпретирует знаки плюс (+) как пробелы, что может вызвать проблемы. В примере ниже мы используем шестнадцатеричные escape-последовательности для имитации строки, содержащей двоичные данные (где каждый байт несет информацию), которые необходимо сохранить в параметрах запроса URL. Обратите внимание, как закодированная строка, созданная btoa(), содержит + и не сохраняется URLSearchParams.

const rawData = "\x13à\x17@\x1F\x80";
const base64Data = btoa(rawData); // 'E+AXQB+A'

const searchParams = new URLSearchParams(`bin=${base64Data}`); // 'bin=E+AXQB+A'
const binQuery = searchParams.get("bin"); // 'E AXQB A', '+' is replaced by spaces

console.log(atob(binQuery) === rawData); // false

Вы можете избежать этого, закодировав данные с помощью encodeURIComponent().

const rawData = "\x13à\x17@\x1F\x80";
const base64Data = btoa(rawData); // 'E+AXQB+A'
const encodedBase64Data = encodeURIComponent(base64Data); // 'E%2BAXQB%2BA'

const searchParams = new URLSearchParams(`bin=${encodedBase64Data}`); // 'bin=E%2BAXQB%2BA'
const binQuery = searchParams.get("bin"); // 'E+AXQB+A'

console.log(atob(binQuery) === rawData); // true

Пустое значение против отсутствия значения

URLSearchParams не различает параметр без чего-либо после =, и параметр без = вообще.

const emptyVal = new URLSearchParams("foo=&bar=baz");
console.log(emptyVal.get("foo")); // returns ''
const noEquals = new URLSearchParams("foo&bar=baz");
console.log(noEquals.get("foo")); // also returns ''
console.log(noEquals.toString()); // 'foo=&bar=baz'

Спецификации

Спецификация
URL # urlsearchparams

Совместимость браузеров

	Настольные					Мобильные
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox for Android	Opera Android	Safari on IOS	Samsung Internet	WebView Android
`@@iterator`	49	17	44	36	10.1	49	44	36	10.3	5.0	49
`URLSearchParams`	49	17	29	36	10.1	49	29	36	10.3	5.0	49
`URLSearchParams`	49	17	29 До версии 57 одиночные кавычки в URL кодировались (см. bug 1386683).	36	10.1	49	29 До версии 57 одиночные кавычки в URL кодировались (см. bug 1386683).	36	10.3	5.0	49
`append`	49	17	29	36	10.1	49	29	36	10.3	5.0	49
`delete`	49	17	29	36	14 10.1 Удаление несуществующего параметра запроса не удаляет `?` из URL. См. bug 193022.	49	29	36	14 10.3 Удаление несуществующего параметра запроса не удаляет `?` из URL. См. bug 193022.	5.0	49
`entries`	49	17	44	36	10.1	49	44	36	10.3	5.0	49
`forEach`	49	17	44	36	10.1	49	44	36	10.3	5.0	49
`get`	49	17	29	36	10.1	49	29	36	10.3	5.0	49
`getAll`	49	17	29	36	10.1	49	29	36	10.3	5.0	49
`has`	49	17	29	36	10.1	49	29	36	10.3	5.0	49
`keys`	49	17	44	36	10.1	49	44	36	10.3	5.0	49
`set`	49	17	29	36	10.1	49	29	36	10.3	5.0	49
`size`	113	113	112	99	17	113	112	76	17	23.0	113
`sort`	61	17	54	48	11	61	54	45	11	8.0	61
`toString`	49	17	29	36	10.1	49	29	36	10.3	5.0	49
`values`	49	17	44	36	10.1	49	44	36	10.3	5.0	49

См. также

Полифилл URLSearchParams в core-js
Интерфейс URL.
Google Developers: Easy URL manipulation with URLSearchParams

© 2005–2024 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams