- assert 断言
- async_hooks 异步钩子
- async_hooks/context 异步上下文
- buffer 缓冲区
- C++插件
- C/C++插件(使用 Node-API)
- C++嵌入器
- child_process 子进程
- cluster 集群
- CLI 命令行
- console 控制台
- Corepack 核心包
- crypto 加密
- crypto/webcrypto 网络加密
- debugger 调试器
- deprecation 弃用
- dgram 数据报
- diagnostics_channel 诊断通道
- dns 域名服务器
- domain 域
- Error 错误
- events 事件触发器
- fs 文件系统
- global 全局变量
- http 超文本传输协议
- http2 超文本传输协议 2.0
- https 安全超文本传输协议
- inspector 检查器
- Intl 国际化
- module 模块
- module/cjs CommonJS 模块
- module/esm ECMAScript 模块
- module/package 包模块
- net 网络
- os 操作系统
- path 路径
- perf_hooks 性能钩子
- permission 权限
- process 进程
- punycode 域名代码
- querystring 查询字符串
- readline 逐行读取
- repl 交互式解释器
- report 诊断报告
- sea 单个可执行应用程序
- stream 流
- stream/web 网络流
- string_decoder 字符串解码器
- test 测试
- timers 定时器
- tls 安全传输层
- trace_events 跟踪事件
- tty 终端
- url 网址
- util 实用工具
- v8 引擎
- vm 虚拟机
- wasi 网络汇编系统接口
- worker_threads 工作线程
- zlib 压缩
Node.js v18.20.0 文档
- Node.js v18.20.0
-
目录
- URL
- URL 字符串和 URL 对象
- WHATWG URL API
- 类:
URL
- 类:
URLSearchParams
new URLSearchParams()
new URLSearchParams(string)
new URLSearchParams(obj)
new URLSearchParams(iterable)
urlSearchParams.append(name, value)
urlSearchParams.delete(name[, value])
urlSearchParams.entries()
urlSearchParams.forEach(fn[, thisArg])
urlSearchParams.get(name)
urlSearchParams.getAll(name)
urlSearchParams.has(name[, value])
urlSearchParams.keys()
urlSearchParams.set(name, value)
urlSearchParams.size
urlSearchParams.sort()
urlSearchParams.toString()
urlSearchParams.values()
urlSearchParams[Symbol.iterator]()
url.domainToASCII(domain)
url.domainToUnicode(domain)
url.fileURLToPath(url)
url.format(URL[, options])
url.pathToFileURL(path)
url.urlToHttpOptions(url)
- 类:
- 旧版 URL API
- URL 中的百分比编码
- URL
-
导航
- assert 断言
- async_hooks 异步钩子
- async_hooks/context 异步上下文
- buffer 缓冲区
- C++插件
- C/C++插件(使用 Node-API)
- C++嵌入器
- child_process 子进程
- cluster 集群
- CLI 命令行
- console 控制台
- Corepack 核心包
- crypto 加密
- crypto/webcrypto 网络加密
- debugger 调试器
- deprecation 弃用
- dgram 数据报
- diagnostics_channel 诊断通道
- dns 域名服务器
- domain 域
- Error 错误
- events 事件触发器
- fs 文件系统
- global 全局变量
- http 超文本传输协议
- http2 超文本传输协议 2.0
- https 安全超文本传输协议
- inspector 检查器
- Intl 国际化
- module 模块
- module/cjs CommonJS 模块
- module/esm ECMAScript 模块
- module/package 包模块
- net 网络
- os 操作系统
- path 路径
- perf_hooks 性能钩子
- permission 权限
- process 进程
- punycode 域名代码
- querystring 查询字符串
- readline 逐行读取
- repl 交互式解释器
- report 诊断报告
- sea 单个可执行应用程序
- stream 流
- stream/web 网络流
- string_decoder 字符串解码器
- test 测试
- timers 定时器
- tls 安全传输层
- trace_events 跟踪事件
- tty 终端
- url 网址
- util 实用工具
- v8 引擎
- vm 虚拟机
- wasi 网络汇编系统接口
- worker_threads 工作线程
- zlib 压缩
- 其他版本
URL#
¥Stability: 2 - Stable
源代码: lib/url.js
node:url
模块提供用于网址处理和解析的实用工具。可以使用以下方式访问它:
¥The node:url
module provides utilities for URL resolution and parsing. It can
be accessed using:
import url from 'node:url';
const url = require('node:url');
URL 字符串和 URL 对象#
¥URL strings and URL objects
网址字符串是包含多个有意义组件的结构化字符串。解析时,将返回包含每个组件的属性的网址对象。
¥A URL string is a structured string containing multiple meaningful components. When parsed, a URL object is returned containing properties for each of these components.
node:url
模块提供了两个用于处理 URL 的 API:一个特定于 Node.js 的旧版 API,以及一个实现 Web 浏览器使用的相同 WHATWG URL 标准 的较新 API。
¥The node:url
module provides two APIs for working with URLs: a legacy API that
is Node.js specific, and a newer API that implements the same
WHATWG URL Standard used by web browsers.
下面提供了 WHATWG 和旧版 API 之间的比较。在网址 'https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash'
上方显示的是由旧版 url.parse()
返回的对象的属性。下方则是 WHATWG URL
对象的属性。
¥A comparison between the WHATWG and legacy APIs is provided below. Above the URL
'https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash'
, properties
of an object returned by the legacy url.parse()
are shown. Below it are
properties of a WHATWG URL
object.
WHATWG 网址的 origin
属性包括 protocol
和 host
,但不包括 username
或 password
。
¥WHATWG URL's origin
property includes protocol
and host
, but not
username
or password
.
┌────────────────────────────────────────────────────────────────────────────────────────────────┐
│ href │
├──────────┬──┬─────────────────────┬────────────────────────┬───────────────────────────┬───────┤
│ protocol │ │ auth │ host │ path │ hash │
│ │ │ ├─────────────────┬──────┼──────────┬────────────────┤ │
│ │ │ │ hostname │ port │ pathname │ search │ │
│ │ │ │ │ │ ├─┬──────────────┤ │
│ │ │ │ │ │ │ │ query │ │
" https: // user : pass @ sub.example.com : 8080 /p/a/t/h ? query=string #hash "
│ │ │ │ │ hostname │ port │ │ │ │
│ │ │ │ ├─────────────────┴──────┤ │ │ │
│ protocol │ │ username │ password │ host │ │ │ │
├──────────┴──┼──────────┴──────────┼────────────────────────┤ │ │ │
│ origin │ │ origin │ pathname │ search │ hash │
├─────────────┴─────────────────────┴────────────────────────┴──────────┴────────────────┴───────┤
│ href │
└────────────────────────────────────────────────────────────────────────────────────────────────┘
(All spaces in the "" line should be ignored. They are purely for formatting.)
使用 WHATWG API 解析网址字符串:
¥Parsing the URL string using the WHATWG API:
const myURL =
new URL('https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash');
使用旧版 API 解析 URL 字符串:
¥Parsing the URL string using the legacy API:
import url from 'node:url';
const myURL =
url.parse('https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash');
const url = require('node:url');
const myURL =
url.parse('https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash');
从组成部分构造 URL 并获取构造的字符串#
¥Constructing a URL from component parts and getting the constructed string
可以使用属性设置器或模板字面串从组件部分构建 WHATWG 网址:
¥It is possible to construct a WHATWG URL from component parts using either the property setters or a template literal string:
const myURL = new URL('https://example.org');
myURL.pathname = '/a/b/c';
myURL.search = '?d=e';
myURL.hash = '#fgh';
const pathname = '/a/b/c';
const search = '?d=e';
const hash = '#fgh';
const myURL = new URL(`https://example.org${pathname}${search}${hash}`);
要获取构造的网址字符串,则使用 href
属性访问器:
¥To get the constructed URL string, use the href
property accessor:
console.log(myURL.href);
WHATWG URL API#
类:URL
#
¥Class: URL
浏览器兼容的 URL
类,按照 WHATWG 网址标准实现。已解析 URL 的示例 可以在标准本身中找到。URL
类也在全局对象上可用。
¥Browser-compatible URL
class, implemented by following the WHATWG URL
Standard. Examples of parsed URLs may be found in the Standard itself.
The URL
class is also available on the global object.
按照浏览器的约定,URL
对象的所有属性都被实现为类原型上的获取器和设置器,而不是对象本身的数据属性。因此,与 旧版 urlObject
不同,在 URL
对象(例如 delete myURL.protocol
、delete myURL.pathname
等)的任何属性上使用 delete
关键字没有效果,但仍会返回 true
。
¥In accordance with browser conventions, all properties of URL
objects
are implemented as getters and setters on the class prototype, rather than as
data properties on the object itself. Thus, unlike legacy urlObject
s,
using the delete
keyword on any properties of URL
objects (e.g. delete myURL.protocol
, delete myURL.pathname
, etc) has no effect but will still
return true
.
new URL(input[, base])
#
-
input
<string> 要解析的绝对或相对的输入网址。如果input
是相对的,则需要base
。如果input
是绝对的,则忽略base
。如果input
不是字符串,则首先是 转换为字符串。¥
input
<string> The absolute or relative input URL to parse. Ifinput
is relative, thenbase
is required. Ifinput
is absolute, thebase
is ignored. Ifinput
is not a string, it is converted to a string first. -
base
<string> 如果input
不是绝对的,则为要解析的基本网址。如果base
不是字符串,则首先是 转换为字符串。¥
base
<string> The base URL to resolve against if theinput
is not absolute. Ifbase
is not a string, it is converted to a string first.
通过相对于 base
解析 input
来创建新的 URL
对象。如果 base
作为字符串传入,则其将被解析为等效于 new URL(base)
。
¥Creates a new URL
object by parsing the input
relative to the base
. If
base
is passed as a string, it will be parsed equivalent to new URL(base)
.
const myURL = new URL('/foo', 'https://example.org/');
// https://example.org/foo
网址构造函数可作为全局对象的属性访问。也可以从内置的 url 模块中导入:
¥The URL constructor is accessible as a property on the global object. It can also be imported from the built-in url module:
import { URL } from 'node:url';
console.log(URL === globalThis.URL); // Prints 'true'.
console.log(URL === require('node:url').URL); // Prints 'true'.
如果 input
或 base
不是有效的网址,则将抛出 TypeError
。注意,会将给定的值强制转换为字符串。例如:
¥A TypeError
will be thrown if the input
or base
are not valid URLs. Note
that an effort will be made to coerce the given values into strings. For
instance:
const myURL = new URL({ toString: () => 'https://example.org/' });
// https://example.org/
input
的主机名中出现的 Unicode 字符将使用 Punycode 算法自动转换为 ASCII。
¥Unicode characters appearing within the host name of input
will be
automatically converted to ASCII using the Punycode algorithm.
const myURL = new URL('https://測試');
// https://xn--g6w251d/
如果事先不知道 input
是否是绝对的网址并且提供了 base
,则建议验证 URL
对象的 origin
是否符合预期。
¥In cases where it is not known in advance if input
is an absolute URL
and a base
is provided, it is advised to validate that the origin
of
the URL
object is what is expected.
let myURL = new URL('http://Example.com/', 'https://example.org/');
// http://example.com/
myURL = new URL('https://Example.com/', 'https://example.org/');
// https://example.com/
myURL = new URL('foo://Example.com/', 'https://example.org/');
// foo://Example.com/
myURL = new URL('http:Example.com/', 'https://example.org/');
// http://example.com/
myURL = new URL('https:Example.com/', 'https://example.org/');
// https://example.org/Example.com/
myURL = new URL('foo:Example.com/', 'https://example.org/');
// foo:Example.com/
url.hash
#
获取和设置网址的片段部分。
¥Gets and sets the fragment portion of the URL.
const myURL = new URL('https://example.org/foo#bar');
console.log(myURL.hash);
// Prints #bar
myURL.hash = 'baz';
console.log(myURL.href);
// Prints https://example.org/foo#baz
分配给 hash
属性的值中包含的无效 URL 字符是 percent-encoded。选择要进行百分比编码的字符可能与 url.parse()
和 url.format()
方法产生的结果有所不同。
¥Invalid URL characters included in the value assigned to the hash
property
are percent-encoded. The selection of which characters to
percent-encode may vary somewhat from what the url.parse()
and
url.format()
methods would produce.
url.host
#
获取和设置网址的主机部分。
¥Gets and sets the host portion of the URL.
const myURL = new URL('https://example.org:81/foo');
console.log(myURL.host);
// Prints example.org:81
myURL.host = 'example.com:82';
console.log(myURL.href);
// Prints https://example.com:82/foo
分配给 host
属性的无效主机值将被忽略。
¥Invalid host values assigned to the host
property are ignored.
url.hostname
#
获取和设置网址的主机名部分。url.host
和 url.hostname
之间的主要区别是 url.hostname
不包括端口。
¥Gets and sets the host name portion of the URL. The key difference between
url.host
and url.hostname
is that url.hostname
does not include the
port.
const myURL = new URL('https://example.org:81/foo');
console.log(myURL.hostname);
// Prints example.org
// Setting the hostname does not change the port
myURL.hostname = 'example.com';
console.log(myURL.href);
// Prints https://example.com:81/foo
// Use myURL.host to change the hostname and port
myURL.host = 'example.org:82';
console.log(myURL.href);
// Prints https://example.org:82/foo
分配给 hostname
属性的无效主机名值将被忽略。
¥Invalid host name values assigned to the hostname
property are ignored.
url.href
#
获取和设置序列化的网址。
¥Gets and sets the serialized URL.
const myURL = new URL('https://example.org/foo');
console.log(myURL.href);
// Prints https://example.org/foo
myURL.href = 'https://example.com/bar';
console.log(myURL.href);
// Prints https://example.com/bar
获取 href
属性的值相当于调用 url.toString()
。
¥Getting the value of the href
property is equivalent to calling
url.toString()
.
将此属性的值设置为新值相当于使用 new URL(value)
创建新的 URL
对象。URL
对象的每个属性都将被修改。
¥Setting the value of this property to a new value is equivalent to creating a
new URL
object using new URL(value)
. Each of the URL
object's properties will be modified.
如果分配给 href
属性的值不是有效的网址,则将抛出 TypeError
。
¥If the value assigned to the href
property is not a valid URL, a TypeError
will be thrown.
url.origin
#
获取网址的源的只读的序列化。
¥Gets the read-only serialization of the URL's origin.
const myURL = new URL('https://example.org/foo/bar?baz');
console.log(myURL.origin);
// Prints https://example.org
const idnURL = new URL('https://測試');
console.log(idnURL.origin);
// Prints https://xn--g6w251d
console.log(idnURL.hostname);
// Prints xn--g6w251d
url.password
#
获取和设置网址的密码部分。
¥Gets and sets the password portion of the URL.
const myURL = new URL('https://abc:xyz@example.com');
console.log(myURL.password);
// Prints xyz
myURL.password = '123';
console.log(myURL.href);
// Prints https://abc:123@example.com/
分配给 password
属性的值中包含的无效 URL 字符是 percent-encoded。选择要进行百分比编码的字符可能与 url.parse()
和 url.format()
方法产生的结果有所不同。
¥Invalid URL characters included in the value assigned to the password
property
are percent-encoded. The selection of which characters to
percent-encode may vary somewhat from what the url.parse()
and
url.format()
methods would produce.
url.pathname
#
获取和设置网址的路径部分。
¥Gets and sets the path portion of the URL.
const myURL = new URL('https://example.org/abc/xyz?123');
console.log(myURL.pathname);
// Prints /abc/xyz
myURL.pathname = '/abcdef';
console.log(myURL.href);
// Prints https://example.org/abcdef?123
分配给 pathname
属性的值中包含的无效 URL 字符是 percent-encoded。选择要进行百分比编码的字符可能与 url.parse()
和 url.format()
方法产生的结果有所不同。
¥Invalid URL characters included in the value assigned to the pathname
property are percent-encoded. The selection of which characters
to percent-encode may vary somewhat from what the url.parse()
and
url.format()
methods would produce.
url.port
#
获取和设置网址的端口部分。
¥Gets and sets the port portion of the URL.
端口值可以是数字,也可以是包含 0
到 65535
(含)范围内的数字的字符串。将值设置为给定 protocol
的 URL
对象的默认端口将导致 port
值成为空字符串 (''
)。
¥The port value may be a number or a string containing a number in the range
0
to 65535
(inclusive). Setting the value to the default port of the
URL
objects given protocol
will result in the port
value becoming
the empty string (''
).
端口值可以是空字符串,在这种情况下端口取决于协议/方案:
¥The port value can be an empty string in which case the port depends on the protocol/scheme:
协议 | 端口 |
---|---|
"ftp" | 21 |
"file" | |
"http" | 80 |
"https" | 443 |
"ws" | 80 |
"wss" | 443 |
为端口分配值后,该值将首先使用 .toString()
转换为字符串。
¥Upon assigning a value to the port, the value will first be converted to a
string using .toString()
.
如果该字符串无效但以数字开头,则将前导数字分配给 port
。如果数字在上述范围之外,则将其忽略。
¥If that string is invalid but it begins with a number, the leading number is
assigned to port
.
If the number lies outside the range denoted above, it is ignored.
const myURL = new URL('https://example.org:8888');
console.log(myURL.port);
// Prints 8888
// Default ports are automatically transformed to the empty string
// (HTTPS protocol's default port is 443)
myURL.port = '443';
console.log(myURL.port);
// Prints the empty string
console.log(myURL.href);
// Prints https://example.org/
myURL.port = 1234;
console.log(myURL.port);
// Prints 1234
console.log(myURL.href);
// Prints https://example.org:1234/
// Completely invalid port strings are ignored
myURL.port = 'abcd';
console.log(myURL.port);
// Prints 1234
// Leading numbers are treated as a port number
myURL.port = '5678abcd';
console.log(myURL.port);
// Prints 5678
// Non-integers are truncated
myURL.port = 1234.5678;
console.log(myURL.port);
// Prints 1234
// Out-of-range numbers which are not represented in scientific notation
// will be ignored.
myURL.port = 1e10; // 10000000000, will be range-checked as described below
console.log(myURL.port);
// Prints 1234
包含小数点的数字,例如浮点数或科学记数法中的数字,也不例外。小数点前的前导数字将被设置为网址的端口,假设它们是有效的:
¥Numbers which contain a decimal point, such as floating-point numbers or numbers in scientific notation, are not an exception to this rule. Leading numbers up to the decimal point will be set as the URL's port, assuming they are valid:
myURL.port = 4.567e21;
console.log(myURL.port);
// Prints 4 (because it is the leading number in the string '4.567e21')
url.protocol
#
获取和设置网址的协议部分。
¥Gets and sets the protocol portion of the URL.
const myURL = new URL('https://example.org');
console.log(myURL.protocol);
// Prints https:
myURL.protocol = 'ftp';
console.log(myURL.href);
// Prints ftp://example.org/
分配给 protocol
属性的无效的网址协议值将被忽略。
¥Invalid URL protocol values assigned to the protocol
property are ignored.
特别计划#
¥Special schemes
WHATWG URL 标准 认为少数 URL 协议方案在解析和序列化方面是特殊的。当使用这些特殊协议之一解析网址时,url.protocol
属性可能会更改为另一种特殊协议,但不能更改为非特殊协议,反之亦然。
¥The WHATWG URL Standard considers a handful of URL protocol schemes to be
special in terms of how they are parsed and serialized. When a URL is
parsed using one of these special protocols, the url.protocol
property
may be changed to another special protocol but cannot be changed to a
non-special protocol, and vice versa.
例如,从 http
更改为 https
有效:
¥For instance, changing from http
to https
works:
const u = new URL('http://example.org');
u.protocol = 'https';
console.log(u.href);
// https://example.org/
但是,从 http
更改为假设的 fish
协议并不是因为新协议并不特殊。
¥However, changing from http
to a hypothetical fish
protocol does not
because the new protocol is not special.
const u = new URL('http://example.org');
u.protocol = 'fish';
console.log(u.href);
// http://example.org/
同样,也不允许从非特殊协议更改为特殊协议:
¥Likewise, changing from a non-special protocol to a special protocol is also not permitted:
const u = new URL('fish://example.org');
u.protocol = 'http';
console.log(u.href);
// fish://example.org
根据 WHATWG 网址标准,特殊协议方案有 ftp
、file
、http
、https
、ws
和 wss
。
¥According to the WHATWG URL Standard, special protocol schemes are ftp
,
file
, http
, https
, ws
, and wss
.
url.search
#
获取和设置网址的序列化的查询部分。
¥Gets and sets the serialized query portion of the URL.
const myURL = new URL('https://example.org/abc?123');
console.log(myURL.search);
// Prints ?123
myURL.search = 'abc=xyz';
console.log(myURL.href);
// Prints https://example.org/abc?abc=xyz
分配给 search
属性的值中出现的任何无效 URL 字符都将为 percent-encoded。选择要进行百分比编码的字符可能与 url.parse()
和 url.format()
方法产生的结果有所不同。
¥Any invalid URL characters appearing in the value assigned the search
property will be percent-encoded. The selection of which
characters to percent-encode may vary somewhat from what the url.parse()
and url.format()
methods would produce.
url.searchParams
#
获取表示网址查询参数的 URLSearchParams
对象。该属性是只读的,但它提供的 URLSearchParams
对象可用于改变 URL 实例;要替换 URL 的全部查询参数,请使用 url.search
设置器。有关详细信息,请参阅 URLSearchParams
文档。
¥Gets the URLSearchParams
object representing the query parameters of the
URL. This property is read-only but the URLSearchParams
object it provides
can be used to mutate the URL instance; to replace the entirety of query
parameters of the URL, use the url.search
setter. See
URLSearchParams
documentation for details.
当使用 .searchParams
修改 URL
时要小心,因为根据 WHATWG 规范,URLSearchParams
对象使用不同的规则来确定要对哪些字符进行百分比编码。例如,URL
对象不会对 ASCII 波浪号 (~
) 字符进行百分比编码,而 URLSearchParams
将始终对其进行编码:
¥Use care when using .searchParams
to modify the URL
because,
per the WHATWG specification, the URLSearchParams
object uses
different rules to determine which characters to percent-encode. For
instance, the URL
object will not percent encode the ASCII tilde (~
)
character, while URLSearchParams
will always encode it:
const myURL = new URL('https://example.org/abc?foo=~bar');
console.log(myURL.search); // prints ?foo=~bar
// Modify the URL via searchParams...
myURL.searchParams.sort();
console.log(myURL.search); // prints ?foo=%7Ebar
url.username
#
获取和设置网址的用户名部分。
¥Gets and sets the username portion of the URL.
const myURL = new URL('https://abc:xyz@example.com');
console.log(myURL.username);
// Prints abc
myURL.username = '123';
console.log(myURL.href);
// Prints https://123:xyz@example.com/
分配给 username
属性的值中出现的任何无效 URL 字符都将为 percent-encoded。选择要进行百分比编码的字符可能与 url.parse()
和 url.format()
方法产生的结果有所不同。
¥Any invalid URL characters appearing in the value assigned the username
property will be percent-encoded. The selection of which
characters to percent-encode may vary somewhat from what the url.parse()
and url.format()
methods would produce.
url.toString()
#
URL
对象上的 toString()
方法返回序列化的网址。返回值等同于 url.href
和 url.toJSON()
的值。
¥The toString()
method on the URL
object returns the serialized URL. The
value returned is equivalent to that of url.href
and url.toJSON()
.
url.toJSON()
#
URL
对象上的 toJSON()
方法返回序列化的网址。返回值等同于 url.href
和 url.toString()
的值。
¥The toJSON()
method on the URL
object returns the serialized URL. The
value returned is equivalent to that of url.href
and
url.toString()
.
当 URL
对象用 JSON.stringify()
序列化时,会自动调用此方法。
¥This method is automatically called when an URL
object is serialized
with JSON.stringify()
.
const myURLs = [
new URL('https://www.example.com'),
new URL('https://test.example.org'),
];
console.log(JSON.stringify(myURLs));
// Prints ["https://www.example.com/","https://test.example.org/"]
URL.createObjectURL(blob)
#
¥Stability: 1 - Experimental
创建表示给定的 <Blob> 对象并且可用于稍后检索 Blob
的 'blob:nodedata:...'
网址字符串。
¥Creates a 'blob:nodedata:...'
URL string that represents the given <Blob>
object and can be used to retrieve the Blob
later.
const {
Blob,
resolveObjectURL,
} = require('node:buffer');
const blob = new Blob(['hello']);
const id = URL.createObjectURL(blob);
// later...
const otherBlob = resolveObjectURL(id);
console.log(otherBlob.size);
已注册的 <Blob> 存储的数据将保留在内存中,直到调用 URL.revokeObjectURL()
将其删除。
¥The data stored by the registered <Blob> will be retained in memory until
URL.revokeObjectURL()
is called to remove it.
Blob
对象已在当前线程中注册。如果使用工作线程,则在工作线程内注册的 Blob
对象将不能被其他工作线程或主线程使用。
¥Blob
objects are registered within the current thread. If using Worker
Threads, Blob
objects registered within one Worker will not be available
to other workers or the main thread.
URL.revokeObjectURL(id)
#
¥Stability: 1 - Experimental
-
id
<string> 先前调用URL.createObjectURL()
返回的'blob:nodedata:...
网址字符串。¥
id
<string> A'blob:nodedata:...
URL string returned by a prior call toURL.createObjectURL()
.
删除由给定标识符标识的已存储的 <Blob>。尝试撤销未注册的 ID 将静默失败。
¥Removes the stored <Blob> identified by the given ID. Attempting to revoke a ID that isn't registered will silently fail.
URL.canParse(input[, base])
#
-
input
<string> 要解析的绝对或相对的输入网址。如果input
是相对的,则需要base
。如果input
是绝对的,则忽略base
。如果input
不是字符串,则首先是 转换为字符串。¥
input
<string> The absolute or relative input URL to parse. Ifinput
is relative, thenbase
is required. Ifinput
is absolute, thebase
is ignored. Ifinput
is not a string, it is converted to a string first. -
base
<string> 如果input
不是绝对的,则为要解析的基本网址。如果base
不是字符串,则首先是 转换为字符串。¥
base
<string> The base URL to resolve against if theinput
is not absolute. Ifbase
is not a string, it is converted to a string first. -
返回:<boolean>
¥Returns: <boolean>
检查相对于 base
的 input
是否可以解析为 URL
。
¥Checks if an input
relative to the base
can be parsed to a URL
.
const isValid = URL.canParse('/foo', 'https://example.org/'); // true
const isNotValid = URL.canParse('/foo'); // false
类:URLSearchParams
#
¥Class: URLSearchParams
URLSearchParams
API 提供对 URL
查询的读写访问。URLSearchParams
类也可以与以下四个构造函数之一单独使用。URLSearchParams
类也在全局对象上可用。
¥The URLSearchParams
API provides read and write access to the query of a
URL
. The URLSearchParams
class can also be used standalone with one of the
four following constructors.
The URLSearchParams
class is also available on the global object.
WHATWG URLSearchParams
接口和 querystring
模块具有相似的用途,但 querystring
模块的用途更通用,因为它允许自定义的分隔符(&
和 =
)。换句话说,此 API 纯粹是为网址查询字符串而设计。
¥The WHATWG URLSearchParams
interface and the querystring
module have
similar purpose, but the purpose of the querystring
module is more
general, as it allows the customization of delimiter characters (&
and =
).
On the other hand, this API is designed purely for URL query strings.
const myURL = new URL('https://example.org/?abc=123');
console.log(myURL.searchParams.get('abc'));
// Prints 123
myURL.searchParams.append('abc', 'xyz');
console.log(myURL.href);
// Prints https://example.org/?abc=123&abc=xyz
myURL.searchParams.delete('abc');
myURL.searchParams.set('a', 'b');
console.log(myURL.href);
// Prints https://example.org/?a=b
const newSearchParams = new URLSearchParams(myURL.searchParams);
// The above is equivalent to
// const newSearchParams = new URLSearchParams(myURL.search);
newSearchParams.append('a', 'c');
console.log(myURL.href);
// Prints https://example.org/?a=b
console.log(newSearchParams.toString());
// Prints a=b&a=c
// newSearchParams.toString() is implicitly called
myURL.search = newSearchParams;
console.log(myURL.href);
// Prints https://example.org/?a=b&a=c
newSearchParams.delete('a');
console.log(myURL.href);
// Prints https://example.org/?a=b&a=c
new URLSearchParams()
#
实例化新的空 URLSearchParams
对象。
¥Instantiate a new empty URLSearchParams
object.
new URLSearchParams(string)
#
将 string
解析为查询字符串,并使用它来实例化新的 URLSearchParams
对象。前导 '?'
(如果存在)将被忽略。
¥Parse the string
as a query string, and use it to instantiate a new
URLSearchParams
object. A leading '?'
, if present, is ignored.
let params;
params = new URLSearchParams('user=abc&query=xyz');
console.log(params.get('user'));
// Prints 'abc'
console.log(params.toString());
// Prints 'user=abc&query=xyz'
params = new URLSearchParams('?user=abc&query=xyz');
console.log(params.toString());
// Prints 'user=abc&query=xyz'
new URLSearchParams(obj)
#
使用查询哈希映射实例化新的 URLSearchParams
对象。obj
的每个属性的键和值总是被强制转换为字符串。
¥Instantiate a new URLSearchParams
object with a query hash map. The key and
value of each property of obj
are always coerced to strings.
与 querystring
模块不同,不允许以数组值的形式出现重复的键。数组使用 array.toString()
字符串化,它简单地用逗号连接所有数组元素。
¥Unlike querystring
module, duplicate keys in the form of array values are
not allowed. Arrays are stringified using array.toString()
, which simply
joins all array elements with commas.
const params = new URLSearchParams({
user: 'abc',
query: ['first', 'second'],
});
console.log(params.getAll('query'));
// Prints [ 'first,second' ]
console.log(params.toString());
// Prints 'user=abc&query=first%2Csecond'
new URLSearchParams(iterable)
#
-
iterable
<Iterable> 元素为键值对的可迭代对象¥
iterable
<Iterable> An iterable object whose elements are key-value pairs
以类似于 Map
的构造函数的方式使用可迭代映射实例化新的 URLSearchParams
对象。iterable
可以是 Array
或任何可迭代对象。这意味着 iterable
可以是另一个 URLSearchParams
,在这种情况下,构造函数将简单地创建提供的 URLSearchParams
的克隆。iterable
的元素是键值对,并且本身可以是任何可迭代对象。
¥Instantiate a new URLSearchParams
object with an iterable map in a way that
is similar to Map
's constructor. iterable
can be an Array
or any
iterable object. That means iterable
can be another URLSearchParams
, in
which case the constructor will simply create a clone of the provided
URLSearchParams
. Elements of iterable
are key-value pairs, and can
themselves be any iterable object.
允许重复的键。
¥Duplicate keys are allowed.
let params;
// Using an array
params = new URLSearchParams([
['user', 'abc'],
['query', 'first'],
['query', 'second'],
]);
console.log(params.toString());
// Prints 'user=abc&query=first&query=second'
// Using a Map object
const map = new Map();
map.set('user', 'abc');
map.set('query', 'xyz');
params = new URLSearchParams(map);
console.log(params.toString());
// Prints 'user=abc&query=xyz'
// Using a generator function
function* getQueryPairs() {
yield ['user', 'abc'];
yield ['query', 'first'];
yield ['query', 'second'];
}
params = new URLSearchParams(getQueryPairs());
console.log(params.toString());
// Prints 'user=abc&query=first&query=second'
// Each key-value pair must have exactly two elements
new URLSearchParams([
['user', 'abc', 'error'],
]);
// Throws TypeError [ERR_INVALID_TUPLE]:
// Each query pair must be an iterable [name, value] tuple
urlSearchParams.append(name, value)
#
将新的名称-值对追加到查询字符串。
¥Append a new name-value pair to the query string.
urlSearchParams.delete(name[, value])
#
如果提供了 value
,则删除名称为 name
且值为 value
的所有名称-值对。
¥If value
is provided, removes all name-value pairs
where name is name
and value is value
..
如果未提供 value
,则删除名称为 name
的所有名称-值对。
¥If value
is not provided, removes all name-value pairs whose name is name
.
urlSearchParams.entries()
#
-
返回:<Iterator>
¥Returns: <Iterator>
在查询中的每个名称-值对上返回 ES6 Iterator
。迭代器的每一项都是 JavaScript Array
。Array
的第一项是 name
,Array
的第二项是 value
。
¥Returns an ES6 Iterator
over each of the name-value pairs in the query.
Each item of the iterator is a JavaScript Array
. The first item of the Array
is the name
, the second item of the Array
is the value
.
urlSearchParams[@@iterator]()
的别名。
¥Alias for urlSearchParams[@@iterator]()
.
urlSearchParams.forEach(fn[, thisArg])
#
-
fn
<Function> 为查询中的每个名称-值对调用¥
fn
<Function> Invoked for each name-value pair in the query -
thisArg
<Object> 在调用fn
时用作this
值¥
thisArg
<Object> To be used asthis
value for whenfn
is called
迭代查询中的每个名称-值对并调用给定的函数。
¥Iterates over each name-value pair in the query and invokes the given function.
const myURL = new URL('https://example.org/?a=b&c=d');
myURL.searchParams.forEach((value, name, searchParams) => {
console.log(name, value, myURL.searchParams === searchParams);
});
// Prints:
// a b true
// c d true
urlSearchParams.get(name)
#
-
name
<string> -
返回:<string> 或
null
(如果不存在具有给定name
的名称-值对)。¥Returns: <string> or
null
if there is no name-value pair with the givenname
.
返回名称为 name
的第一个名称-值对的值。如果没有这样的对,则返回 null
。
¥Returns the value of the first name-value pair whose name is name
. If there
are no such pairs, null
is returned.
urlSearchParams.getAll(name)
#
-
name
<string> -
返回:<string[]>
¥Returns: <string[]>
返回名称为 name
的所有名称-值对的值。如果没有这样的对,则返回空数组。
¥Returns the values of all name-value pairs whose name is name
. If there are
no such pairs, an empty array is returned.
urlSearchParams.has(name[, value])
#
检查 URLSearchParams
对象是否包含基于 name
和可选的 value
参数的键值对。
¥Checks if the URLSearchParams
object contains key-value pair(s) based on
name
and an optional value
argument.
如果提供了 value
,则当存在具有相同 name
和 value
的名称-值对时返回 true
。
¥If value
is provided, returns true
when name-value pair with
same name
and value
exists.
如果未提供 value
,则如果至少有一个名称为 name
的名称-值对,则返回 true
。
¥If value
is not provided, returns true
if there is at least one name-value
pair whose name is name
.
urlSearchParams.keys()
#
-
返回:<Iterator>
¥Returns: <Iterator>
在每个名称-值对的名称上返回 ES6 Iterator
。
¥Returns an ES6 Iterator
over the names of each name-value pair.
const params = new URLSearchParams('foo=bar&foo=baz');
for (const name of params.keys()) {
console.log(name);
}
// Prints:
// foo
// foo
urlSearchParams.set(name, value)
#
将与 name
关联的 URLSearchParams
对象中的值设置为 value
。如果存在任何名称为 name
的预先存在的名称-值对,则将第一个此类对的值设置为 value
并删除所有其他名称。如果没有,则将名称-值对追加到查询字符串。
¥Sets the value in the URLSearchParams
object associated with name
to
value
. If there are any pre-existing name-value pairs whose names are name
,
set the first such pair's value to value
and remove all others. If not,
append the name-value pair to the query string.
const params = new URLSearchParams();
params.append('foo', 'bar');
params.append('foo', 'baz');
params.append('abc', 'def');
console.log(params.toString());
// Prints foo=bar&foo=baz&abc=def
params.set('foo', 'def');
params.set('xyz', 'opq');
console.log(params.toString());
// Prints foo=def&abc=def&xyz=opq
urlSearchParams.size
#
参数条目的总数。
¥The total number of parameter entries.
urlSearchParams.sort()
#
按名称对所有现有的名称-值对进行就地排序。排序是使用 稳定排序算法 完成的,因此保留了具有相同名称的名称-值对之间的相对顺序。
¥Sort all existing name-value pairs in-place by their names. Sorting is done with a stable sorting algorithm, so relative order between name-value pairs with the same name is preserved.
该方法尤其可用于增加缓存命中。
¥This method can be used, in particular, to increase cache hits.
const params = new URLSearchParams('query[]=abc&type=search&query[]=123');
params.sort();
console.log(params.toString());
// Prints query%5B%5D=abc&query%5B%5D=123&type=search
urlSearchParams.toString()
#
返回序列化为字符串的搜索参数,必要时使用百分比编码的字符。
¥Returns the search parameters serialized as a string, with characters percent-encoded where necessary.
urlSearchParams.values()
#
-
返回:<Iterator>
¥Returns: <Iterator>
在每个名称-值对的值上返回 ES6 Iterator
。
¥Returns an ES6 Iterator
over the values of each name-value pair.
urlSearchParams[Symbol.iterator]()
#
-
返回:<Iterator>
¥Returns: <Iterator>
在查询字符串中的每个名称-值对上返回 ES6 Iterator
。迭代器的每一项都是 JavaScript Array
。Array
的第一项是 name
,Array
的第二项是 value
。
¥Returns an ES6 Iterator
over each of the name-value pairs in the query string.
Each item of the iterator is a JavaScript Array
. The first item of the Array
is the name
, the second item of the Array
is the value
.
urlSearchParams.entries()
的别名。
¥Alias for urlSearchParams.entries()
.
const params = new URLSearchParams('foo=bar&xyz=baz');
for (const [name, value] of params) {
console.log(name, value);
}
// Prints:
// foo bar
// xyz baz
url.domainToASCII(domain)
#
返回 domain
的 Punycode ASCII 序列化。如果 domain
是无效域,则返回空字符串。
¥Returns the Punycode ASCII serialization of the domain
. If domain
is an
invalid domain, the empty string is returned.
它执行与 url.domainToUnicode()
相反的操作。
¥It performs the inverse operation to url.domainToUnicode()
.
import url from 'node:url';
console.log(url.domainToASCII('español.com'));
// Prints xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'));
// Prints xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'));
// Prints an empty string
const url = require('node:url');
console.log(url.domainToASCII('español.com'));
// Prints xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'));
// Prints xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'));
// Prints an empty string
url.domainToUnicode(domain)
#
返回 domain
的 Unicode 序列化。如果 domain
是无效域,则返回空字符串。
¥Returns the Unicode serialization of the domain
. If domain
is an invalid
domain, the empty string is returned.
它执行与 url.domainToASCII()
相反的操作。
¥It performs the inverse operation to url.domainToASCII()
.
import url from 'node:url';
console.log(url.domainToUnicode('xn--espaol-zwa.com'));
// Prints español.com
console.log(url.domainToUnicode('xn--fiq228c.com'));
// Prints 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'));
// Prints an empty string
const url = require('node:url');
console.log(url.domainToUnicode('xn--espaol-zwa.com'));
// Prints español.com
console.log(url.domainToUnicode('xn--fiq228c.com'));
// Prints 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'));
// Prints an empty string
url.fileURLToPath(url)
#
-
url
<URL> | <string> 要转换为路径的文件网址字符串或网址对象。¥
url
<URL> | <string> The file URL string or URL object to convert to a path. -
返回:<string> 完全解析的特定于平台的 Node.js 文件路径。
¥Returns: <string> The fully-resolved platform-specific Node.js file path.
此函数可确保正确解码百分比编码字符,并确保跨平台有效的绝对路径字符串。
¥This function ensures the correct decodings of percent-encoded characters as well as ensuring a cross-platform valid absolute path string.
import { fileURLToPath } from 'node:url';
const __filename = fileURLToPath(import.meta.url);
new URL('file:///C:/path/').pathname; // Incorrect: /C:/path/
fileURLToPath('file:///C:/path/'); // Correct: C:\path\ (Windows)
new URL('file://nas/foo.txt').pathname; // Incorrect: /foo.txt
fileURLToPath('file://nas/foo.txt'); // Correct: \\nas\foo.txt (Windows)
new URL('file:///你好.txt').pathname; // Incorrect: /%E4%BD%A0%E5%A5%BD.txt
fileURLToPath('file:///你好.txt'); // Correct: /你好.txt (POSIX)
new URL('file:///hello world').pathname; // Incorrect: /hello%20world
fileURLToPath('file:///hello world'); // Correct: /hello world (POSIX)
const { fileURLToPath } = require('node:url');
new URL('file:///C:/path/').pathname; // Incorrect: /C:/path/
fileURLToPath('file:///C:/path/'); // Correct: C:\path\ (Windows)
new URL('file://nas/foo.txt').pathname; // Incorrect: /foo.txt
fileURLToPath('file://nas/foo.txt'); // Correct: \\nas\foo.txt (Windows)
new URL('file:///你好.txt').pathname; // Incorrect: /%E4%BD%A0%E5%A5%BD.txt
fileURLToPath('file:///你好.txt'); // Correct: /你好.txt (POSIX)
new URL('file:///hello world').pathname; // Incorrect: /hello%20world
fileURLToPath('file:///hello world'); // Correct: /hello world (POSIX)
url.format(URL[, options])
#
-
URL
<URL> 一个 WHATWG URL 对象¥
URL
<URL> A WHATWG URL object -
options
<Object>-
auth
<boolean> 如果序列化 URL 字符串应包含用户名和密码,则为true
,否则为false
。默认值:true
。¥
auth
<boolean>true
if the serialized URL string should include the username and password,false
otherwise. Default:true
. -
fragment
<boolean> 如果序列化 URL 字符串应包含片段,则为true
,否则为false
。默认值:true
。¥
fragment
<boolean>true
if the serialized URL string should include the fragment,false
otherwise. Default:true
. -
search
<boolean> 如果序列化 URL 字符串应包含搜索查询,则为true
,否则为false
。默认值:true
。¥
search
<boolean>true
if the serialized URL string should include the search query,false
otherwise. Default:true
. -
unicode
<boolean>true
如果 URL 字符串的主机组件中出现的 Unicode 字符应直接编码,而不是 Punycode 编码。默认值:false
。¥
unicode
<boolean>true
if Unicode characters appearing in the host component of the URL string should be encoded directly as opposed to being Punycode encoded. Default:false
.
-
-
返回:<string>
¥Returns: <string>
返回 WHATWG URL 对象的 URL String
表示的可自定义序列化。
¥Returns a customizable serialization of a URL String
representation of a
WHATWG URL object.
网址对象具有 toString()
方法和 href
属性,用于返回网址的字符串序列化。但是,这些都不能以任何方式自定义。url.format(URL[, options])
方法允许对输出进行基本的自定义。
¥The URL object has both a toString()
method and href
property that return
string serializations of the URL. These are not, however, customizable in
any way. The url.format(URL[, options])
method allows for basic customization
of the output.
import url from 'node:url';
const myURL = new URL('https://a:b@測試?abc#foo');
console.log(myURL.href);
// Prints https://a:b@xn--g6w251d/?abc#foo
console.log(myURL.toString());
// Prints https://a:b@xn--g6w251d/?abc#foo
console.log(url.format(myURL, { fragment: false, unicode: true, auth: false }));
// Prints 'https://測試/?abc'
const url = require('node:url');
const myURL = new URL('https://a:b@測試?abc#foo');
console.log(myURL.href);
// Prints https://a:b@xn--g6w251d/?abc#foo
console.log(myURL.toString());
// Prints https://a:b@xn--g6w251d/?abc#foo
console.log(url.format(myURL, { fragment: false, unicode: true, auth: false }));
// Prints 'https://測試/?abc'
url.pathToFileURL(path)
#
-
path
<string> 要转换为文件网址的路径。¥
path
<string> The path to convert to a File URL. -
返回:<URL> 文件网址对象。
¥Returns: <URL> The file URL object.
该函数确保 path
被绝对解析,并且在转换为文件网址时正确编码网址控制字符。
¥This function ensures that path
is resolved absolutely, and that the URL
control characters are correctly encoded when converting into a File URL.
import { pathToFileURL } from 'node:url';
new URL('/foo#1', 'file:'); // Incorrect: file:///foo#1
pathToFileURL('/foo#1'); // Correct: file:///foo%231 (POSIX)
new URL('/some/path%.c', 'file:'); // Incorrect: file:///some/path%.c
pathToFileURL('/some/path%.c'); // Correct: file:///some/path%25.c (POSIX)
const { pathToFileURL } = require('node:url');
new URL(__filename); // Incorrect: throws (POSIX)
new URL(__filename); // Incorrect: C:\... (Windows)
pathToFileURL(__filename); // Correct: file:///... (POSIX)
pathToFileURL(__filename); // Correct: file:///C:/... (Windows)
new URL('/foo#1', 'file:'); // Incorrect: file:///foo#1
pathToFileURL('/foo#1'); // Correct: file:///foo%231 (POSIX)
new URL('/some/path%.c', 'file:'); // Incorrect: file:///some/path%.c
pathToFileURL('/some/path%.c'); // Correct: file:///some/path%25.c (POSIX)
url.urlToHttpOptions(url)
#
-
url
<URL> 要转换为选项对象的 WHATWG URL 对象。¥
url
<URL> The WHATWG URL object to convert to an options object. -
返回:<Object> 选项对象
¥Returns: <Object> Options object
-
protocol
<string> 要使用的协议。¥
protocol
<string> Protocol to use. -
hostname
<string> 要向其触发请求的服务器的域名或 IP 地址。¥
hostname
<string> A domain name or IP address of the server to issue the request to. -
hash
<string> 网址的片段部分。¥
hash
<string> The fragment portion of the URL. -
search
<string> 网址的序列化的查询部分。¥
search
<string> The serialized query portion of the URL. -
pathname
<string> 网址的路径部分。¥
pathname
<string> The path portion of the URL. -
path
<string> 请求的路径。应包括查询字符串(如果有)。E.G.'/index.html?page=12'
。当请求路径包含非法字符时抛出异常。目前,只有空格被拒绝,但将来可能会改变。¥
path
<string> Request path. Should include query string if any. E.G.'/index.html?page=12'
. An exception is thrown when the request path contains illegal characters. Currently, only spaces are rejected but that may change in the future. -
href
<string> 序列化的网址。¥
href
<string> The serialized URL. -
port
<number> 远程服务器的端口。¥
port
<number> Port of remote server. -
auth
<string> 基本身份验证,即'user:password'
计算授权标头。¥
auth
<string> Basic authentication i.e.'user:password'
to compute an Authorization header.
-
该实用函数按照 http.request()
和 https.request()
API 的预期将网址对象转换为普通选项对象。
¥This utility function converts a URL object into an ordinary options object as
expected by the http.request()
and https.request()
APIs.
import { urlToHttpOptions } from 'node:url';
const myURL = new URL('https://a:b@測試?abc#foo');
console.log(urlToHttpOptions(myURL));
/*
{
protocol: 'https:',
hostname: 'xn--g6w251d',
hash: '#foo',
search: '?abc',
pathname: '/',
path: '/?abc',
href: 'https://a:b@xn--g6w251d/?abc#foo',
auth: 'a:b'
}
*/
const { urlToHttpOptions } = require('node:url');
const myURL = new URL('https://a:b@測試?abc#foo');
console.log(urlToHttpOptions(myURL));
/*
{
protocol: 'https:',
hostname: 'xn--g6w251d',
hash: '#foo',
search: '?abc',
pathname: '/',
path: '/?abc',
href: 'https://a:b@xn--g6w251d/?abc#foo',
auth: 'a:b'
}
*/
旧版 URL API#
¥Legacy URL API
¥Stability: 3 - Legacy: Use the WHATWG URL API instead.
旧版 urlObject
#
¥Legacy urlObject
¥Stability: 3 - Legacy: Use the WHATWG URL API instead.
旧版的 urlObject
(require('node:url').Url
或 import { Url } from 'node:url'
)由 url.parse()
函数创建和返回。
¥The legacy urlObject
(require('node:url').Url
or
import { Url } from 'node:url'
) is
created and returned by the url.parse()
function.
urlObject.auth
#
auth
属性是 URL 的用户名和密码部分,也称为用户信息。此字符串子集跟在 protocol
和双斜杠(如果存在)之后,并在 host
组件之前,由 @
分隔。该字符串要么是用户名,要么是由 :
分隔的用户名和密码。
¥The auth
property is the username and password portion of the URL, also
referred to as userinfo. This string subset follows the protocol
and
double slashes (if present) and precedes the host
component, delimited by @
.
The string is either the username, or it is the username and password separated
by :
.
例如:'user:pass'
。
¥For example: 'user:pass'
.
urlObject.hash
#
hash
属性是网址的片段标识符部分,包括前导 #
字符。
¥The hash
property is the fragment identifier portion of the URL including the
leading #
character.
例如:'#hash'
。
¥For example: '#hash'
.
urlObject.host
#
host
属性是网址的完整小写主机部分,包括 port
(如果指定)。
¥The host
property is the full lower-cased host portion of the URL, including
the port
if specified.
例如:'sub.example.com:8080'
。
¥For example: 'sub.example.com:8080'
.
urlObject.hostname
#
hostname
属性是 host
组件的小写主机名部分,不包括 port
。
¥The hostname
property is the lower-cased host name portion of the host
component without the port
included.
例如:'sub.example.com'
。
¥For example: 'sub.example.com'
.
urlObject.href
#
href
属性是将 protocol
和 host
组件都转换为小写的完整网址字符串。
¥The href
property is the full URL string that was parsed with both the
protocol
and host
components converted to lower-case.
例如:'http://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash'
。
¥For example: 'http://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash'
.
urlObject.path
#
path
属性是 pathname
和 search
组件的串联。
¥The path
property is a concatenation of the pathname
and search
components.
例如:'/p/a/t/h?query=string'
。
¥For example: '/p/a/t/h?query=string'
.
不执行 path
的解码。
¥No decoding of the path
is performed.
urlObject.pathname
#
pathname
属性包含网址的整个路径部分。这是 host
(包括 port
)之后和 query
或 hash
组件开始之前的所有内容,由 ASCII 问号 (?
) 或哈希 (#
) 字符分隔。
¥The pathname
property consists of the entire path section of the URL. This
is everything following the host
(including the port
) and before the start
of the query
or hash
components, delimited by either the ASCII question
mark (?
) or hash (#
) characters.
例如:'/p/a/t/h'
。
¥For example: '/p/a/t/h'
.
不执行路径字符串的解码。
¥No decoding of the path string is performed.
urlObject.port
#
port
属性是 host
组件的数字端口部分。
¥The port
property is the numeric port portion of the host
component.
例如:'8080'
。
¥For example: '8080'
.
urlObject.protocol
#
protocol
属性标识网址的小写协议方案。
¥The protocol
property identifies the URL's lower-cased protocol scheme.
例如:'http:'
。
¥For example: 'http:'
.
urlObject.query
#
query
属性要么是不带前导 ASCII 问号 (?
) 的查询字符串,要么是 querystring
模块的 parse()
方法返回的对象。query
属性是字符串还是对象由传给 url.parse()
的 parseQueryString
参数决定。
¥The query
property is either the query string without the leading ASCII
question mark (?
), or an object returned by the querystring
module's
parse()
method. Whether the query
property is a string or object is
determined by the parseQueryString
argument passed to url.parse()
.
例如:'query=string'
或 {'query': 'string'}
。
¥For example: 'query=string'
or {'query': 'string'}
.
如果作为字符串返回,则不执行查询字符串的解码。如果作为对象返回,则键和值都会被解码。
¥If returned as a string, no decoding of the query string is performed. If returned as an object, both keys and values are decoded.
urlObject.search
#
search
属性由 URL 的整个 "请求参数" 部分组成,包括前导 ASCII 问号 (?
) 字符。
¥The search
property consists of the entire "query string" portion of the
URL, including the leading ASCII question mark (?
) character.
例如:'?query=string'
。
¥For example: '?query=string'
.
不执行查询字符串的解码。
¥No decoding of the query string is performed.
urlObject.slashes
#
如果 protocol
中的冒号后需要两个 ASCII 正斜杠字符 (/
),则 slashes
属性是值为 true
的 boolean
。
¥The slashes
property is a boolean
with a value of true
if two ASCII
forward-slash characters (/
) are required following the colon in the
protocol
.
url.format(urlObject)
#
¥Stability: 3 - Legacy: Use the WHATWG URL API instead.
-
urlObject
<Object> | <string> 网址对象(由url.parse()
返回或以其他方式构造)。如果是字符串,则通过将其传给url.parse()
将其转换为对象。¥
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()
.
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 toresult
. -
否则,如果
urlObject.protocol
不是undefined
并且不是字符串,则抛出Error
。¥Otherwise, if
urlObject.protocol
is notundefined
and is not a string, anError
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 toresult
. -
如果以下任一条件为真,则字面字符串
//
将附加到result
:¥If either of the following conditions is true, then the literal string
//
will be appended toresult
:-
urlObject.slashes
属性为真;¥
urlObject.slashes
property is true; -
urlObject.protocol
以http
、https
、ftp
、gopher
或file
开头;¥
urlObject.protocol
begins withhttp
,https
,ftp
,gopher
, orfile
;
-
-
如果
urlObject.auth
属性的值为真,并且urlObject.host
或urlObject.hostname
不是undefined
,则urlObject.auth
的值将被强制转换为字符串并附加到result
后跟字面串@
。¥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@
. -
如果
urlObject.host
属性为undefined
,则:¥If the
urlObject.host
property isundefined
then:-
如果
urlObject.hostname
是字符串,则将其附加到result
。¥If the
urlObject.hostname
is a string, it is appended toresult
. -
否则,如果
urlObject.hostname
不是undefined
并且不是字符串,则抛出Error
。¥Otherwise, if
urlObject.hostname
is notundefined
and is not a string, anError
is thrown. -
如果
urlObject.port
属性值为真,并且urlObject.hostname
不是undefined
:¥If the
urlObject.port
property value is truthy, andurlObject.hostname
is notundefined
:-
字面量字符串
:
附加到result
,并且¥The literal string
:
is appended toresult
, and -
urlObject.port
的值被强制转换为字符串并附加到result
。¥The value of
urlObject.port
is coerced to a string and appended toresult
.
-
-
-
否则,如果
urlObject.host
属性值为真,则将urlObject.host
的值强制转换为字符串并附加到result
。¥Otherwise, if the
urlObject.host
property value is truthy, the value ofurlObject.host
is coerced to a string and appended toresult
. -
如果
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 toresult
. -
urlObject.pathname
的值附加到result
。¥The value of
urlObject.pathname
is appended toresult
.
-
-
否则,如果
urlObject.pathname
不是undefined
并且不是字符串,则抛出Error
。¥Otherwise, if
urlObject.pathname
is notundefined
and is not a string, anError
is thrown. -
如果
urlObject.search
属性是undefined
并且如果urlObject.query
属性是Object
,则字面串?
附加到result
,然后是调用querystring
模块的stringify()
方法的输出,并传入urlObject.query
的值。¥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
. -
否则,如果
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 toresult
. -
urlObject.search
的值附加到result
。¥The value of
urlObject.search
is appended toresult
.
-
-
否则,如果
urlObject.search
不是undefined
并且不是字符串,则抛出Error
。¥Otherwise, if
urlObject.search
is notundefined
and is not a string, anError
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 toresult
. -
urlObject.hash
的值附加到result
。¥The value of
urlObject.hash
is appended toresult
.
-
-
否则,如果
urlObject.hash
属性不是undefined
并且不是字符串,则抛出Error
。¥Otherwise, if the
urlObject.hash
property is notundefined
and is not a string, anError
is thrown. -
result
返回。¥
result
is returned.
url.parse(urlString[, parseQueryString[, slashesDenoteHost]])
#
¥Stability: 0 - Deprecated: Use the WHATWG URL API instead.
-
urlString
<string> 要解析的 URL 字符串。¥
urlString
<string> The URL string to parse. -
parseQueryString
<boolean> 如果为true
,则query
属性将始终设置为querystring
模块的parse()
方法返回的对象。如果为false
,则返回的网址对象上的query
属性将是未解析、未解码的字符串。默认值:false
。¥
parseQueryString
<boolean> Iftrue
, thequery
property will always be set to an object returned by thequerystring
module'sparse()
method. Iffalse
, thequery
property on the returned URL object will be an unparsed, undecoded string. Default:false
. -
slashesDenoteHost
<boolean> 如果为true
,则字面串//
之后和下一个/
之前的第一个令牌将被解释为host
。例如,给定//foo/bar
,结果将是{host: 'foo', pathname: '/bar'}
而不是{pathname: '//foo/bar'}
。默认值:false
。¥
slashesDenoteHost
<boolean> Iftrue
, the first token after the literal string//
and preceding the next/
will be interpreted as thehost
. For instance, given//foo/bar
, the result would be{host: 'foo', pathname: '/bar'}
rather than{pathname: '//foo/bar'}
. Default:false
.
url.parse()
方法接受网址字符串,解析并返回网址对象。
¥The url.parse()
method takes a URL string, parses it, and returns a URL
object.
如果 urlString
不是字符串,则抛出 TypeError
。
¥A TypeError
is thrown if urlString
is not a string.
如果 auth
属性存在但无法解码,则抛出 URIError
。
¥A URIError
is thrown if the auth
property is present but cannot be decoded.
url.parse()
使用一种宽松的、非标准的算法来解析 URL 字符串。它很容易出现安全问题,例如 主机名欺骗 和用户名和密码的不正确处理。不要使用不受信任的输入。不针对 url.parse()
漏洞发布 CVE。改用 WHATWG URL API。
¥url.parse()
uses a lenient, non-standard algorithm for parsing URL
strings. It is prone to security issues such as host name spoofing
and incorrect handling of usernames and passwords. Do not use with untrusted
input. CVEs are not issued for url.parse()
vulnerabilities. Use the
WHATWG URL API instead.
url.resolve(from, to)
#
¥Stability: 3 - Legacy: Use the WHATWG URL API instead.
-
from
<string> 如果to
是相对的 URL,则使用的基本的 URL。¥
from
<string> The base URL to use ifto
is a relative URL. -
to
<string> 要解析的目标 URL。¥
to
<string> The target URL to resolve.
url.resolve()
方法以类似于 Web 浏览器解析锚标记的方式解析相对于基本 URL 的目标 URL。
¥The url.resolve()
method resolves a target URL relative to a base URL in a
manner similar to that of a web browser resolving an anchor tag.
const url = require('node:url');
url.resolve('/one/two/three', 'four'); // '/one/two/four'
url.resolve('http://example.com/', '/one'); // 'http://example.com/one'
url.resolve('http://example.com/one', '/two'); // 'http://example.com/two'
使用 WHATWG URL API 实现相同的结果:
¥To achieve the same result using the WHATWG URL API:
function resolve(from, to) {
const resolvedUrl = new URL(to, new URL(from, 'resolve://'));
if (resolvedUrl.protocol === 'resolve:') {
// `from` is a relative URL.
const { pathname, search, hash } = resolvedUrl;
return pathname + search + hash;
}
return resolvedUrl.toString();
}
resolve('/one/two/three', 'four'); // '/one/two/four'
resolve('http://example.com/', '/one'); // 'http://example.com/one'
resolve('http://example.com/one', '/two'); // 'http://example.com/two'
URL 中的百分比编码#
¥Percent-encoding in URLs
网址只允许包含一定范围的字符。任何超出该范围的字符都必须进行编码。这些字符的编码方式以及要编码的字符完全取决于字符在网址结构中的位置。
¥URLs are permitted to only contain a certain range of characters. Any character falling outside of that range must be encoded. How such characters are encoded, and which characters to encode depends entirely on where the character is located within the structure of the URL.
旧版 API#
¥Legacy API
在旧版 API 中,空格 (' '
) 和以下字符将在网址对象的属性中自动转义:
¥Within the Legacy API, spaces (' '
) and the following characters will be
automatically escaped in the properties of URL objects:
< > " ` \r \n \t { } | \ ^ '
例如,ASCII 空格字符 (' '
) 被编码为 %20
。ASCII 正斜杠 (/
) 字符编码为 %3C
。
¥For example, the ASCII space character (' '
) is encoded as %20
. The ASCII
forward slash (/
) character is encoded as %3C
.
WHATWG API#
WHATWG URL 标准 使用比 Legacy API 使用的方法更具选择性和更细粒度的方法来选择编码字符。
¥The WHATWG URL Standard uses a more selective and fine grained approach to selecting encoded characters than that used by the Legacy API.
WHATWG 算法定义了四个 "百分比编码集",它们描述了必须进行百分比编码的字符范围:
¥The WHATWG algorithm defines four "percent-encode sets" that describe ranges of characters that must be percent-encoded:
-
C0 控制百分比编码集包括 U+0000 到 U+001F(含)范围内的代码点以及大于 U+007E (~) 的所有代码点。
¥The C0 control percent-encode set includes code points in range U+0000 to U+001F (inclusive) and all code points greater than U+007E (~).
-
片段百分比编码集包括 C0 控制百分比编码集和代码点 U+0020 SPACE、U+0022 (")、U+003C (<)、U+003E (>) 和 U+0060 (`) 。
¥The fragment percent-encode set includes the C0 control percent-encode set and code points U+0020 SPACE, U+0022 ("), U+003C (<), U+003E (>), and U+0060 (`).
-
路径百分比编码集包括 C0 控制百分比编码集和代码点 U+0020 SPACE、U+0022 (")、U+0023 (#)、U+003C (<)、U+003E (>)、 U+003F (?)、U+0060 (`)、U+007B ({), and U+007D (})。
¥The path percent-encode set includes the C0 control percent-encode set and code points U+0020 SPACE, U+0022 ("), U+0023 (#), U+003C (<), U+003E (>), U+003F (?), U+0060 (`), U+007B ({), and U+007D (}).
-
用户信息编码集包括路径百分比编码集和代码点 U+002F (/)、U+003A (:)、U+003B (;)、U+003D (=)、U+0040 (@)、U +005B ([) 至 U+005E(^) 和 U+007C (|)。
¥The userinfo encode set includes the path percent-encode set and code points U+002F (/), U+003A (:), U+003B (;), U+003D (=), U+0040 (@), U+005B ([) to U+005E(^), and U+007C (|).
userinfo 百分比编码集专门用于在 URL 中编码的用户名和密码。路径百分比编码集用于大多数 URL 的路径。片段百分比编码集用于 URL 片段。C0 控制百分比编码集用于某些特定条件下的主机和路径,以及所有其他情况。
¥The userinfo percent-encode set is used exclusively for username and passwords encoded within the URL. The path percent-encode set is used for the path of most URLs. The fragment percent-encode set is used for URL fragments. The C0 control percent-encode set is used for host and path under certain specific conditions, in addition to all other cases.
当主机名中出现非 ASCII 字符时,主机名将使用 Punycode 算法进行编码。但是请注意,主机名可能同时包含 Punycode 编码字符和百分比编码字符:
¥When non-ASCII characters appear within a host name, the host name is encoded using the Punycode algorithm. Note, however, that a host name may contain both Punycode encoded and percent-encoded characters:
const myURL = new URL('https://%CF%80.example.com/foo');
console.log(myURL.href);
// Prints https://xn--1xa.example.com/foo
console.log(myURL.origin);
// Prints https://xn--1xa.example.com