Node.js v21.7.2 文件

querystring.decode()#

querystring.decode() 函式是 querystring.parse() 的別名。

querystring.encode()#

querystring.encode() 函式是 querystring.stringify() 的別名。

querystring.escape(str)#

• str <字串>

querystring.escape() 方法對指定的 str 執行 URL 百分比編碼，其方式針對 URL 查詢字串的特定需求進行最佳化。

querystring.escape() 方法由 querystring.stringify() 使用，通常不會直接使用。它主要用於允許應用程式碼提供替代的百分比編碼實作（如果需要），方法是將 querystring.escape 指派給替代函式。

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

• str <字串> 要解析的 URL 查詢字串
• sep <字串> 用於在查詢字串中區分鍵值對的子字串。預設值： '&'。
• eq <字串> 用於在查詢字串中區分鍵和值的子字串。預設值： '='。
• options <物件>
  • decodeURIComponent <函式> 在查詢字串中解碼百分比編碼字元時要使用的函式。預設值： querystring.unescape()。
  • maxKeys <number> 指定要解析的最大金鑰數。指定 0 以移除金鑰計數限制。預設值：1000。

querystring.parse() 方法會將 URL 查詢字串 (str) 解析成金鑰和值配對的集合。

例如，查詢字串 'foo=bar&abc=xyz&abc=123' 會解析成

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

querystring.parse() 方法傳回的物件不會從 JavaScript Object 原型繼承。這表示典型的 Object 方法，例如 obj.toString()、obj.hasOwnProperty() 等，並未定義，且無法運作。

預設情況下，查詢字串中的百分比編碼字元會假設使用 UTF-8 編碼。如果使用其他字元編碼，則需要指定其他 decodeURIComponent 選項

// Assuming gbkDecodeURIComponent function already exists...

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

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

• obj <Object> 要序列化成 URL 查詢字串的物件
• sep <字串> 用於在查詢字串中區分鍵值對的子字串。預設值： '&'。
• eq <字串> 用於在查詢字串中區分鍵和值的子字串。預設值： '='。
• options
  • encodeURIComponent <Function> 在查詢字串中將 URL 不安全的字元轉換為百分比編碼時要使用的函式。預設值：querystring.escape()。

querystring.stringify() 方法會透過反覆處理物件的「自有屬性」來產生給定 obj 的 URL 查詢字串。

它會序列化傳入 obj 的下列類型值：<string> | <number> | <bigint> | <boolean> | <string[]> | <number[]> | <bigint[]> | <boolean[]> 數值必須是有限的。任何其他輸入值都將轉換為空字串。

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' copy

預設情況下，查詢字串中需要百分比編碼的字元會編碼為 UTF-8。如果需要其他編碼，則需要指定其他 encodeURIComponent 選項

// Assuming gbkEncodeURIComponent function already exists,

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

querystring.unescape(str)#

• str <字串>

querystring.unescape() 方法對給定的 str 上的 URL 百分比編碼字元執行解碼。

querystring.unescape() 方法由 querystring.parse() 使用，一般預期不會直接使用。它主要用於讓應用程式程式碼提供替代解碼實作，必要時可將 querystring.unescape 指定給替代函式。

預設情況下，querystring.unescape() 方法會嘗試使用 JavaScript 內建的 decodeURIComponent() 方法來解碼。如果失敗，將會使用一個更安全的等效方法，不會對格式錯誤的 URL 擲回例外。