Node.js v18.15.0 文档


目录

querystring 查询字符串#

中英对照

稳定性: 2 - 稳定

源代码: lib/querystring.js

node:querystring 模块提供了用于解析和格式化网址查询字符串的实用工具。 可以使用以下方式访问它:

const querystring = require('node:querystring');

querystring<URLSearchParams> 性能更高,但不是标准化的 API。 当性能不重要或需要与浏览器代码兼容时使用 <URLSearchParams>

querystring.decode()#

中英对照

querystring.decode() 函数是 querystring.parse() 的别名。

querystring.encode()#

中英对照

querystring.encode() 函数是 querystring.stringify() 的别名。

querystring.escape(str)#

中英对照

querystring.escape() 方法以针对网址查询字符串的特定要求优化的方式对给定的 str 执行网址百分比编码。

querystring.escape() 方法被 querystring.stringify() 使用,通常不会被直接使用。 导出它主要是为了允许应用程序代码在必要时通过将 querystring.escape 分配给替代函数来提供替换的百分比编码实现。

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

中英对照

  • str <string> 要解析的网址查询字符串
  • sep <string> 用于在查询字符串中分隔键值对的子字符串。 默认值: '&'
  • eq <string>用于在查询字符串中分隔键和值的子字符串。 默认值: '='
  • options <Object>
    • decodeURIComponent <Function> 当对查询字符串中的百分比编码字符进行解码时使用的函数。 默认值: querystring.unescape()
    • maxKeys <number> 指定要解析的最大键数。 指定 0 以删除键的计数限制。 默认值: 1000

querystring.parse() 方法将网址查询字符串 (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]]])#

中英对照

  • obj <Object> 要序列化为网址查询字符串的对象
  • sep <string> 用于在查询字符串中分隔键值对的子字符串。 默认值: '&'
  • eq <string>用于在查询字符串中分隔键和值的子字符串。 默认值: '='
  • options
    • encodeURIComponent <Function> 当将网址不安全的字符转换为查询字符串中的百分比编码时使用的函数。 默认值: querystring.escape()

querystring.stringify() 方法通过遍历对象的"自有属性"从给定的 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)#

中英对照

querystring.unescape() 方法在给定的 str 上执行网址百分比编码字符的解码。

querystring.unescape() 方法被 querystring.parse() 使用,通常不会被直接使用。 导出它主要是为了允许应用程序代码在必要时通过将 querystring.unescape 分配给替代函数来提供替代的解码实现。

默认情况下,querystring.unescape() 方法将尝试使用 JavaScript 内置的 decodeURIComponent() 方法进行解码。 如果失败,则将使用更安全的不会因格式错误的网址而抛出错误的同类方法。

返回顶部