Query String

• querystring.escape(str)
• querystring.parse(str[, sep[, eq[, options]]])
• querystring.stringify(obj[, sep[, eq[, options]]])
• querystring.unescape(str)

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

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

const querystring = require('querystring');

querystring.escape(str)

• str <Строка>

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

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

querystring.parse (strp[, sep[, eqp[, options]]])

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

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

Например, строка запроса 'foo=bar&abc=xyz&abc=123' парсится в:

{
  foo: 'bar',
  abc: ['xyz', '123']
}

Примечание: объект, возвращаемый методом querystring.parse() не вырастает прототипично из Object JavaScript. Это означает, что типичные методы 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]]])

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

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

Пример:

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)

• str <Строка>

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

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

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