查询字符串

稳定性：2 - 稳定

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

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

querystring 的性能优于 <URLSearchParams>，但它不是一个标准化的 API。当性能不是关键因素或需要与浏览器代码兼容时，请使用 <URLSearchParams>。

querystring.decode(): void

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

querystring.encode(): void

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

querystring.escape(str): void

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

querystring.escape() 方法由 querystring.stringify() 使用，通常不建议直接使用。导出它主要是为了允许应用程序代码在必要时通过将 querystring.escape 赋值给替代函数来提供替代的百分号编码实现。

querystring.parse(str, sep?, eq?, options?): void

querystring.parse() 方法将 URL 查询字符串（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?): void

querystring.stringify() 方法通过遍历对象的“自有属性”，从给定的 obj 生成 URL 查询字符串。

它序列化 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): void

querystring.unescape() 方法对给定的 str 执行 URL 百分号编码字符的解码。

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

默认情况下，querystring.unescape() 方法将尝试使用 JavaScript 内置的 decodeURIComponent() 方法进行解码。如果失败，将使用一个更安全的等效方法，该方法不会在 URL 格式错误时抛出异常。