url.format(urlObject)
稳定性: 3 - 旧版: 改为使用 WHATWG URL API 。
url.format()
方法返回从 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
。
格式化过程如下:
- 创建新的空字符串
result
。 - 如果
urlObject.protocol
是字符串,则按原样附加到result
。 - 否则,如果
urlObject.protocol
不是undefined
并且不是字符串,则抛出Error
。 - 对于所有不以 ASCII 冒号(
:
)字符结尾的urlObject.protocol
字符串值,文字字符串:
将附加到result
。 - 如果以下任一条件为真,则文字串
//
将附加到result
:urlObject.slashes
属性为真;urlObject.protocol
以http
、https
、ftp
、gopher
或file
开头;
- 如果
urlObject.auth
属性的值为真,并且urlObject.host
或urlObject.hostname
不是undefined
,则urlObject.auth
的值将被强制转换为字符串并附加到result
后跟文字串@
。 - 如果
urlObject.host
属性为undefined
,则:- 如果
urlObject.hostname
是字符串,则将其附加到result
。 - 否则,如果
urlObject.hostname
不是undefined
并且不是字符串,则抛出Error
。 - 如果
urlObject.port
属性值为真,而urlObject.hostname
不是undefined
:- 字面量字符串
:
附加到result
,并且 urlObject.port
的值被强制转换为字符串并附加到result
。
- 字面量字符串
- 如果
- 否则,如果
urlObject.host
属性值为真,则将urlObject.host
的值强制转换为字符串并附加到result
。 - 如果
urlObject.pathname
属性是非空的字符串:- 如果
urlObject.pathname
不以 ASCII 正斜杠 (/
) 开头,则文本字符串'/'
将附加到result
。 urlObject.pathname
的值附加到result
。
- 如果
- 否则,如果
urlObject.pathname
不是undefined
并且不是字符串,则抛出Error
。 - 如果
urlObject.search
属性是undefined
并且如果urlObject.query
属性是Object
,则文字串?
附加到result
,然后是调用querystring
模块的stringify()
方法的输出,并传入urlObject.query
的值。 - 否则,如果
urlObject.search
是一个字符串:- 如果
urlObject.search
的值不以 ASCII 问号 (?
) 字符开头,则文本字符串?
附加到result
。 urlObject.search
的值附加到result
。
- 如果
- 否则,如果
urlObject.search
不是undefined
并且不是字符串,则抛出Error
。 - 如果
urlObject.hash
属性是字符串:- 如果
urlObject.hash
的值不以 ASCII 散列 (#
) 字符开头,则文本字符串#
将附加到result
。 urlObject.hash
的值附加到result
。
- 如果
- 否则,如果
urlObject.hash
属性不是undefined
并且不是字符串,则抛出Error
。 result
返回。
Stability: 3 - Legacy: Use the WHATWG URL API instead.
urlObject
<Object> | <string> A URL object (as returned byurl.parse()
or constructed otherwise). If a string, it is converted to an object by passing it tourl.parse()
.
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'
If urlObject
is not an object or a string, url.format()
will throw a
TypeError
.
The formatting process operates as follows:
- A new empty string
result
is created. - If
urlObject.protocol
is a string, it is appended as-is toresult
. - Otherwise, if
urlObject.protocol
is notundefined
and is not a string, anError
is thrown. - For all string values of
urlObject.protocol
that do not end with an ASCII colon (:
) character, the literal string:
will be appended toresult
. - If either of the following conditions is true, then the literal string
//
will be appended toresult
:urlObject.slashes
property is true;urlObject.protocol
begins withhttp
,https
,ftp
,gopher
, orfile
;
- If the value of the
urlObject.auth
property is truthy, and eitherurlObject.host
orurlObject.hostname
are notundefined
, the value ofurlObject.auth
will be coerced into a string and appended toresult
followed by the literal string@
. - If the
urlObject.host
property isundefined
then:- If the
urlObject.hostname
is a string, it is appended toresult
. - Otherwise, if
urlObject.hostname
is notundefined
and is not a string, anError
is thrown. - If the
urlObject.port
property value is truthy, andurlObject.hostname
is notundefined
:- The literal string
:
is appended toresult
, and - The value of
urlObject.port
is coerced to a string and appended toresult
.
- The literal string
- If the
- Otherwise, if the
urlObject.host
property value is truthy, the value ofurlObject.host
is coerced to a string and appended toresult
. - If the
urlObject.pathname
property is a string that is not an empty string:- If the
urlObject.pathname
does not start with an ASCII forward slash (/
), then the literal string'/'
is appended toresult
. - The value of
urlObject.pathname
is appended toresult
.
- If the
- Otherwise, if
urlObject.pathname
is notundefined
and is not a string, anError
is thrown. - If the
urlObject.search
property isundefined
and if theurlObject.query
property is anObject
, the literal string?
is appended toresult
followed by the output of calling thequerystring
module'sstringify()
method passing the value ofurlObject.query
. - Otherwise, if
urlObject.search
is a string:- If the value of
urlObject.search
does not start with the ASCII question mark (?
) character, the literal string?
is appended toresult
. - The value of
urlObject.search
is appended toresult
.
- If the value of
- Otherwise, if
urlObject.search
is notundefined
and is not a string, anError
is thrown. - If the
urlObject.hash
property is a string:- If the value of
urlObject.hash
does not start with the ASCII hash (#
) character, the literal string#
is appended toresult
. - The value of
urlObject.hash
is appended toresult
.
- If the value of
- Otherwise, if the
urlObject.hash
property is notundefined
and is not a string, anError
is thrown. result
is returned.