Перейти к содержанию

Модуль querystring

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

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

const querystring = require('querystring');

querystring.escape()

querystring.escape(str)
  • str <Строка>

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

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

querystring.parse()

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()

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()

querystring.unescape(str)
  • str <Строка>

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

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

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