Stringa de consulta

[Estável: 2 - Estável]

Estável: 2 Estabilidade: 2 - Estável

Código-fonte: lib/querystring.js

O módulo node:querystring fornece utilitários para analisar e formatar strings de consulta de URL. Ele pode ser acessado usando:

const querystring = require('node:querystring')

querystring tem melhor desempenho do que <URLSearchParams>, mas não é uma API padronizada. Use <URLSearchParams> quando o desempenho não for crítico ou quando a compatibilidade com código do navegador for desejável.

querystring.decode()

Adicionado em: v0.1.99

A função querystring.decode() é um alias para querystring.parse().

querystring.encode()

Adicionado em: v0.1.99

A função querystring.encode() é um alias para querystring.stringify().

querystring.escape(str)

Adicionado em: v0.1.25

• str <string>

O método querystring.escape() realiza a codificação percentual de URL na str fornecida de uma maneira otimizada para os requisitos específicos das strings de consulta de URL.

O método querystring.escape() é usado por querystring.stringify() e geralmente não se espera que seja usado diretamente. Ele é exportado principalmente para permitir que o código do aplicativo forneça uma implementação de codificação percentual alternativa, se necessário, atribuindo querystring.escape a uma função alternativa.

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

[Histórico]

Versão	Alterações
v8.0.0	Múltiplas entradas vazias agora são analisadas corretamente (por exemplo, &=&=).
v6.0.0	O objeto retornado não herda mais de Object.prototype.
v6.0.0, v4.2.4	O parâmetro eq agora pode ter um comprimento maior que 1.
v0.1.25	Adicionada em: v0.1.25

• str <string> A string de consulta de URL a ser analisada
• sep <string> A substring usada para delimitar pares chave-valor na string de consulta. Padrão: '&'.
• eq <string>. A substring usada para delimitar chaves e valores na string de consulta. Padrão: '='.
• options <Object>
  • decodeURIComponent <Function> A função a ser usada ao decodificar caracteres codificados por percentagem na string de consulta. Padrão: querystring.unescape().
  • maxKeys <number> Especifica o número máximo de chaves a serem analisadas. Especifique 0 para remover as limitações de contagem de chaves. Padrão: 1000.

O método querystring.parse() analisa uma string de consulta de URL (str) em uma coleção de pares chave-valor.

Por exemplo, a string de consulta 'foo=bar&abc=xyz&abc=123' é analisada em:

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

O objeto retornado pelo método querystring.parse() não herda prototipicamente do JavaScript Object. Isso significa que os métodos Object típicos, como obj.toString(), obj.hasOwnProperty() e outros não estão definidos e não funcionarão.

Por padrão, os caracteres codificados por percentagem na string de consulta serão considerados como usando codificação UTF-8. Se uma codificação de caracteres alternativa for usada, uma opção decodeURIComponent alternativa precisará ser especificada:

// Supondo que a função gbkDecodeURIComponent já exista...

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

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

Adicionado em: v0.1.25

• obj <Object> O objeto a ser serializado em uma string de consulta de URL
• sep <string> A substring usada para delimitar pares chave-valor na string de consulta. Padrão: '&'.
• eq <string>. A substring usada para delimitar chaves e valores na string de consulta. Padrão: '='.
• options
  • encodeURIComponent <Function> A função a ser usada ao converter caracteres inseguros para URL em codificação percentual na string de consulta. Padrão: querystring.escape().

O método querystring.stringify() produz uma string de consulta de URL a partir de um obj dado, iterando pelas "propriedades próprias" do objeto.

Ele serializa os seguintes tipos de valores passados em obj: <string> | <number> | <bigint> | <boolean> | <string[]> | <number[]> | <bigint[]> | <boolean[]> Os valores numéricos devem ser finitos. Quaisquer outros valores de entrada serão convertidos em strings vazias.

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

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

Por padrão, os caracteres que exigem codificação percentual na string de consulta serão codificados como UTF-8. Se for necessária uma codificação alternativa, será necessário especificar uma opção encodeURIComponent alternativa:

// Assumindo que a função gbkEncodeURIComponent já exista,

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

querystring.unescape(str)

Adicionado em: v0.1.25

• str <string>

O método querystring.unescape() executa a decodificação de caracteres percentualmente codificados em URL na string str fornecida.

O método querystring.unescape() é usado por querystring.parse() e geralmente não se espera que seja usado diretamente. Ele é exportado principalmente para permitir que o código do aplicativo forneça uma implementação de decodificação alternativa, se necessário, atribuindo querystring.unescape a uma função alternativa.

Por padrão, o método querystring.unescape() tentará usar o método decodeURIComponent() integrado ao JavaScript para decodificar. Se isso falhar, será usado um equivalente mais seguro que não lança exceções em URLs malformadas.