mirror of
https://github.com/nodejs/node.git
synced 2026-10-14 10:26:26 -04:00
doc: add basic documentation for WHATWG URL API
PR-URL: https://github.com/nodejs/node/pull/10620 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Michal Zasso <targos@protonmail.com> Reviewed-By: Timothy Gu <timothygu99@gmail.com>
This commit is contained in:
James M Snell committed
1 parent
0c712b6743
commit
4757ddcce1
1 file changed
+458
Regular → Executable
+458
@@ -250,7 +250,465 @@ properties of URL objects:
|
||||
For example, the ASCII space character (`' '`) is encoded as `%20`. The ASCII
|
||||
forward slash (`/`) character is encoded as `%3C`.
|
||||
|
||||
## The WHATWG URL API
|
||||
|
||||
> Stability: 1 - Experimental
|
||||
|
||||
The `url` module provides an *experimental* implementation of the
|
||||
[WHATWG URL Standard][] as an alternative to the existing `url.parse()` API.
|
||||
|
||||
```js
|
||||
const URL = require('url').URL;
|
||||
const myURL = new URL('https://example.org/foo');
|
||||
|
||||
console.log(myURL.href); // https://example.org/foo
|
||||
console.log(myURL.protocol); // https:
|
||||
console.log(myURL.hostname); // example.org
|
||||
console.log(myURL.pathname); // /foo
|
||||
```
|
||||
|
||||
*Note*: Using the `delete` keyword (e.g. `delete myURL.protocol`,
|
||||
`delete myURL.pathname`, etc) has no effect but will still return `true`.
|
||||
|
||||
### Class: URL
|
||||
#### Constructor: new URL(input[, base])
|
||||
|
||||
* `input` {String} The input URL to parse
|
||||
* `base` {String | URL} The base URL to resolve against if the `input` is not
|
||||
absolute.
|
||||
|
||||
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)`.
|
||||
|
||||
```js
|
||||
const myURL = new URL('/foo', 'https://example.org/');
|
||||
// https://example.org/foo
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```js
|
||||
const myURL = new URL({toString: () => 'https://example.org/'});
|
||||
// https://example.org/
|
||||
```
|
||||
|
||||
Unicode characters appearing within the hostname of `input` will be
|
||||
automatically converted to ASCII using the [Punycode][] algorithm.
|
||||
|
||||
```js
|
||||
const myURL = new URL('https://你好你好');
|
||||
// https://xn--6qqa088eba
|
||||
```
|
||||
|
||||
Additional [examples of parsed URLs][] may be found in the WHATWG URL Standard.
|
||||
|
||||
#### url.hash
|
||||
|
||||
Gets and sets the fragment portion of the URL.
|
||||
|
||||
```js
|
||||
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
|
||||
```
|
||||
|
||||
Invalid URL characters included in the value assigned to the `hash` property
|
||||
are [percent-encoded](#whatwg-percent-encoding). Note that 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.
|
||||
|
||||
```js
|
||||
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
|
||||
```
|
||||
|
||||
Invalid host values assigned to the `host` property are ignored.
|
||||
|
||||
#### url.hostname
|
||||
|
||||
Gets and sets the hostname portion of the URL. The key difference between
|
||||
`url.host` and `url.hostname` is that `url.hostname` does *not* include the
|
||||
port.
|
||||
|
||||
```js
|
||||
const myURL = new URL('https://example.org:81/foo');
|
||||
console.log(myURL.hostname);
|
||||
// Prints example.org
|
||||
|
||||
myURL.hostname = 'example.com:82';
|
||||
console.log(myURL.href);
|
||||
// Prints https://example.com:81/foo
|
||||
```
|
||||
|
||||
Invalid hostname values assigned to the `hostname` property are ignored.
|
||||
|
||||
#### url.href
|
||||
|
||||
Gets and sets the serialized URL.
|
||||
|
||||
```js
|
||||
const myURL = new URL('https://example.org/foo');
|
||||
console.log(myURL.href);
|
||||
// Prints https://example.org/foo
|
||||
|
||||
myURL.href = 'https://example.com/bar'
|
||||
// Prints https://example.com/bar
|
||||
```
|
||||
|
||||
Setting the value of the `href` 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.
|
||||
|
||||
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. Unicode characters that
|
||||
may be contained within the hostname will be encoded as-is without [Punycode][]
|
||||
encoding.
|
||||
|
||||
```js
|
||||
const myURL = new URL('https://example.org/foo/bar?baz');
|
||||
console.log(myURL.origin);
|
||||
// Prints https://example.org
|
||||
```
|
||||
|
||||
```js
|
||||
const idnURL = new URL('https://你好你好');
|
||||
console.log(idnURL.origin);
|
||||
// Prints https://你好你好
|
||||
|
||||
console.log(idnURL.hostname);
|
||||
// Prints xn--6qqa088eba
|
||||
```
|
||||
|
||||
#### url.password
|
||||
|
||||
Gets and sets the password portion of the URL.
|
||||
|
||||
```js
|
||||
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
|
||||
```
|
||||
|
||||
Invalid URL characters included in the value assigned to the `password` property
|
||||
are [percent-encoded](#whatwg-percent-encoding). Note that 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.
|
||||
|
||||
```js
|
||||
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
|
||||
```
|
||||
|
||||
Invalid URL characters included in the value assigned to the `pathname`
|
||||
property are [percent-encoded](#whatwg-percent-encoding). Note that 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. When getting the port, the value
|
||||
is returned as a String.
|
||||
|
||||
```js
|
||||
const myURL = new URL('https://example.org:8888');
|
||||
console.log(myURL.port);
|
||||
// Prints 8888
|
||||
|
||||
myURL.port = 1234;
|
||||
console.log(myURL.href);
|
||||
// Prints https://example.org:1234
|
||||
```
|
||||
|
||||
The port value may be set as either a number or as 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 (`''`).
|
||||
|
||||
Invalid URL port values assigned to the `port` property are ignored.
|
||||
|
||||
#### url.protocol
|
||||
|
||||
Gets and sets the protocol portion of the URL.
|
||||
|
||||
```js
|
||||
const myURL = new URL('https://example.org');
|
||||
console.log(myURL.protocol);
|
||||
// Prints http:
|
||||
|
||||
myURL.protocol = 'ftp';
|
||||
console.log(myURL.href);
|
||||
// Prints ftp://example.org
|
||||
```
|
||||
|
||||
Invalid URL protocol values assigned to the `protocol` property are ignored.
|
||||
|
||||
#### url.search
|
||||
|
||||
Gets and sets the serialized query portion of the URL.
|
||||
|
||||
```js
|
||||
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
|
||||
```
|
||||
|
||||
Any invalid URL characters appearing in the value assigned the `search`
|
||||
property will be [percent-encoded](#whatwg-percent-encoding). Note that the
|
||||
selection of which characters to percent-encode may vary somewhat from what the
|
||||
[`url.parse()`][] and [`url.format()`][] methods would produce.
|
||||
|
||||
#### url.searchParams
|
||||
|
||||
Gets a [`URLSearchParams`](#url_class_urlsearchparams) object representing the
|
||||
query parameters of the URL.
|
||||
|
||||
#### url.username
|
||||
|
||||
Gets and sets the username portion of the URL.
|
||||
|
||||
```js
|
||||
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
|
||||
```
|
||||
|
||||
Any invalid URL characters appearing in the value assigned the `username`
|
||||
property will be [percent-encoded](#whatwg-percent-encoding). Note that the
|
||||
selection of which characters to percent-encode may vary somewhat from what the
|
||||
[`url.parse()`][] and [`url.format()`][] methods would produce.
|
||||
|
||||
#### url.toString()
|
||||
|
||||
The `toString()` method on the `URL` object returns the serialized URL. The
|
||||
value returned is equivalent to that of `url.href`.
|
||||
|
||||
### Class: URLSearchParams
|
||||
|
||||
The `URLSearchParams` object provides read and write access to the query of a
|
||||
`URL`.
|
||||
|
||||
```js
|
||||
const URL = require('url').URL;
|
||||
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
|
||||
```
|
||||
|
||||
#### Constructor: new URLSearchParams([init])
|
||||
|
||||
* `init` {String} The URL query
|
||||
|
||||
#### urlSearchParams.append(name, value)
|
||||
|
||||
* `name` {String}
|
||||
* `value` {String}
|
||||
|
||||
Append a new name-value pair to the query string.
|
||||
|
||||
#### urlSearchParams.delete(name)
|
||||
|
||||
* `name` {String}
|
||||
|
||||
Remove all name-value pairs whose name is `name`.
|
||||
|
||||
#### urlSearchParams.entries()
|
||||
|
||||
* Returns: {Iterator}
|
||||
|
||||
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`.
|
||||
|
||||
Alias for `urlSearchParams\[\@\@iterator\]()`.
|
||||
|
||||
#### urlSearchParams.forEach(fn)
|
||||
|
||||
* `fn` {Function} Function invoked for each name-value pair in the query.
|
||||
|
||||
Iterates over each name-value pair in the query and invokes the given function.
|
||||
|
||||
```js
|
||||
const URL = require('url').URL;
|
||||
const myURL = new URL('https://example.org/?a=b&c=d');
|
||||
myURL.searchParams.forEach((value, name) => {
|
||||
console.log(name, value);
|
||||
});
|
||||
```
|
||||
|
||||
#### urlSearchParams.get(name)
|
||||
|
||||
* `name` {String}
|
||||
* Returns: {String} or `null` if there is no name-value pair with the given
|
||||
`name`.
|
||||
|
||||
Returns the value of the first name-value pair whose name is `name`.
|
||||
|
||||
#### urlSearchParams.getAll(name)
|
||||
|
||||
* `name` {String}
|
||||
* Returns: {Array}
|
||||
|
||||
Returns the values of all name-value pairs whose name is `name`.
|
||||
|
||||
#### urlSearchParams.has(name)
|
||||
|
||||
* `name` {String}
|
||||
* Returns: {Boolean}
|
||||
|
||||
Returns `true` if there is at least one name-value pair whose name is `name`.
|
||||
|
||||
#### urlSearchParams.keys()
|
||||
|
||||
* Returns: {Iterator}
|
||||
|
||||
Returns an ES6 Iterator over the names of each name-value pair.
|
||||
|
||||
#### urlSearchParams.set(name, value)
|
||||
|
||||
* `name` {String}
|
||||
* `value` {String}
|
||||
|
||||
Remove any existing name-value pairs whose name is `name` and append a new
|
||||
name-value pair.
|
||||
|
||||
#### urlSearchParams.toString()
|
||||
|
||||
* Returns: {String}
|
||||
|
||||
Returns the search parameters serialized as a URL-encoded string.
|
||||
|
||||
#### urlSearchParams.values()
|
||||
|
||||
* Returns: {Iterator}
|
||||
|
||||
Returns an ES6 Iterator over the values of each name-value pair.
|
||||
|
||||
#### urlSearchParams\[\@\@iterator\]()
|
||||
|
||||
* Returns: {Iterator}
|
||||
|
||||
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`.
|
||||
|
||||
Alias for `urlSearchParams.entries()`.
|
||||
|
||||
### require('url').domainToAscii(domain)
|
||||
|
||||
* `domain` {String}
|
||||
* Returns: {String}
|
||||
|
||||
Returns the [Punycode][] ASCII serialization of the `domain`.
|
||||
|
||||
*Note*: The `require('url').domainToAscii()` method is introduced as part of
|
||||
the new `URL` implementation but is not part of the WHATWG URL standard.
|
||||
|
||||
### require('url').domainToUnicode(domain)
|
||||
|
||||
* `domain` {String}
|
||||
* Returns: {String}
|
||||
|
||||
Returns the Unicode serialization of the `domain`.
|
||||
|
||||
*Note*: The `require('url').domainToUnicode()` API is introduced as part of the
|
||||
the new `URL` implementation but is not part of the WHATWG URL standard.
|
||||
|
||||
<a id="whatwg-percent-encoding"></a>
|
||||
### Percent-Encoding in the WHATWG URL Standard
|
||||
|
||||
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. The WHATWG URL Standard uses a more
|
||||
selective and fine grained approach to selecting encoded characters than that
|
||||
used by the older [`url.parse()`][] and [`url.format()`][] methods.
|
||||
|
||||
The WHATWG algorithm defines three "encoding sets" that describe ranges of
|
||||
characters that must be percent-encoded:
|
||||
|
||||
* The *simple encode set* includes code points in range U+0000 to U+001F
|
||||
(inclusive) and all code points greater than U+007E.
|
||||
|
||||
* The *default encode set* includes the *simple encode set* and code points
|
||||
U+0020, U+0022, U+0023, U+003C, U+003E, U+003F, U+0060, U+007B, and U+007D.
|
||||
|
||||
* The *userinfo encode set* includes the *default encode set* and code points
|
||||
U+002F, U+003A, U+003B, U+003D, U+0040, U+005B, U+005C, U+005D, U+005E, and
|
||||
U+007C.
|
||||
|
||||
The *simple encode set* is used primary for URL fragments and certain specific
|
||||
conditions for the path. The *userinfo encode set* is used specifically for
|
||||
username and passwords encoded within the URL. The *default encode set* is used
|
||||
for all other cases.
|
||||
|
||||
When non-ASCII characters appear within a hostname, the hostname is encoded
|
||||
using the [Punycode][] algorithm. Note, however, that a hostname *may* contain
|
||||
*both* Punycode encoded and percent-encoded characters. For example:
|
||||
|
||||
```js
|
||||
const URL = require('url').URL;
|
||||
const myURL = new URL('https://%CF%80.com/foo');
|
||||
console.log(myURL.href);
|
||||
// Prints https://xn--1xa.com/foo
|
||||
console.log(myURL.origin);
|
||||
// Prints https://π.com
|
||||
```
|
||||
|
||||
|
||||
[`Error`]: errors.html#errors_class_error
|
||||
[`querystring`]: querystring.html
|
||||
[`TypeError`]: errors.html#errors_class_typeerror
|
||||
[WHATWG URL Standard]: https://url.spec.whatwg.org/
|
||||
[examples of parsed URLs]: https://url.spec.whatwg.org/#example-url-parsing
|
||||
[`url.parse()`]: #url_url_parse_urlstring_parsequerystring_slashesdenotehost
|
||||
[`url.format()`]: #url_url_format_urlobject
|
||||
[Punycode]: https://tools.ietf.org/html/rfc5891#section-4.4
|
||||
Reference in new issue
Block a user