doc: restructure url.md
PR-URL: https://github.com/nodejs/node/pull/12710 Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Daijiro Wachi <daijiro.wachi@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
This commit is contained in:
parent
10754b60d0
commit
dbbe1faf30
744
doc/api/url.md
744
doc/api/url.md
@ -15,371 +15,18 @@ A URL string is a structured string containing multiple meaningful components.
|
|||||||
When parsed, a URL object is returned containing properties for each of these
|
When parsed, a URL object is returned containing properties for each of these
|
||||||
components.
|
components.
|
||||||
|
|
||||||
The following details each of the components of a parsed URL. The example
|
The `url` module provides two APIs for working with URLs: a legacy API that is
|
||||||
`'http://user:pass@sub.host.com:8080/p/a/t/h?query=string#hash'` is used to
|
Node.js specific, and a newer API that implements the same
|
||||||
illustrate each.
|
[WHATWG URL Standard][] used by web browsers.
|
||||||
|
|
||||||
```txt
|
*Note*: While the Legacy API has not been deprecated, it is maintained solely
|
||||||
┌─────────────────────────────────────────────────────────────────────────────────┐
|
for backwards compatibility with existing applications. New application code
|
||||||
│ href │
|
should use the WHATWG API.
|
||||||
├──────────┬┬───────────┬─────────────────────┬───────────────────────────┬───────┤
|
|
||||||
│ protocol ││ auth │ host │ path │ hash │
|
A comparison between the WHATWG and Legacy APIs is provided below. Above the URL
|
||||||
│ ││ ├──────────────┬──────┼──────────┬────────────────┤ │
|
`'http://user:pass@sub.host.com:8080/p/a/t/h?query=string#hash'`, properties of
|
||||||
│ ││ │ hostname │ port │ pathname │ search │ │
|
an object returned by the legacy `url.parse()` are shown. Below it are
|
||||||
│ ││ │ │ │ ├─┬──────────────┤ │
|
properties of a WHATWG `URL` object.
|
||||||
│ ││ │ │ │ │ │ query │ │
|
|
||||||
" http: // user:pass @ sub.host.com : 8080 /p/a/t/h ? query=string #hash "
|
|
||||||
│ ││ │ │ │ │ │ │ │
|
|
||||||
└──────────┴┴───────────┴──────────────┴──────┴──────────┴─┴──────────────┴───────┘
|
|
||||||
(all spaces in the "" line should be ignored -- they are purely for formatting)
|
|
||||||
```
|
|
||||||
|
|
||||||
### urlObject.auth
|
|
||||||
|
|
||||||
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 an
|
|
||||||
ASCII "at sign" (`@`). The format of the string is `{username}[:{password}]`,
|
|
||||||
with the `[:{password}]` portion being optional.
|
|
||||||
|
|
||||||
For example: `'user:pass'`
|
|
||||||
|
|
||||||
### urlObject.hash
|
|
||||||
|
|
||||||
The `hash` property consists of the "fragment" portion of the URL including
|
|
||||||
the leading ASCII hash (`#`) character.
|
|
||||||
|
|
||||||
For example: `'#hash'`
|
|
||||||
|
|
||||||
### urlObject.host
|
|
||||||
|
|
||||||
The `host` property is the full lower-cased host portion of the URL, including
|
|
||||||
the `port` if specified.
|
|
||||||
|
|
||||||
For example: `'sub.host.com:8080'`
|
|
||||||
|
|
||||||
### urlObject.hostname
|
|
||||||
|
|
||||||
The `hostname` property is the lower-cased host name portion of the `host`
|
|
||||||
component *without* the `port` included.
|
|
||||||
|
|
||||||
For example: `'sub.host.com'`
|
|
||||||
|
|
||||||
### urlObject.href
|
|
||||||
|
|
||||||
The `href` property is the full URL string that was parsed with both the
|
|
||||||
`protocol` and `host` components converted to lower-case.
|
|
||||||
|
|
||||||
For example: `'http://user:pass@sub.host.com:8080/p/a/t/h?query=string#hash'`
|
|
||||||
|
|
||||||
### urlObject.path
|
|
||||||
|
|
||||||
The `path` property is a concatenation of the `pathname` and `search`
|
|
||||||
components.
|
|
||||||
|
|
||||||
For example: `'/p/a/t/h?query=string'`
|
|
||||||
|
|
||||||
No decoding of the `path` is performed.
|
|
||||||
|
|
||||||
### urlObject.pathname
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
For example `'/p/a/t/h'`
|
|
||||||
|
|
||||||
No decoding of the path string is performed.
|
|
||||||
|
|
||||||
### urlObject.port
|
|
||||||
|
|
||||||
The `port` property is the numeric port portion of the `host` component.
|
|
||||||
|
|
||||||
For example: `'8080'`
|
|
||||||
|
|
||||||
### urlObject.protocol
|
|
||||||
|
|
||||||
The `protocol` property identifies the URL's lower-cased protocol scheme.
|
|
||||||
|
|
||||||
For example: `'http:'`
|
|
||||||
|
|
||||||
### urlObject.query
|
|
||||||
|
|
||||||
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()`.
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
The `search` property consists of the entire "query string" portion of the
|
|
||||||
URL, including the leading ASCII question mark (`?`) character.
|
|
||||||
|
|
||||||
For example: `'?query=string'`
|
|
||||||
|
|
||||||
No decoding of the query string is performed.
|
|
||||||
|
|
||||||
### urlObject.slashes
|
|
||||||
|
|
||||||
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.domainToASCII(domain)
|
|
||||||
<!-- YAML
|
|
||||||
added: v7.4.0
|
|
||||||
-->
|
|
||||||
|
|
||||||
> Stability: 1 - Experimental
|
|
||||||
|
|
||||||
* `domain` {string}
|
|
||||||
* Returns: {string}
|
|
||||||
|
|
||||||
Returns the [Punycode][] ASCII serialization of the `domain`. If `domain` is an
|
|
||||||
invalid domain, the empty string is returned.
|
|
||||||
|
|
||||||
It performs the inverse operation to [`url.domainToUnicode()`][].
|
|
||||||
|
|
||||||
```js
|
|
||||||
const url = require('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)
|
|
||||||
<!-- YAML
|
|
||||||
added: v7.4.0
|
|
||||||
-->
|
|
||||||
|
|
||||||
> Stability: 1 - Experimental
|
|
||||||
|
|
||||||
* `domain` {string}
|
|
||||||
* Returns: {string}
|
|
||||||
|
|
||||||
Returns the Unicode serialization of the `domain`. If `domain` is an invalid
|
|
||||||
domain, the empty string is returned.
|
|
||||||
|
|
||||||
It performs the inverse operation to [`url.domainToASCII()`][].
|
|
||||||
|
|
||||||
```js
|
|
||||||
const url = require('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.format(urlObject)
|
|
||||||
<!-- YAML
|
|
||||||
added: v0.1.25
|
|
||||||
-->
|
|
||||||
|
|
||||||
* `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()`.
|
|
||||||
|
|
||||||
The `url.format()` method returns a formatted URL string derived from
|
|
||||||
`urlObject`.
|
|
||||||
|
|
||||||
If `urlObject` is not an object or a string, `url.parse()` 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 to `result`.
|
|
||||||
* Otherwise, if `urlObject.protocol` is not `undefined` and is not a string, an
|
|
||||||
[`Error`][] is thrown.
|
|
||||||
* For all string values of `urlObject.protocol` that *do not end* with an ASCII
|
|
||||||
colon (`:`) character, the literal string `:` will be appended to `result`.
|
|
||||||
* If either of the following conditions is true, then the literal string `//`
|
|
||||||
will be appended to `result`:
|
|
||||||
* `urlObject.slashes` property is true;
|
|
||||||
* `urlObject.protocol` begins with `http`, `https`, `ftp`, `gopher`, or
|
|
||||||
`file`;
|
|
||||||
* 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 `@`.
|
|
||||||
* If the `urlObject.host` property is `undefined` then:
|
|
||||||
* If the `urlObject.hostname` is a string, it is appended to `result`.
|
|
||||||
* Otherwise, if `urlObject.hostname` is not `undefined` and is not a string,
|
|
||||||
an [`Error`][] is thrown.
|
|
||||||
* If the `urlObject.port` property value is truthy, and `urlObject.hostname`
|
|
||||||
is not `undefined`:
|
|
||||||
* The literal string `:` is appended to `result`, and
|
|
||||||
* The value of `urlObject.port` is coerced to a string and appended to
|
|
||||||
`result`.
|
|
||||||
* Otherwise, if the `urlObject.host` property value is truthy, the value of
|
|
||||||
`urlObject.host` is coerced to a string and appended to `result`.
|
|
||||||
* 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 to `result`.
|
|
||||||
* The value of `urlObject.pathname` is appended to `result`.
|
|
||||||
* Otherwise, if `urlObject.pathname` is not `undefined` and is not a string, an
|
|
||||||
[`Error`][] is thrown.
|
|
||||||
* 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`.
|
|
||||||
* 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 to `result`.
|
|
||||||
* The value of `urlObject.search` is appended to `result`.
|
|
||||||
* Otherwise, if `urlObject.search` is not `undefined` and is not a string, an
|
|
||||||
[`Error`][] 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 to `result`.
|
|
||||||
* The value of `urlObject.hash` is appended to `result`.
|
|
||||||
* Otherwise, if the `urlObject.hash` property is not `undefined` and is not a
|
|
||||||
string, an [`Error`][] is thrown.
|
|
||||||
* `result` is returned.
|
|
||||||
|
|
||||||
## url.format(URL[, options])
|
|
||||||
<!-- YAML
|
|
||||||
added: v7.6.0
|
|
||||||
-->
|
|
||||||
|
|
||||||
* `URL` {URL} A [WHATWG URL][] object
|
|
||||||
* `options` {Object}
|
|
||||||
* `auth` {boolean} `true` if the serialized URL string should include the
|
|
||||||
username and password, `false` otherwise. Defaults to `true`.
|
|
||||||
* `fragment` {boolean} `true` if the serialized URL string should include the
|
|
||||||
fragment, `false` otherwise. Defaults to `true`.
|
|
||||||
* `search` {boolean} `true` if the serialized URL string should include the
|
|
||||||
search query, `false` otherwise. Defaults to `true`.
|
|
||||||
* `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. Defaults to `false`.
|
|
||||||
|
|
||||||
Returns a customizable serialization of a URL String representation of a
|
|
||||||
[WHATWG URL][] object.
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
For example:
|
|
||||||
|
|
||||||
```js
|
|
||||||
const myURL = new URL('https://a:b@你好你好?abc#foo');
|
|
||||||
|
|
||||||
console.log(myURL.href);
|
|
||||||
// Prints https://a:b@xn--6qqa088eba/?abc#foo
|
|
||||||
|
|
||||||
console.log(myURL.toString());
|
|
||||||
// Prints https://a:b@xn--6qqa088eba/?abc#foo
|
|
||||||
|
|
||||||
console.log(url.format(myURL, {fragment: false, unicode: true, auth: false}));
|
|
||||||
// Prints 'https://你好你好?abc'
|
|
||||||
```
|
|
||||||
|
|
||||||
## url.parse(urlString[, parseQueryString[, slashesDenoteHost]])
|
|
||||||
<!-- YAML
|
|
||||||
added: v0.1.25
|
|
||||||
-->
|
|
||||||
|
|
||||||
* `urlString` {string} The URL string to parse.
|
|
||||||
* `parseQueryString` {boolean} If `true`, the `query` property will always
|
|
||||||
be set to an object returned by the [`querystring`][] module's `parse()`
|
|
||||||
method. If `false`, the `query` property on the returned URL object will be an
|
|
||||||
unparsed, undecoded string. Defaults to `false`.
|
|
||||||
* `slashesDenoteHost` {boolean} If `true`, the first token after the literal
|
|
||||||
string `//` and preceding the next `/` will be interpreted as the `host`.
|
|
||||||
For instance, given `//foo/bar`, the result would be
|
|
||||||
`{host: 'foo', pathname: '/bar'}` rather than `{pathname: '//foo/bar'}`.
|
|
||||||
Defaults to `false`.
|
|
||||||
|
|
||||||
The `url.parse()` method takes a URL string, parses it, and returns a URL
|
|
||||||
object.
|
|
||||||
|
|
||||||
A `TypeError` is thrown if `urlString` is not a string.
|
|
||||||
|
|
||||||
A `URIError` is thrown if the `auth` property is present but cannot be decoded.
|
|
||||||
|
|
||||||
## url.resolve(from, to)
|
|
||||||
<!-- YAML
|
|
||||||
added: v0.1.25
|
|
||||||
changes:
|
|
||||||
- version: v6.6.0
|
|
||||||
pr-url: https://github.com/nodejs/node/pull/8215
|
|
||||||
description: The `auth` fields are now kept intact when `from` and `to`
|
|
||||||
refer to the same host.
|
|
||||||
- version: v6.5.0, v4.6.2
|
|
||||||
pr-url: https://github.com/nodejs/node/pull/8214
|
|
||||||
description: The `port` field is copied correctly now.
|
|
||||||
- version: v6.0.0
|
|
||||||
pr-url: https://github.com/nodejs/node/pull/1480
|
|
||||||
description: The `auth` fields is cleared now the `to` parameter
|
|
||||||
contains a hostname.
|
|
||||||
-->
|
|
||||||
|
|
||||||
* `from` {string} The Base URL being resolved against.
|
|
||||||
* `to` {string} The HREF URL being resolved.
|
|
||||||
|
|
||||||
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 HREF.
|
|
||||||
|
|
||||||
For example:
|
|
||||||
|
|
||||||
```js
|
|
||||||
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'
|
|
||||||
```
|
|
||||||
|
|
||||||
## Escaped Characters
|
|
||||||
|
|
||||||
URLs are only permitted to contain a certain range of characters. Spaces (`' '`)
|
|
||||||
and the following characters will be automatically escaped in the
|
|
||||||
properties of URL objects:
|
|
||||||
|
|
||||||
```txt
|
|
||||||
< > " ` \r \n \t { } | \ ^ '
|
|
||||||
```
|
|
||||||
|
|
||||||
For example, the ASCII space character (`' '`) is encoded as `%20`. The ASCII
|
|
||||||
forward slash (`/`) character is encoded as `%3C`.
|
|
||||||
|
|
||||||
## The WHATWG URL API
|
|
||||||
<!-- YAML
|
|
||||||
added: v7.0.0
|
|
||||||
-->
|
|
||||||
|
|
||||||
The `url` module provides an 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`.
|
|
||||||
|
|
||||||
A comparison between this API and `url.parse()` is given below. Above the URL
|
|
||||||
`'http://user:pass@sub.host.com:8080/p/a/t/h?query=string#hash'`, properties of an
|
|
||||||
object returned by `url.parse()` are shown. Below it are properties of a WHATWG
|
|
||||||
`URL` object.
|
|
||||||
|
|
||||||
*Note*: WHATWG URL's `origin` property includes `protocol` and `host`, but not
|
*Note*: WHATWG URL's `origin` property includes `protocol` and `host`, but not
|
||||||
`username` or `password`.
|
`username` or `password`.
|
||||||
@ -393,7 +40,7 @@ object returned by `url.parse()` are shown. Below it are properties of a WHATWG
|
|||||||
│ │ │ │ hostname │ port │ pathname │ search │ │
|
│ │ │ │ hostname │ port │ pathname │ search │ │
|
||||||
│ │ │ │ │ │ ├─┬──────────────┤ │
|
│ │ │ │ │ │ ├─┬──────────────┤ │
|
||||||
│ │ │ │ │ │ │ │ query │ │
|
│ │ │ │ │ │ │ │ query │ │
|
||||||
" http: // user : pass @ sub.host.com : 8080 /p/a/t/h ? query=string #hash "
|
" https: // user : pass @ sub.host.com : 8080 /p/a/t/h ? query=string #hash "
|
||||||
│ │ │ │ │ hostname │ port │ │ │ │
|
│ │ │ │ │ hostname │ port │ │ │ │
|
||||||
│ │ │ │ ├──────────────┴──────┤ │ │ │
|
│ │ │ │ ├──────────────┴──────┤ │ │ │
|
||||||
│ protocol │ │ username │ password │ host │ │ │ │
|
│ protocol │ │ username │ password │ host │ │ │ │
|
||||||
@ -405,6 +52,35 @@ object returned by `url.parse()` are shown. Below it are properties of a WHATWG
|
|||||||
(all spaces in the "" line should be ignored -- they are purely for formatting)
|
(all spaces in the "" line should be ignored -- they are purely for formatting)
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Parsing the URL string using the WHATWG API:
|
||||||
|
|
||||||
|
```js
|
||||||
|
const URL = require('url').URL;
|
||||||
|
const myURL =
|
||||||
|
new URL('https://user:pass@sub.host.com:8080/p/a/t/h?query=string#hash');
|
||||||
|
```
|
||||||
|
|
||||||
|
*Note*: In Web Browsers, the WHATWG `URL` class is a global that is always
|
||||||
|
available. In Node.js, however, the `URL` class must be accessed via
|
||||||
|
`require('url').URL`.
|
||||||
|
|
||||||
|
Parsing the URL string using the Legacy API:
|
||||||
|
|
||||||
|
```js
|
||||||
|
const url = require('url');
|
||||||
|
const myURL =
|
||||||
|
url.parse('https://user:pass@sub.host.com:8080/p/a/t/h?query=string#hash');
|
||||||
|
```
|
||||||
|
|
||||||
|
## The WHATWG URL API
|
||||||
|
<!-- YAML
|
||||||
|
added: v7.0.0
|
||||||
|
-->
|
||||||
|
|
||||||
|
*Note*: Using the `delete` keyword on `URL` objects (e.g.
|
||||||
|
`delete myURL.protocol`, `delete myURL.pathname`, etc) has no effect but will
|
||||||
|
still return `true`.
|
||||||
|
|
||||||
### Class: URL
|
### Class: URL
|
||||||
#### Constructor: new URL(input[, base])
|
#### Constructor: new URL(input[, base])
|
||||||
|
|
||||||
@ -1058,15 +734,342 @@ for (const [name, value] of params) {
|
|||||||
// xyz baz
|
// xyz baz
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### url.domainToASCII(domain)
|
||||||
|
<!-- YAML
|
||||||
|
added: v7.4.0
|
||||||
|
-->
|
||||||
|
|
||||||
|
* `domain` {string}
|
||||||
|
* Returns: {string}
|
||||||
|
|
||||||
|
Returns the [Punycode][] ASCII serialization of the `domain`. If `domain` is an
|
||||||
|
invalid domain, the empty string is returned.
|
||||||
|
|
||||||
|
It performs the inverse operation to [`url.domainToUnicode()`][].
|
||||||
|
|
||||||
|
```js
|
||||||
|
const url = require('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)
|
||||||
|
<!-- YAML
|
||||||
|
added: v7.4.0
|
||||||
|
-->
|
||||||
|
|
||||||
|
* `domain` {string}
|
||||||
|
* Returns: {string}
|
||||||
|
|
||||||
|
Returns the Unicode serialization of the `domain`. If `domain` is an invalid
|
||||||
|
domain, the empty string is returned.
|
||||||
|
|
||||||
|
It performs the inverse operation to [`url.domainToASCII()`][].
|
||||||
|
|
||||||
|
```js
|
||||||
|
const url = require('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.format(URL[, options])
|
||||||
|
<!-- YAML
|
||||||
|
added: v7.6.0
|
||||||
|
-->
|
||||||
|
|
||||||
|
* `URL` {URL} A [WHATWG URL][] object
|
||||||
|
* `options` {Object}
|
||||||
|
* `auth` {boolean} `true` if the serialized URL string should include the
|
||||||
|
username and password, `false` otherwise. Defaults to `true`.
|
||||||
|
* `fragment` {boolean} `true` if the serialized URL string should include the
|
||||||
|
fragment, `false` otherwise. Defaults to `true`.
|
||||||
|
* `search` {boolean} `true` if the serialized URL string should include the
|
||||||
|
search query, `false` otherwise. Defaults to `true`.
|
||||||
|
* `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. Defaults to `false`.
|
||||||
|
|
||||||
|
Returns a customizable serialization of a URL String representation of a
|
||||||
|
[WHATWG URL][] object.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
For example:
|
||||||
|
|
||||||
|
```js
|
||||||
|
const myURL = new URL('https://a:b@你好你好?abc#foo');
|
||||||
|
|
||||||
|
console.log(myURL.href);
|
||||||
|
// Prints https://a:b@xn--6qqa088eba/?abc#foo
|
||||||
|
|
||||||
|
console.log(myURL.toString());
|
||||||
|
// Prints https://a:b@xn--6qqa088eba/?abc#foo
|
||||||
|
|
||||||
|
console.log(url.format(myURL, {fragment: false, unicode: true, auth: false}));
|
||||||
|
// Prints 'https://你好你好?abc'
|
||||||
|
```
|
||||||
|
|
||||||
|
## Legacy URL API
|
||||||
|
|
||||||
|
### Legacy urlObject
|
||||||
|
|
||||||
|
The legacy urlObject (`require('url').Url`) is created and returned by the
|
||||||
|
`url.parse()` function.
|
||||||
|
|
||||||
|
#### urlObject.auth
|
||||||
|
|
||||||
|
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 an
|
||||||
|
ASCII "at sign" (`@`). The format of the string is `{username}[:{password}]`,
|
||||||
|
with the `[:{password}]` portion being optional.
|
||||||
|
|
||||||
|
For example: `'user:pass'`
|
||||||
|
|
||||||
|
#### urlObject.hash
|
||||||
|
|
||||||
|
The `hash` property consists of the "fragment" portion of the URL including
|
||||||
|
the leading ASCII hash (`#`) character.
|
||||||
|
|
||||||
|
For example: `'#hash'`
|
||||||
|
|
||||||
|
#### urlObject.host
|
||||||
|
|
||||||
|
The `host` property is the full lower-cased host portion of the URL, including
|
||||||
|
the `port` if specified.
|
||||||
|
|
||||||
|
For example: `'sub.host.com:8080'`
|
||||||
|
|
||||||
|
#### urlObject.hostname
|
||||||
|
|
||||||
|
The `hostname` property is the lower-cased host name portion of the `host`
|
||||||
|
component *without* the `port` included.
|
||||||
|
|
||||||
|
For example: `'sub.host.com'`
|
||||||
|
|
||||||
|
#### urlObject.href
|
||||||
|
|
||||||
|
The `href` property is the full URL string that was parsed with both the
|
||||||
|
`protocol` and `host` components converted to lower-case.
|
||||||
|
|
||||||
|
For example: `'http://user:pass@sub.host.com:8080/p/a/t/h?query=string#hash'`
|
||||||
|
|
||||||
|
#### urlObject.path
|
||||||
|
|
||||||
|
The `path` property is a concatenation of the `pathname` and `search`
|
||||||
|
components.
|
||||||
|
|
||||||
|
For example: `'/p/a/t/h?query=string'`
|
||||||
|
|
||||||
|
No decoding of the `path` is performed.
|
||||||
|
|
||||||
|
#### urlObject.pathname
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
For example `'/p/a/t/h'`
|
||||||
|
|
||||||
|
No decoding of the path string is performed.
|
||||||
|
|
||||||
|
#### urlObject.port
|
||||||
|
|
||||||
|
The `port` property is the numeric port portion of the `host` component.
|
||||||
|
|
||||||
|
For example: `'8080'`
|
||||||
|
|
||||||
|
#### urlObject.protocol
|
||||||
|
|
||||||
|
The `protocol` property identifies the URL's lower-cased protocol scheme.
|
||||||
|
|
||||||
|
For example: `'http:'`
|
||||||
|
|
||||||
|
#### urlObject.query
|
||||||
|
|
||||||
|
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()`.
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
The `search` property consists of the entire "query string" portion of the
|
||||||
|
URL, including the leading ASCII question mark (`?`) character.
|
||||||
|
|
||||||
|
For example: `'?query=string'`
|
||||||
|
|
||||||
|
No decoding of the query string is performed.
|
||||||
|
|
||||||
|
#### urlObject.slashes
|
||||||
|
|
||||||
|
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)
|
||||||
|
<!-- YAML
|
||||||
|
added: v0.1.25
|
||||||
|
-->
|
||||||
|
|
||||||
|
* `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()`.
|
||||||
|
|
||||||
|
The `url.format()` method returns a formatted URL string derived from
|
||||||
|
`urlObject`.
|
||||||
|
|
||||||
|
If `urlObject` is not an object or a string, `url.parse()` 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 to `result`.
|
||||||
|
* Otherwise, if `urlObject.protocol` is not `undefined` and is not a string, an
|
||||||
|
[`Error`][] is thrown.
|
||||||
|
* For all string values of `urlObject.protocol` that *do not end* with an ASCII
|
||||||
|
colon (`:`) character, the literal string `:` will be appended to `result`.
|
||||||
|
* If either of the following conditions is true, then the literal string `//`
|
||||||
|
will be appended to `result`:
|
||||||
|
* `urlObject.slashes` property is true;
|
||||||
|
* `urlObject.protocol` begins with `http`, `https`, `ftp`, `gopher`, or
|
||||||
|
`file`;
|
||||||
|
* 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 `@`.
|
||||||
|
* If the `urlObject.host` property is `undefined` then:
|
||||||
|
* If the `urlObject.hostname` is a string, it is appended to `result`.
|
||||||
|
* Otherwise, if `urlObject.hostname` is not `undefined` and is not a string,
|
||||||
|
an [`Error`][] is thrown.
|
||||||
|
* If the `urlObject.port` property value is truthy, and `urlObject.hostname`
|
||||||
|
is not `undefined`:
|
||||||
|
* The literal string `:` is appended to `result`, and
|
||||||
|
* The value of `urlObject.port` is coerced to a string and appended to
|
||||||
|
`result`.
|
||||||
|
* Otherwise, if the `urlObject.host` property value is truthy, the value of
|
||||||
|
`urlObject.host` is coerced to a string and appended to `result`.
|
||||||
|
* 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 to `result`.
|
||||||
|
* The value of `urlObject.pathname` is appended to `result`.
|
||||||
|
* Otherwise, if `urlObject.pathname` is not `undefined` and is not a string, an
|
||||||
|
[`Error`][] is thrown.
|
||||||
|
* 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`.
|
||||||
|
* 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 to `result`.
|
||||||
|
* The value of `urlObject.search` is appended to `result`.
|
||||||
|
* Otherwise, if `urlObject.search` is not `undefined` and is not a string, an
|
||||||
|
[`Error`][] 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 to `result`.
|
||||||
|
* The value of `urlObject.hash` is appended to `result`.
|
||||||
|
* Otherwise, if the `urlObject.hash` property is not `undefined` and is not a
|
||||||
|
string, an [`Error`][] is thrown.
|
||||||
|
* `result` is returned.
|
||||||
|
|
||||||
|
|
||||||
|
### url.parse(urlString[, parseQueryString[, slashesDenoteHost]])
|
||||||
|
<!-- YAML
|
||||||
|
added: v0.1.25
|
||||||
|
-->
|
||||||
|
|
||||||
|
* `urlString` {string} The URL string to parse.
|
||||||
|
* `parseQueryString` {boolean} If `true`, the `query` property will always
|
||||||
|
be set to an object returned by the [`querystring`][] module's `parse()`
|
||||||
|
method. If `false`, the `query` property on the returned URL object will be an
|
||||||
|
unparsed, undecoded string. Defaults to `false`.
|
||||||
|
* `slashesDenoteHost` {boolean} If `true`, the first token after the literal
|
||||||
|
string `//` and preceding the next `/` will be interpreted as the `host`.
|
||||||
|
For instance, given `//foo/bar`, the result would be
|
||||||
|
`{host: 'foo', pathname: '/bar'}` rather than `{pathname: '//foo/bar'}`.
|
||||||
|
Defaults to `false`.
|
||||||
|
|
||||||
|
The `url.parse()` method takes a URL string, parses it, and returns a URL
|
||||||
|
object.
|
||||||
|
|
||||||
|
A `TypeError` is thrown if `urlString` is not a string.
|
||||||
|
|
||||||
|
A `URIError` is thrown if the `auth` property is present but cannot be decoded.
|
||||||
|
|
||||||
|
### url.resolve(from, to)
|
||||||
|
<!-- YAML
|
||||||
|
added: v0.1.25
|
||||||
|
changes:
|
||||||
|
- version: v6.6.0
|
||||||
|
pr-url: https://github.com/nodejs/node/pull/8215
|
||||||
|
description: The `auth` fields are now kept intact when `from` and `to`
|
||||||
|
refer to the same host.
|
||||||
|
- version: v6.5.0, v4.6.2
|
||||||
|
pr-url: https://github.com/nodejs/node/pull/8214
|
||||||
|
description: The `port` field is copied correctly now.
|
||||||
|
- version: v6.0.0
|
||||||
|
pr-url: https://github.com/nodejs/node/pull/1480
|
||||||
|
description: The `auth` fields is cleared now the `to` parameter
|
||||||
|
contains a hostname.
|
||||||
|
-->
|
||||||
|
|
||||||
|
* `from` {string} The Base URL being resolved against.
|
||||||
|
* `to` {string} The HREF URL being resolved.
|
||||||
|
|
||||||
|
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 HREF.
|
||||||
|
|
||||||
|
For example:
|
||||||
|
|
||||||
|
```js
|
||||||
|
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'
|
||||||
|
```
|
||||||
|
|
||||||
<a id="whatwg-percent-encoding"></a>
|
<a id="whatwg-percent-encoding"></a>
|
||||||
### Percent-Encoding in the WHATWG URL Standard
|
## Percent-Encoding in URLs
|
||||||
|
|
||||||
URLs are permitted to only contain a certain range of characters. Any character
|
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,
|
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
|
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
|
located within the structure of the URL.
|
||||||
selective and fine grained approach to selecting encoded characters than that
|
|
||||||
used by the older [`url.parse()`][] and [`url.format()`][] methods.
|
### Legacy API
|
||||||
|
|
||||||
|
Within the Legacy API, spaces (`' '`) and the following characters will be
|
||||||
|
automatically escaped in the properties of URL objects:
|
||||||
|
|
||||||
|
```txt
|
||||||
|
< > " ` \r \n \t { } | \ ^ '
|
||||||
|
```
|
||||||
|
|
||||||
|
For example, the ASCII space character (`' '`) is encoded as `%20`. The ASCII
|
||||||
|
forward slash (`/`) character is encoded as `%3C`.
|
||||||
|
|
||||||
|
### WHATWG API
|
||||||
|
|
||||||
|
The [WHATWG URL Standard][] uses a more selective and fine grained approach to
|
||||||
|
selecting encoded characters than that used by the Legacy API.
|
||||||
|
|
||||||
The WHATWG algorithm defines three "percent-encode sets" that describe ranges
|
The WHATWG algorithm defines three "percent-encode sets" that describe ranges
|
||||||
of characters that must be percent-encoded:
|
of characters that must be percent-encoded:
|
||||||
@ -1101,7 +1104,6 @@ console.log(myURL.origin);
|
|||||||
// Prints https://π.com
|
// Prints https://π.com
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
[`Error`]: errors.html#errors_class_error
|
[`Error`]: errors.html#errors_class_error
|
||||||
[`JSON.stringify()`]: https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
|
[`JSON.stringify()`]: https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
|
||||||
[`Map`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
|
[`Map`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
|
||||||
|
Loading…
x
Reference in New Issue
Block a user