Node.js v6.10.0 文档


url#

查看英文版 / 参与翻译

稳定性: 2 - 稳定的

url 模块提供了一些实用函数,用于 URL 处理与解析。 可以通过以下方式使用:

const url = require('url');

URL 字符串与 URL 对象#

查看英文版 / 参与翻译

一个 URL 字符串是一个结构化的字符串,它包含多个有意义的组成部分。 当被解析时,会返回一个 URL 对象,它包含每个组成部分作为属性。

以下详情描述了一个解析后的 URL 的每个组成部分。 例子,'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'

┌─────────────────────────────────────────────────────────────────────────────┐
│                                    href                                     │
├──────────┬┬───────────┬─────────────────┬───────────────────────────┬───────┤
│ protocol ││   auth    │      host       │           path            │ hash  │
│          ││           ├──────────┬──────┼──────────┬────────────────┤       │
│          ││           │ hostname │ port │ pathname │     search     │       │
│          ││           │          │      │          ├─┬──────────────┤       │
│          ││           │          │      │          │ │    query     │       │
"  http:   // user:pass @ host.com : 8080   /p/a/t/h  ?  query=string   #hash "
│          ││           │          │      │          │ │              │       │
└──────────┴┴───────────┴──────────┴──────┴──────────┴─┴──────────────┴───────┘
(请忽略字符串中的空格,它们只是为了格式化)

urlObject.href#

查看英文版 / 参与翻译

href 属性是解析后的完整的 URL 字符串,protocolhost 都会被转换为小写的。

例如:'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'

urlObject.protocol#

查看英文版 / 参与翻译

protocol 属性表明 URL 的小写的协议体制。

例如:'http:'

urlObject.slashes#

查看英文版 / 参与翻译

slashes 属性是一个 boolean,如果 protocol 中的冒号后面跟着两个 ASCII 斜杠字符(/),则值为 true

urlObject.host#

查看英文版 / 参与翻译

host 属性是 URL 的完整的小写的主机部分,包括 port(如果有)。

例如:'host.com:8080'

urlObject.auth#

查看英文版 / 参与翻译

auth 属性是 URL 的用户名与密码部分。 该字符串跟在 protocol 和双斜杠(如果有)的后面,排在 host 部分的前面且被一个 ASCII 的 at 符号(@)分隔。 该字符的格式为 {username}[:{password}][:{password}] 部分是可选的。

例如:'user:pass'

urlObject.hostname#

查看英文版 / 参与翻译

hostname 属性是 host 组成部分排除 port 之后的小写的主机名部分。

例如:'host.com'

urlObject.port#

查看英文版 / 参与翻译

port 属性是 host 组成部分中的数值型的端口部分。

例如:'8080'

urlObject.pathname#

查看英文版 / 参与翻译

pathname 属性包含 URL 的整个路径部分。 它跟在 host (包括 port)后面,排在 queryhash 组成部分的前面且被 ASCII 问号(?)或哈希字符(#)分隔。

例如:'/p/a/t/h'

不会对路径字符串执行解码。

urlObject.search#

查看英文版 / 参与翻译

search 属性包含 URL 的整个查询字符串部分,包括开头的 ASCII 问号字符(?)。

例如:'?query=string'

不会对查询字符串执行解码。

urlObject.path#

查看英文版 / 参与翻译

path 属性是一个 pathnamesearch 组成部分的串接。

例如:'/p/a/t/h?query=string'

不会对 path 执行解码。

urlObject.query#

查看英文版 / 参与翻译

query 属性是不含开头 ASCII 问号(?)的查询字符串,或一个被 querystring 模块的 parse() 方法返回的对象。 query 属性是一个字符串还是一个对象是由传入 url.parse()parseQueryString 参数决定的。

例如:'query=string' or {'query': 'string'}

如果返回一个字符串,则不会对查询字符串执行解码。 如果返回一个对象,则键和值都会被解码。

urlObject.hash#

查看英文版 / 参与翻译

hash 属性包含 URL 的碎片部分,包括开头的 ASCII 哈希字符(#)。

例如:'#hash'

url.format(urlObject)#

查看英文版 / 参与翻译

  • 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]])#

查看英文版 / 参与翻译

  • 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.

url.resolve(from, to)#

查看英文版 / 参与翻译

  • 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:

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:

< > " ` \r \n \t { } | \ ^ '

For example, the ASCII space character (' ') is encoded as %20. The ASCII forward slash (/) character is encoded as %3C.