Cadena de consulta

[Estable: 2 - Estable]

Estable: 2 Estabilidad: 2 - Estable

Código fuente: lib/querystring.js

El módulo node:querystring proporciona utilidades para analizar y formatear cadenas de consulta de URL. Se puede acceder utilizando:

const querystring = require('node:querystring')

querystring es más eficiente que <URLSearchParams>, pero no es una API estandarizada. Utilice <URLSearchParams> cuando el rendimiento no sea crítico o cuando sea deseable la compatibilidad con el código del navegador.

querystring.decode()

Añadido en: v0.1.99

La función querystring.decode() es un alias de querystring.parse().

querystring.encode()

Añadido en: v0.1.99

La función querystring.encode() es un alias de querystring.stringify().

querystring.escape(str)

Añadido en: v0.1.25

• str <string>

El método querystring.escape() realiza la codificación de porcentaje de URL en la str dada de una manera que está optimizada para los requisitos específicos de las cadenas de consulta de URL.

El método querystring.escape() es utilizado por querystring.stringify() y generalmente no se espera que se utilice directamente. Se exporta principalmente para permitir que el código de la aplicación proporcione una implementación de codificación de porcentaje de reemplazo si es necesario asignando querystring.escape a una función alternativa.

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

[Historial]

Versión	Cambios
v8.0.0	Ahora se analizan correctamente múltiples entradas vacías (p. ej., &=&=).
v6.0.0	El objeto devuelto ya no hereda de Object.prototype.
v6.0.0, v4.2.4	El parámetro eq ahora puede tener una longitud superior a 1.
v0.1.25	Añadido en: v0.1.25

• str <string> La cadena de consulta de URL para analizar
• sep <string> La subcadena utilizada para delimitar los pares clave-valor en la cadena de consulta. Predeterminado: '&'.
• eq <string>. La subcadena utilizada para delimitar las claves y los valores en la cadena de consulta. Predeterminado: '='.
• options <Object>
  • decodeURIComponent <Function> La función que se utilizará al decodificar caracteres codificados por porcentaje en la cadena de consulta. Predeterminado: querystring.unescape().
  • maxKeys <number> Especifica el número máximo de claves que se analizarán. Especifique 0 para eliminar las limitaciones de conteo de claves. Predeterminado: 1000.

El método querystring.parse() analiza una cadena de consulta de URL (str) en una colección de pares clave-valor.

Por ejemplo, la cadena de consulta 'foo=bar&abc=xyz&abc=123' se analiza en:

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

El objeto devuelto por el método querystring.parse() no hereda prototípicamente del Object de JavaScript. Esto significa que los métodos típicos de Object, como obj.toString(), obj.hasOwnProperty() y otros, no están definidos y no funcionarán.

De forma predeterminada, se supondrá que los caracteres codificados por porcentaje dentro de la cadena de consulta usan la codificación UTF-8. Si se usa una codificación de caracteres alternativa, será necesario especificar una opción decodeURIComponent alternativa:

// Suponiendo que la función gbkDecodeURIComponent ya existe...

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

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

Añadido en: v0.1.25

• obj <Object> El objeto a serializar en una cadena de consulta URL
• sep <string> La subcadena utilizada para delimitar los pares clave y valor en la cadena de consulta. Predeterminado: '&'.
• eq <string>. La subcadena utilizada para delimitar claves y valores en la cadena de consulta. Predeterminado: '='.
• options
  • encodeURIComponent <Function> La función a usar al convertir caracteres no seguros para URL a codificación de porcentaje en la cadena de consulta. Predeterminado: querystring.escape().

El método querystring.stringify() produce una cadena de consulta URL a partir de un obj dado iterando a través de las "propiedades propias" del objeto.

Serializa los siguientes tipos de valores pasados en obj: <string> | <number> | <bigint> | <boolean> | <string[]> | <number[]> | <bigint[]> | <boolean[]> Los valores numéricos deben ser finitos. Cualquier otro valor de entrada se convertirá en cadenas vacías.

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

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

De forma predeterminada, los caracteres que requieren codificación de porcentaje dentro de la cadena de consulta se codificarán como UTF-8. Si se requiere una codificación alternativa, se deberá especificar una opción alternativa encodeURIComponent:

// Asumiendo que la función gbkEncodeURIComponent ya existe,

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

querystring.unescape(str)

Agregado en: v0.1.25

• str <string>

El método querystring.unescape() realiza la decodificación de caracteres codificados en porcentaje de URL en la str dada.

El método querystring.unescape() es utilizado por querystring.parse() y generalmente no se espera que se use directamente. Se exporta principalmente para permitir que el código de la aplicación proporcione una implementación de decodificación de reemplazo si es necesario asignando querystring.unescape a una función alternativa.

De forma predeterminada, el método querystring.unescape() intentará utilizar el método decodeURIComponent() incorporado de JavaScript para decodificar. Si eso falla, se utilizará un equivalente más seguro que no genera errores en las URL con formato incorrecto.