url.format(urlObject)

• urlObject <Object> | <string> 网址对象（由 url.parse() 返回或以其他方式构造）。如果是字符串，则通过将其传给 url.parse() 将其转换为对象。

  ¥urlObject <Object> | <string> A URL object (as returned by url.parse() or constructed otherwise). If a string, it is converted to an object by passing it to url.parse().

url.format() 方法返回从 urlObject 派生的格式化网址字符串。

¥The url.format() method returns a formatted URL string derived from urlObject.

const url = require('node:url');
url.format({
  protocol: 'https',
  hostname: 'example.com',
  pathname: '/some/path',
  query: {
    page: 1,
    format: 'json',
  },
});

// => 'https://example.com/some/path?page=1&format=json' 拷贝

如果 urlObject 不是对象或字符串，则 url.format() 将抛出 TypeError。

¥If urlObject is not an object or a string, url.format() will throw a TypeError.

格式化过程如下：

¥The formatting process operates as follows:

• 创建新的空字符串 result。

  ¥A new empty string result is created.

• 如果 urlObject.protocol 是字符串，则按原样附加到 result。

  ¥If urlObject.protocol is a string, it is appended as-is to result.

• 否则，如果 urlObject.protocol 不是 undefined 并且不是字符串，则抛出 Error。

  ¥Otherwise, if urlObject.protocol is not undefined and is not a string, an Error is thrown.

• 对于不以 ASCII 冒号 (:) 字符结尾的 urlObject.protocol 的所有字符串值，字面字符串 : 将附加到 result。

  ¥For all string values of urlObject.protocol that do not end with an ASCII colon (:) character, the literal string : will be appended to result.

• 如果以下任一条件为真，则字面字符串 // 将附加到 result：

  ¥If either of the following conditions is true, then the literal string // will be appended to result:

  • urlObject.slashes 属性为真；

    ¥urlObject.slashes property is true;

  • urlObject.protocol 以 http、https、ftp、gopher 或 file 开头；

    ¥urlObject.protocol begins with http, https, ftp, gopher, or file;

• 如果 urlObject.auth 属性的值为真，并且 urlObject.host 或 urlObject.hostname 不是 undefined，则 urlObject.auth 的值将被强制转换为字符串并附加到 result 后跟字面串 @。

  ¥If the value of the urlObject.auth property is truthy, and either urlObject.host or urlObject.hostname are not undefined, the value of urlObject.auth will be coerced into a string and appended to result followed by the literal string @.

• 如果 urlObject.host 属性为 undefined，则：

  ¥If the urlObject.host property is undefined then:

  • 如果 urlObject.hostname 是字符串，则将其附加到 result。

    ¥If the urlObject.hostname is a string, it is appended to result.

  • 否则，如果 urlObject.hostname 不是 undefined 并且不是字符串，则抛出 Error。

    ¥Otherwise, if urlObject.hostname is not undefined and is not a string, an Error is thrown.

  • 如果 urlObject.port 属性值为真，并且 urlObject.hostname 不是 undefined：

    ¥If the urlObject.port property value is truthy, and urlObject.hostname is not undefined:

    • 字面量字符串 : 附加到 result，并且

      ¥The literal string : is appended to result, and

    • urlObject.port 的值被强制转换为字符串并附加到 result。

      ¥The value of urlObject.port is coerced to a string and appended to result.

• 否则，如果 urlObject.host 属性值为真，则将 urlObject.host 的值强制转换为字符串并附加到 result。

  ¥Otherwise, if the urlObject.host property value is truthy, the value of urlObject.host is coerced to a string and appended to result.

• 如果 urlObject.pathname 属性是非空的字符串：

  ¥If the urlObject.pathname property is a string that is not an empty string:

  • 如果 urlObject.pathname 不以 ASCII 正斜杠 (/) 开头，则将字面字符串 '/' 附加到 result。

    ¥If the urlObject.pathname does not start with an ASCII forward slash (/), then the literal string '/' is appended to result.

  • urlObject.pathname 的值附加到 result。

    ¥The value of urlObject.pathname is appended to result.

• 否则，如果 urlObject.pathname 不是 undefined 并且不是字符串，则抛出 Error。

  ¥Otherwise, if urlObject.pathname is not undefined and is not a string, an Error is thrown.

• 如果 urlObject.search 属性是 undefined 并且如果 urlObject.query 属性是 Object，则字面串 ? 附加到 result，然后是调用 querystring 模块的 stringify() 方法的输出，并传入 urlObject.query 的值。

  ¥If the urlObject.search property is undefined and if the urlObject.query property is an Object, the literal string ? is appended to result followed by the output of calling the querystring module's stringify() method passing the value of urlObject.query.

• 否则，如果 urlObject.search 是一个字符串：

  ¥Otherwise, if urlObject.search is a string:

  • 如果 urlObject.search 的值不以 ASCII 问号 (?) 字符开头，则将字面字符串 ? 附加到 result。

    ¥If the value of urlObject.search does not start with the ASCII question mark (?) character, the literal string ? is appended to result.

  • urlObject.search 的值附加到 result。

    ¥The value of urlObject.search is appended to result.

• 否则，如果 urlObject.search 不是 undefined 并且不是字符串，则抛出 Error。

  ¥Otherwise, if urlObject.search is not undefined and is not a string, an Error is thrown.

• 如果 urlObject.hash 属性是字符串：

  ¥If the urlObject.hash property is a string:

  • 如果 urlObject.hash 的值不以 ASCII 散列 (#) 字符开头，则将字面字符串 # 附加到 result。

    ¥If the value of urlObject.hash does not start with the ASCII hash (#) character, the literal string # is appended to result.

  • urlObject.hash 的值附加到 result。

    ¥The value of urlObject.hash is appended to result.

• 否则，如果 urlObject.hash 属性不是 undefined 并且不是字符串，则抛出 Error。

  ¥Otherwise, if the urlObject.hash property is not undefined and is not a string, an Error is thrown.

• result 返回。

  ¥result is returned.