Строка запроса

Модуль node:querystring предоставляет утилиты для разбора и форматирования строк запроса URL. К нему можно получить доступ с помощью:

const querystring = require('node:querystring');
jscopy

querystring производительнее, чем <URLSearchParams>, но не является стандартизированным API. Используйте <URLSearchParams>, если производительность не критична или желательна совместимость с кодом браузера.

querystring.decode()

Функция querystring.decode() является псевдонимом для querystring.parse().

querystring.encode()

Функция querystring.encode() является псевдонимом для querystring.stringify().

querystring.escape(str)

• str <string>

Метод querystring.escape() выполняет процентное кодирование URL для заданной str с учетом особых требований строк запроса URL.

Метод querystring.escape() используется функцией querystring.stringify() и обычно не предназначен для непосредственного использования. Он экспортируется главным образом для того, чтобы при необходимости код приложения мог предоставить собственную реализацию процентного кодирования, присвоив querystring.escape альтернативную функцию.

querystring.parse(str[, sep[, eq[, options]]])

• str <string> Строка запроса URL для разбора
• sep <string> Подстрока, используемая для разделения пар ключ-значение в строке запроса. По умолчанию: '&'.
• eq <string>. Подстрока, используемая для разделения ключей и значений в строке запроса. По умолчанию: '='.
• options <Object>
  • decodeURIComponent <Function> Функция, используемая для декодирования символов с процентным кодированием в строке запроса. По умолчанию: querystring.unescape().
  • maxKeys <number> Задает максимальное число ключей для разбора. Укажите 0, чтобы снять ограничения на подсчет ключей. По умолчанию: 1000.

Метод querystring.parse() разбирает строку запроса URL (str) в набор пар ключ-значение.

Например, строка запроса 'foo=bar&abc=xyz&abc=123' разбирается следующим образом:

{
  "foo": "bar",
  "abc": ["xyz", "123"]
}
jsoncopy

Объект, возвращаемый методом querystring.parse(), не наследуется по цепочке прототипов от JavaScript-объекта Object. Это означает, что стандартные методы Object, такие как obj.toString(), obj.hasOwnProperty() и другие, не определены и не будут работать.

По умолчанию предполагается, что символы с процентным кодированием в строке запроса используют кодировку UTF-8. Если используется другая кодировка символов, необходимо указать альтернативный параметр decodeURIComponent:

// Assuming gbkDecodeURIComponent function already exists...

querystring.parse('w=%D6%D0%CE%C4&foo=bar', null, null,
                  { decodeURIComponent: gbkDecodeURIComponent });
jscopy

querystring.stringify(obj[, sep[, eq[, options]]])

• obj <Object> Объект для сериализации в строку запроса URL
• sep <string> Подстрока, используемая для разделения пар ключ-значение в строке запроса. По умолчанию: '&'.
• eq <string>. Подстрока, используемая для разделения ключей и значений в строке запроса. По умолчанию: '='.
• options
  • encodeURIComponent <Function> Функция, используемая для преобразования символов, небезопасных для URL, в символы с процентным кодированием в строке запроса. По умолчанию: querystring.escape().

Метод querystring.stringify() создает строку запроса URL из заданного obj, перебирая «собственные свойства» объекта.

Он сериализует следующие типы значений, переданных в obj: <string> | <number> | <bigint> | <boolean> | <string[]> | <number[]> | <bigint[]> | <boolean[]>. Числовые значения должны быть конечными. Любые другие входные значения будут преобразованы в пустые строки.

querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' });
// Returns 'foo=bar&baz=qux&baz=quux&corge='

querystring.stringify({ foo: 'bar', baz: 'qux' }, ';', ':');
// Returns 'foo:bar;baz:qux'
jscopy

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

// Assuming gbkEncodeURIComponent function already exists,

querystring.stringify({ w: '中文', foo: 'bar' }, null, null,
                      { encodeURIComponent: gbkEncodeURIComponent });
jscopy

querystring.unescape(str)

• str <string>

Метод querystring.unescape() выполняет декодирование символов URL с процентным кодированием в заданной str.

Метод querystring.unescape() используется функцией querystring.parse() и обычно не предназначен для непосредственного использования. Он экспортируется главным образом для того, чтобы при необходимости код приложения мог предоставить собственную реализацию декодирования, присвоив querystring.unescape альтернативную функцию.

По умолчанию метод querystring.unescape() пытается использовать встроенный метод JavaScript decodeURIComponent() для декодирования. Если это не удается, используется более безопасный эквивалент, который не вызывает исключение при некорректных URL.