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

[Стабильно: 2 - Стабильно]

Стабильно: 2 Стабильность: 2 - Стабильно

Исходный код: lib/querystring.js

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

const querystring = require('node:querystring')

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

querystring.decode()

Добавлено в: v0.1.99

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

querystring.encode()

Добавлено в: v0.1.99

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

querystring.escape(str)

Добавлено в: v0.1.25

• str <string>

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

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

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

[История]

Версия	Изменения
v8.0.0	Теперь правильно разбираются несколько пустых записей (например, &=&=).
v6.0.0	Возвращаемый объект больше не наследуется от Object.prototype.
v6.0.0, v4.2.4	Параметр eq теперь может иметь длину больше 1.
v0.1.25	Добавлено в: v0.1.25

• 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"]
}

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

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

// Предполагая, что функция gbkDecodeURIComponent уже существует...

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

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

Добавлено в: v0.1.25

• 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: '' })
// Возвращает 'foo=bar&baz=qux&baz=quux&corge='

querystring.stringify({ foo: 'bar', baz: 'qux' }, ';', ':')
// Возвращает 'foo:bar;baz:qux'

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

// Предполагается, что функция gbkEncodeURIComponent уже существует,

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

querystring.unescape(str)

Добавлено в: v0.1.25

• str <строка>

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

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

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