Node.js v24.13.0 文档

querystring.decode()#>

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

【The querystring.decode() function is an alias for querystring.parse().】

querystring.encode()#>

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

【The querystring.encode() function is an alias for querystring.stringify().】

querystring.escape(str)#>

• str <string>

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

【The querystring.escape() method performs URL percent-encoding on the given str in a manner that is optimized for the specific requirements of URL query strings.】

querystring.escape() 方法被 querystring.stringify() 使用，通常不期望直接使用它。它之所以被导出，主要是为了允许应用代码在必要时通过将 querystring.escape 指定为其他函数来提供替代的百分比编码实现。

【The querystring.escape() method is used by querystring.stringify() and is generally not expected to be used directly. It is exported primarily to allow application code to provide a replacement percent-encoding implementation if necessary by assigning querystring.escape to an alternative function.】

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

• str <string> 要解析的 URL 查询字符串
• sep <string> 用于分隔查询字符串中键值对的子字符串。默认值： '&'。
• eq <string>。用于在查询字符串中分隔键和值的子字符串。默认值： '='。
• options <Object>
  • decodeURIComponent <Function> 用于解码查询字符串中百分比编码字符的函数。默认值： querystring.unescape()。
  • maxKeys <number> 指定要解析的最大键数。指定 0 可取消键计数限制。默认值： 1000。

querystring.parse() 方法将 URL 查询字符串（str）解析成一组键值对。

【The querystring.parse() method parses a URL query string (str) into a collection of key and value pairs.】

例如，查询字符串 'foo=bar&abc=xyz&abc=123' 被解析为：

【For example, the query string 'foo=bar&abc=xyz&abc=123' is parsed into:】

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

querystring.parse() 方法返回的对象不会从 JavaScript 的 Object 原型继承。这意味着像 obj.toString()、obj.hasOwnProperty() 等典型的 Object 方法未定义，并且无法使用。

【The object returned by the querystring.parse() method does not prototypically inherit from the JavaScript Object. This means that typical Object methods such as obj.toString(), obj.hasOwnProperty(), and others are not defined and will not work.】

默认情况下，查询字符串中的百分号编码字符将被假定使用 UTF-8 编码。如果使用了其他字符编码，则需要指定一个替代的 decodeURIComponent 选项：

【By default, percent-encoded characters within the query string will be assumed to use UTF-8 encoding. If an alternative character encoding is used, then an alternative decodeURIComponent option will need to be specified:】

// Assuming gbkDecodeURIComponent function already exists...

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

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

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

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

【The querystring.stringify() method produces a URL query string from a given obj by iterating through the object's "own properties".】

它会序列化传入 obj 的以下类型的值： <string> | <number> | <bigint> | <boolean> | <string[]> | <number[]> | <bigint[]> | <boolean[]> 数值必须是有限的。任何其他输入值都会被强制转换为空字符串。

【It serializes the following types of values passed in obj: <string> | <number> | <bigint> | <boolean> | <string[]> | <number[]> | <bigint[]> | <boolean[]> The numeric values must be finite. Any other input values will be coerced to empty strings.】

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

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

默认情况下，查询字符串中需要进行百分比编码的字符将会以 UTF-8 编码。如果需要使用其他编码，则需要指定一个替代的 encodeURIComponent 选项：

【By default, characters requiring percent-encoding within the query string will be encoded as UTF-8. If an alternative encoding is required, then an alternative encodeURIComponent option will need to be specified:】

// Assuming gbkEncodeURIComponent function already exists,

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

querystring.unescape(str)#>

• str <string>

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

【The querystring.unescape() method performs decoding of URL percent-encoded characters on the given str.】

querystring.unescape() 方法由 querystring.parse() 使用，通常不建议直接使用它。它之所以被导出，主要是为了在必要时允许应用代码通过将 querystring.unescape 指定为其他函数来提供替代的解码实现。

【The querystring.unescape() method is used by querystring.parse() and is generally not expected to be used directly. It is exported primarily to allow application code to provide a replacement decoding implementation if necessary by assigning querystring.unescape to an alternative function.】

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

【By default, the querystring.unescape() method will attempt to use the JavaScript built-in decodeURIComponent() method to decode. If that fails, a safer equivalent that does not throw on malformed URLs will be used.】