URL

[Estável: 2 - Estável]

Código-Fonte: lib/url.js

O módulo node:url fornece utilitários para resolução e análise de URLs. Pode ser acessado usando:

ESMCJS

import url from 'node:url'

const url = require('node:url')

Strings de URL e objetos URL

Uma string de URL é uma string estruturada contendo vários componentes significativos. Quando analisada, um objeto URL é retornado contendo propriedades para cada um desses componentes.

O módulo node:url fornece duas APIs para trabalhar com URLs: uma API herdada específica do Node.js e uma API mais nova que implementa o mesmo Padrão de URL WHATWG usado por navegadores web.

Uma comparação entre as APIs WHATWG e legadas é fornecida abaixo. Acima da URL 'https://user:[email protected]:8080/p/a/t/h?query=string#hash', são mostradas as propriedades de um objeto retornado pela função url.parse() herdada. Abaixo dela estão as propriedades de um objeto URL WHATWG.

A propriedade origin da URL WHATWG inclui protocol e host, mas não username ou password.

text

┌────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                              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                                              │
└────────────────────────────────────────────────────────────────────────────────────────────────┘
(Todos os espaços na linha "" devem ser ignorados. Eles são apenas para formatação.)

Analisando a string da URL usando a API WHATWG:

const myURL = new URL('https://user::8080/p/a/t/h?query=string#hash')

Analisando a string da URL usando a API herdada:

ESMCJS

import url from 'node:url'
const myURL = url.parse('https://user::8080/p/a/t/h?query=string#hash')

const url = require('node:url')
const myURL = url.parse('https://user::8080/p/a/t/h?query=string#hash')

Construindo uma URL a partir de partes componentes e obtendo a string construída

É possível construir uma URL WHATWG a partir de partes componentes usando os definidores de propriedade ou uma string literal de modelo:

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}`)

Para obter a string da URL construída, use o acessador de propriedade href:

console.log(myURL.href)

A API WHATWG URL

Classe: `URL`

[Histórico]

Versão	Alterações
v10.0.0	A classe agora está disponível no objeto global.
v7.0.0, v6.13.0	Adicionada em: v7.0.0, v6.13.0

Classe URL compatível com o navegador, implementada seguindo o Padrão WHATWG URL. Exemplos de URLs analisadas podem ser encontrados no próprio Padrão. A classe URL também está disponível no objeto global.

De acordo com as convenções do navegador, todas as propriedades dos objetos URL são implementadas como getters e setters no protótipo da classe, em vez de como propriedades de dados no próprio objeto. Assim, ao contrário dos objetos urlObject herdados, usar a palavra-chave delete em qualquer propriedade dos objetos URL (por exemplo, delete myURL.protocol, delete myURL.pathname, etc.) não tem efeito, mas ainda retornará true.

`new URL(input[, base])`

[Histórico]

Versão	Alterações
v20.0.0, v18.17.0	O requisito ICU foi removido.

input <string> A URL de entrada absoluta ou relativa a ser analisada. Se input for relativo, então base é necessário. Se input for absoluto, o base será ignorado. Se input não for uma string, ele será convertido para uma string primeiro.
base <string> A URL base para resolver contra se a input não for absoluta. Se base não for uma string, ele será convertido para uma string primeiro.

Cria um novo objeto URL analisando a input em relação à base. Se base for passado como uma string, ele será analisado equivalente a new URL(base).

const myURL = new URL('/foo', 'https://example.org/')
// https://example.org/foo

O construtor URL é acessível como uma propriedade no objeto global. Ele também pode ser importado do módulo url embutido:

ESMCJS

import { URL } from 'node:url'
console.log(URL === globalThis.URL) // Imprime 'true'.

console.log(URL === require('node:url').URL) // Imprime 'true'.

Um TypeError será lançado se a input ou base não forem URLs válidas. Observe que será feito um esforço para converter os valores fornecidos em strings. Por exemplo:

const myURL = new URL({ toString: () => 'https://example.org/' })
// https://example.org/

Os caracteres Unicode que aparecem no nome do host de input serão convertidos automaticamente para ASCII usando o algoritmo Punycode.

const myURL = new URL('https://測試')
// https://xn--g6w251d/

Nos casos em que não se sabe antecipadamente se input é uma URL absoluta e uma base é fornecida, é aconselhável validar que a origin do objeto URL seja o que é esperado.

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`

<string>

Obtém e define a parte de fragmento da URL.

const myURL = new URL('https://example.org/foo#bar')
console.log(myURL.hash)
// Imprime #bar

myURL.hash = 'baz'
console.log(myURL.href)
// Imprime https://example.org/foo#baz

Caracteres de URL inválidos incluídos no valor atribuído à propriedade hash são codificados em porcentagem. A seleção de quais caracteres devem ser codificados em porcentagem pode variar um pouco do que os métodos url.parse() e url.format() produziriam.

`url.host`

<string>

Obtém e define a parte do host da URL.

const myURL = new URL('https://example.org:81/foo')
console.log(myURL.host)
// Imprime example.org:81

myURL.host = 'example.com:82'
console.log(myURL.href)
// Imprime https://example.com:82/foo

Valores de host inválidos atribuídos à propriedade host são ignorados.

`url.hostname`

<string>

Obtém e define a parte do nome do host da URL. A principal diferença entre url.host e url.hostname é que url.hostname não inclui a porta.

const myURL = new URL('https://example.org:81/foo')
console.log(myURL.hostname)
// Imprime example.org

// Definir o hostname não altera a porta
myURL.hostname = 'example.com'
console.log(myURL.href)
// Imprime https://example.com:81/foo

// Use myURL.host para alterar o hostname e a porta
myURL.host = 'example.org:82'
console.log(myURL.href)
// Imprime https://example.org:82/foo

Valores de nome de host inválidos atribuídos à propriedade hostname são ignorados.

`url.href`

<string>

Obtém e define a URL serializada.

const myURL = new URL('https://example.org/foo')
console.log(myURL.href)
// Imprime https://example.org/foo

myURL.href = 'https://example.com/bar'
console.log(myURL.href)
// Imprime https://example.com/bar

Obter o valor da propriedade href é equivalente a chamar url.toString().

Definir o valor desta propriedade para um novo valor é equivalente a criar um novo objeto URL usando new URL(value). Cada uma das propriedades do objeto URL será modificada.

Se o valor atribuído à propriedade href não for uma URL válida, será lançado um TypeError.

`url.origin`

[Histórico]

Versão	Alterações
v15.0.0	O esquema "gopher" não é mais especial e `url.origin` agora retorna `'null'` para ele.

<string>

Obtém a serialização somente leitura da origem da URL.

const myURL = new URL('https://example.org/foo/bar?baz')
console.log(myURL.origin)
// Imprime https://example.org

const idnURL = new URL('https://測試')
console.log(idnURL.origin)
// Imprime https://xn--g6w251d

console.log(idnURL.hostname)
// Imprime xn--g6w251d

`url.password`

<string>

Obtém e define a parte da senha da URL.

const myURL = new URL('https://abc:')
console.log(myURL.password)
// Imprime xyz

myURL.password = '123'
console.log(myURL.href)
// Imprime https://abc:/

Caracteres de URL inválidos incluídos no valor atribuído à propriedade password são percentualmente codificados. A seleção de quais caracteres devem ser codificados por porcentagem pode variar um pouco do que os métodos url.parse() e url.format() produziriam.

`url.pathname`

<string>

Obtém e define a parte do caminho da URL.

const myURL = new URL('https://example.org/abc/xyz?123')
console.log(myURL.pathname)
// Imprime /abc/xyz

myURL.pathname = '/abcdef'
console.log(myURL.href)
// Imprime https://example.org/abcdef?123

Caracteres de URL inválidos incluídos no valor atribuído à propriedade pathname são percentualmente codificados. A seleção de quais caracteres devem ser codificados por porcentagem pode variar um pouco do que os métodos url.parse() e url.format() produziriam.

`url.port`

[Histórico]

Versão	Alterações
v15.0.0	O esquema "gopher" não é mais especial.

<string>

Obtém e define a parte da porta da URL.

O valor da porta pode ser um número ou uma string contendo um número na faixa de 0 a 65535 (inclusive). Definir o valor para a porta padrão dos objetos URL dado o protocol resultará no valor port se tornando uma string vazia ('').

O valor da porta pode ser uma string vazia, caso em que a porta depende do protocolo/esquema:

protocolo	porta
"ftp"	21
"file"
"http"	80
"https"	443
"ws"	80
"wss"	443

Ao atribuir um valor à porta, o valor será primeiro convertido para uma string usando .toString().

Se essa string for inválida, mas começar com um número, o número inicial será atribuído a port. Se o número estiver fora do intervalo denotado acima, ele será ignorado.

const myURL = new URL('https://example.org:8888')
console.log(myURL.port)
// Imprime 8888

// As portas padrão são automaticamente transformadas em string vazia
// (a porta padrão do protocolo HTTPS é 443)
myURL.port = '443'
console.log(myURL.port)
// Imprime a string vazia
console.log(myURL.href)
// Imprime https://example.org/

myURL.port = 1234
console.log(myURL.port)
// Imprime 1234
console.log(myURL.href)
// Imprime https://example.org:1234/

// Strings de porta completamente inválidas são ignoradas
myURL.port = 'abcd'
console.log(myURL.port)
// Imprime 1234

// Os números iniciais são tratados como um número de porta
myURL.port = '5678abcd'
console.log(myURL.port)
// Imprime 5678

// Números não inteiros são truncados
myURL.port = 1234.5678
console.log(myURL.port)
// Imprime 1234

// Números fora do intervalo que não são representados em notação científica
// serão ignorados.
myURL.port = 1e10 // 10000000000, será verificado no intervalo como descrito abaixo
console.log(myURL.port)
// Imprime 1234

Números que contêm um ponto decimal, como números de ponto flutuante ou números em notação científica, não são uma exceção a essa regra. Os números iniciais até o ponto decimal serão definidos como a porta da URL, assumindo que sejam válidos:

myURL.port = 4.567e21
console.log(myURL.port)
// Imprime 4 (porque é o número inicial na string '4.567e21')

`url.protocol`

<string>

Obtém e define a parte do protocolo da URL.

const myURL = new URL('https://example.org')
console.log(myURL.protocol)
// Imprime https:

myURL.protocol = 'ftp'
console.log(myURL.href)
// Imprime ftp://example.org/

Valores de protocolo de URL inválidos atribuídos à propriedade protocol são ignorados.

Esquemas especiais

[Histórico]

Versão	Alterações
v15.0.0	O esquema "gopher" não é mais especial.

O Padrão WHATWG URL considera um punhado de esquemas de protocolo de URL como especiais em termos de como são analisados e serializados. Quando uma URL é analisada usando um desses protocolos especiais, a propriedade url.protocol pode ser alterada para outro protocolo especial, mas não pode ser alterada para um protocolo não especial, e vice-versa.

Por exemplo, a mudança de http para https funciona:

const u = new URL('http://example.org')
u.protocol = 'https'
console.log(u.href)
// https://example.org/

No entanto, a mudança de http para um hipotético protocolo fish não funciona porque o novo protocolo não é especial.

const u = new URL('http://example.org')
u.protocol = 'fish'
console.log(u.href)
// http://example.org/

Da mesma forma, a alteração de um protocolo não especial para um protocolo especial também não é permitida:

const u = new URL('fish://example.org')
u.protocol = 'http'
console.log(u.href)
// fish://example.org

De acordo com o Padrão WHATWG URL, os esquemas de protocolo especiais são ftp, file, http, https, ws e wss.

`url.search`

<string>

Obtém e define a parte de consulta serializada da URL.

const myURL = new URL('https://example.org/abc?123')
console.log(myURL.search)
// Imprime ?123

myURL.search = 'abc=xyz'
console.log(myURL.href)
// Imprime https://example.org/abc?abc=xyz

Quaisquer caracteres de URL inválidos que aparecem no valor atribuído à propriedade search serão codificados em porcentagem. A seleção de quais caracteres devem ser codificados em porcentagem pode variar um pouco do que os métodos url.parse() e url.format() produziriam.

`url.searchParams`

<URLSearchParams>

Obtém o objeto URLSearchParams que representa os parâmetros de consulta da URL. Esta propriedade é somente leitura, mas o objeto URLSearchParams que ela fornece pode ser usado para modificar a instância da URL; para substituir a totalidade dos parâmetros de consulta da URL, use o seletor url.search. Consulte a documentação URLSearchParams para obter detalhes.

Tome cuidado ao usar .searchParams para modificar a URL porque, de acordo com a especificação WHATWG, o objeto URLSearchParams usa regras diferentes para determinar quais caracteres devem ser codificados em porcentagem. Por exemplo, o objeto URL não codificará em porcentagem o caractere til (~) ASCII, enquanto URLSearchParams sempre o codificará:

const myURL = new URL('https://example.org/abc?foo=~bar')

console.log(myURL.search) // imprime ?foo=~bar

// Modifica a URL via searchParams...
myURL.searchParams.sort()

console.log(myURL.search) // imprime ?foo=%7Ebar

`url.username`

<string>

Obtém e define a parte do nome de usuário da URL.

const myURL = new URL('https://abc:')
console.log(myURL.username)
// Imprime abc

myURL.username = '123'
console.log(myURL.href)
// Imprime https://123:/

Quaisquer caracteres de URL inválidos que aparecem no valor atribuído à propriedade username serão codificados em porcentagem. A seleção de quais caracteres devem ser codificados em porcentagem pode variar um pouco do que os métodos url.parse() e url.format() produziriam.

`url.toString()`

Retorna: <string>

O método toString() no objeto URL retorna a URL serializada. O valor retornado é equivalente ao de url.href e url.toJSON().

`url.toJSON()`

Adicionado em: v7.7.0, v6.13.0

Retorna: <string>

O método toJSON() no objeto URL retorna a URL serializada. O valor retornado é equivalente ao de url.href e url.toString().

Este método é chamado automaticamente quando um objeto URL é serializado com JSON.stringify().

const myURLs = [new URL('https://www.example.com'), new URL('https://test.example.org')]
console.log(JSON.stringify(myURLs))
// Imprime ["https://www.example.com/","https://test.example.org/"]

`URL.createObjectURL(blob)`

Adicionado em: v16.7.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

blob <Blob>
Retorna: <string>

Cria uma string de URL 'blob:nodedata:...' que representa o objeto <Blob> fornecido e pode ser usada para recuperar o Blob posteriormente.

const { Blob, resolveObjectURL } = require('node:buffer')

const blob = new Blob(['hello'])
const id = URL.createObjectURL(blob)

// mais tarde...

const otherBlob = resolveObjectURL(id)
console.log(otherBlob.size)

Os dados armazenados pelo <Blob> registrado serão retidos na memória até que URL.revokeObjectURL() seja chamado para removê-los.

Objetos Blob são registrados na thread atual. Se estiver usando Worker Threads, os objetos Blob registrados em um Worker não estarão disponíveis para outros workers ou a thread principal.

`URL.revokeObjectURL(id)`

Adicionado em: v16.7.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

id <string> Uma string de URL 'blob:nodedata:... retornada por uma chamada anterior a URL.createObjectURL().

Remove o <Blob> armazenado identificado pelo ID fornecido. Tentar revogar um ID que não está registrado falhará silenciosamente.

`URL.canParse(input[, base])`

Adicionado em: v19.9.0, v18.17.0

input <string> A URL de entrada absoluta ou relativa a ser analisada. Se input for relativa, então base é necessário. Se input for absoluta, base será ignorado. Se input não for uma string, ela será convertida para uma string primeiro.
base <string> A URL base para resolução se input não for absoluta. Se base não for uma string, ela será convertida para uma string primeiro.
Retorna: <boolean>

Verifica se um input relativo à base pode ser analisado como uma URL.

const isValid = URL.canParse('/foo', 'https://example.org/') // true

const isNotValid = URL.canParse('/foo') // false

`URL.parse(input[, base])`

Adicionado em: v22.1.0

input <string> A URL de entrada absoluta ou relativa a ser analisada. Se input for relativa, então base é necessário. Se input for absoluta, base será ignorado. Se input não for uma string, ela será convertida para uma string primeiro.
base <string> A URL base para resolução se input não for absoluta. Se base não for uma string, ela será convertida para uma string primeiro.
Retorna: <URL> | <null>

Analisa uma string como uma URL. Se base for fornecido, ele será usado como a URL base para resolver URLs input não absolutas. Retorna null se input não for válido.

Classe: `URLSearchParams`

[Histórico]

Versão	Alterações
v10.0.0	A classe agora está disponível no objeto global.
v7.5.0, v6.13.0	Adicionada em: v7.5.0, v6.13.0

A API URLSearchParams fornece acesso de leitura e escrita à consulta de uma URL. A classe URLSearchParams também pode ser usada de forma independente com um dos quatro construtores a seguir. A classe URLSearchParams também está disponível no objeto global.

A interface URLSearchParams WHATWG e o módulo querystring têm propósitos semelhantes, mas o propósito do módulo querystring é mais geral, pois permite a personalização dos caracteres delimitadores (& e =). Por outro lado, esta API é projetada puramente para strings de consulta de URL.

const myURL = new URL('https://example.org/?abc=123')
console.log(myURL.searchParams.get('abc'))
// Imprime 123

myURL.searchParams.append('abc', 'xyz')
console.log(myURL.href)
// Imprime https://example.org/?abc=123&abc=xyz

myURL.searchParams.delete('abc')
myURL.searchParams.set('a', 'b')
console.log(myURL.href)
// Imprime https://example.org/?a=b

const newSearchParams = new URLSearchParams(myURL.searchParams)
// O código acima é equivalente a
// const newSearchParams = new URLSearchParams(myURL.search);

newSearchParams.append('a', 'c')
console.log(myURL.href)
// Imprime https://example.org/?a=b
console.log(newSearchParams.toString())
// Imprime a=b&a=c

// newSearchParams.toString() é chamado implicitamente
myURL.search = newSearchParams
console.log(myURL.href)
// Imprime https://example.org/?a=b&a=c
newSearchParams.delete('a')
console.log(myURL.href)
// Imprime https://example.org/?a=b&a=c

`new URLSearchParams()`

Instancia um novo objeto URLSearchParams vazio.

`new URLSearchParams(string)`

string <string> Uma string de consulta

Analisa a string como uma string de consulta e a usa para instanciar um novo objeto URLSearchParams. Um '?' inicial, se presente, é ignorado.

let params

params = new URLSearchParams('user=abc&query=xyz')
console.log(params.get('user'))
// Imprime 'abc'
console.log(params.toString())
// Imprime 'user=abc&query=xyz'

params = new URLSearchParams('?user=abc&query=xyz')
console.log(params.toString())
// Imprime 'user=abc&query=xyz'

`new URLSearchParams(obj)`

Adicionado em: v7.10.0, v6.13.0

obj <Object> Um objeto representando uma coleção de pares chave-valor

Instancia um novo objeto URLSearchParams com um mapa hash de consulta. A chave e o valor de cada propriedade de obj são sempre convertidos para strings.

Ao contrário do módulo querystring, chaves duplicadas na forma de valores de array não são permitidas. Os arrays são convertidos em string usando array.toString(), que simplesmente junta todos os elementos do array com vírgulas.

const params = new URLSearchParams({
  user: 'abc',
  query: ['first', 'second'],
})
console.log(params.getAll('query'))
// Imprime [ 'first,second' ]
console.log(params.toString())
// Imprime 'user=abc&query=first%2Csecond'

`new URLSearchParams(iterable)`

Adicionado em: v7.10.0, v6.13.0

iterable <Iterable> Um objeto iterável cujos elementos são pares chave-valor

Instancia um novo objeto URLSearchParams com um mapa iterável de forma semelhante ao construtor de Map. iterable pode ser um Array ou qualquer objeto iterável. Isso significa que iterable pode ser outro URLSearchParams, caso em que o construtor simplesmente criará uma cópia do URLSearchParams fornecido. Os elementos de iterable são pares chave-valor e podem ser eles próprios qualquer objeto iterável.

Chaves duplicadas são permitidas.

let params

// Usando um array
params = new URLSearchParams([
  ['user', 'abc'],
  ['query', 'first'],
  ['query', 'second'],
])
console.log(params.toString())
// Imprime 'user=abc&query=first&query=second'

// Usando um objeto Map
const map = new Map()
map.set('user', 'abc')
map.set('query', 'xyz')
params = new URLSearchParams(map)
console.log(params.toString())
// Imprime 'user=abc&query=xyz'

// Usando uma função geradora
function* getQueryPairs() {
  yield ['user', 'abc']
  yield ['query', 'first']
  yield ['query', 'second']
}
params = new URLSearchParams(getQueryPairs())
console.log(params.toString())
// Imprime 'user=abc&query=first&query=second'

// Cada par chave-valor deve ter exatamente dois elementos
new URLSearchParams([['user', 'abc', 'error']])
// Lança TypeError [ERR_INVALID_TUPLE]:
//        Cada par de consulta deve ser uma tupla iterável [nome, valor]

`urlSearchParams.append(name, value)`

name <string>
value <string>

Adiciona um novo par nome-valor à string de consulta.

`urlSearchParams.delete(name[, value])`

[Histórico]

Versão	Alterações
v20.2.0, v18.18.0	Adiciona suporte para o argumento `value` opcional.

name <string>
value <string>

Se value for fornecido, remove todos os pares nome-valor onde o nome é name e o valor é value.

Se value não for fornecido, remove todos os pares nome-valor cujo nome seja name.

`urlSearchParams.entries()`

Retorna: <Iterator>

Retorna um Iterator ES6 sobre cada um dos pares nome-valor na consulta. Cada item do iterador é um Array JavaScript. O primeiro item do Array é o name, o segundo item do Array é o value.

Alias para urlSearchParams[@@iterator]().

`urlSearchParams.forEach(fn[, thisArg])`

[Histórico]

Versão	Alterações
v18.0.0	Passar um callback inválido para o argumento `fn` agora lança `ERR_INVALID_ARG_TYPE` em vez de `ERR_INVALID_CALLBACK`.

fn <Function> Invocado para cada par nome-valor na consulta
thisArg <Object> Para ser usado como valor this quando fn for chamado

Itera sobre cada par nome-valor na consulta e invoca a função fornecida.

const myURL = new URL('https://example.org/?a=b&c=d')
myURL.searchParams.forEach((value, name, searchParams) => {
  console.log(name, value, myURL.searchParams === searchParams)
})
// Imprime:
//   a b true
//   c d true

`urlSearchParams.get(name)`

name <string>
Retorna: <string> | <null> Uma string ou null se não houver um par nome-valor com o name fornecido.

Retorna o valor do primeiro par nome-valor cujo nome é name. Se não houver pares desse tipo, null é retornado.

`urlSearchParams.getAll(name)`

name <string>
Retorna: <string[]>

Retorna os valores de todos os pares nome-valor cujo nome é name. Se não houver pares desse tipo, um array vazio é retornado.

`urlSearchParams.has(name[, value])`

[Histórico]

Versão	Alterações
v20.2.0, v18.18.0	Adiciona suporte para o argumento `value` opcional.

name <string>
value <string>
Retorna: <boolean>

Verifica se o objeto URLSearchParams contém par(es) chave-valor com base em name e um argumento value opcional.

Se value for fornecido, retorna true quando existir um par nome-valor com o mesmo name e value.

Se value não for fornecido, retorna true se houver pelo menos um par nome-valor cujo nome seja name.

`urlSearchParams.keys()`

Retorna: <Iterator>

Retorna um Iterator ES6 sobre os nomes de cada par nome-valor.

const params = new URLSearchParams('foo=bar&foo=baz')
for (const name of params.keys()) {
  console.log(name)
}
// Imprime:
//   foo
//   foo

`urlSearchParams.set(name, value)`

name <string>
value <string>

Define o valor no objeto URLSearchParams associado a name como value. Se houverem pares nome-valor preexistentes cujos nomes sejam name, define o valor do primeiro desses pares como value e remove todos os outros. Se não, anexa o par nome-valor à string de consulta.

const params = new URLSearchParams()
params.append('foo', 'bar')
params.append('foo', 'baz')
params.append('abc', 'def')
console.log(params.toString())
// Imprime foo=bar&foo=baz&abc=def

params.set('foo', 'def')
params.set('xyz', 'opq')
console.log(params.toString())
// Imprime foo=def&abc=def&xyz=opq

`urlSearchParams.size`

Adicionado em: v19.8.0, v18.16.0

O número total de entradas de parâmetros.

`urlSearchParams.sort()`

Adicionado em: v7.7.0, v6.13.0

Classifica todos os pares nome-valor existentes no local por seus nomes. A classificação é feita com um algoritmo de classificação estável, de modo que a ordem relativa entre os pares nome-valor com o mesmo nome seja preservada.

Este método pode ser usado, em particular, para aumentar as ocorrências em cache.

const params = new URLSearchParams('query[]=abc&type=search&query[]=123')
params.sort()
console.log(params.toString())
// Imprime query%5B%5D=abc&query%5B%5D=123&type=search

`urlSearchParams.toString()`

Retorna: <string>

Retorna os parâmetros de pesquisa serializados como uma string, com caracteres percentualmente codificados onde necessário.

`urlSearchParams.values()`

Retorna: <Iterator>

Retorna um iterador ES6 sobre os valores de cada par nome-valor.

`urlSearchParams[Symbol.iterator]()`

Retorna: <Iterator>

Retorna um iterador ES6 sobre cada um dos pares nome-valor na string de consulta. Cada item do iterador é um Array JavaScript. O primeiro item do Array é o name, o segundo item do Array é o value.

Sinônimo para urlSearchParams.entries().

const params = new URLSearchParams('foo=bar&xyz=baz')
for (const [name, value] of params) {
  console.log(name, value)
}
// Imprime:
//   foo bar
//   xyz baz

`url.domainToASCII(domain)`

[Histórico]

Versão	Alterações
v20.0.0, v18.17.0	Requisito ICU removido.
v7.4.0, v6.13.0	Adicionado em: v7.4.0, v6.13.0

domain <string>
Retorna: <string>

Retorna a serialização ASCII Punycode do domain. Se domain for um domínio inválido, a string vazia será retornada.

Realiza a operação inversa de url.domainToUnicode().

ESMCJS

import url from 'node:url'

console.log(url.domainToASCII('español.com'))
// Imprime xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'))
// Imprime xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'))
// Imprime uma string vazia

const url = require('node:url')

console.log(url.domainToASCII('español.com'))
// Imprime xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'))
// Imprime xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'))
// Imprime uma string vazia

`url.domainToUnicode(domain)`

[Histórico]

Versão	Alterações
v20.0.0, v18.17.0	Requisito ICU removido.
v7.4.0, v6.13.0	Adicionado em: v7.4.0, v6.13.0

domain <string>
Retorna: <string>

Retorna a serialização Unicode do domain. Se domain for um domínio inválido, a string vazia será retornada.

Realiza a operação inversa de url.domainToASCII().

ESMCJS

import url from 'node:url'

console.log(url.domainToUnicode('xn--espaol-zwa.com'))
// Imprime español.com
console.log(url.domainToUnicode('xn--fiq228c.com'))
// Imprime 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'))
// Imprime uma string vazia

const url = require('node:url')

console.log(url.domainToUnicode('xn--espaol-zwa.com'))
// Imprime español.com
console.log(url.domainToUnicode('xn--fiq228c.com'))
// Imprime 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'))
// Imprime uma string vazia

`url.fileURLToPath(url[, options])`

[Histórico]

Versão	Alterações
v22.1.0, v20.13.0	O argumento `options` agora pode ser usado para determinar como analisar o argumento `path`.
v10.12.0	Adicionado em: v10.12.0

url <URL> | <string> A string URL do arquivo ou objeto URL a ser convertido em um caminho.
options <Object>
- windows <boolean> | <undefined> true se o path deve ser retornado como um caminho de arquivo do Windows, false para posix e undefined para o padrão do sistema. Padrão: undefined.
Retorna: <string> O caminho de arquivo Node.js específico da plataforma totalmente resolvido.

Esta função garante a decodificação correta dos caracteres codificados em porcentagem, além de garantir uma string de caminho absoluto válida entre plataformas.

ESMCJS

import { fileURLToPath } from 'node:url'

const __filename = fileURLToPath(import.meta.url)

new URL('file:///C:/path/').pathname // Incorreto: /C:/path/
fileURLToPath('file:///C:/path/') // Correto:   C:\path\ (Windows)

new URL('file://nas/foo.txt').pathname // Incorreto: /foo.txt
fileURLToPath('file://nas/foo.txt') // Correto:   \\nas\foo.txt (Windows)

new URL('file:///你好.txt').pathname // Incorreto: /%E4%BD%A0%E5%A5%BD.txt
fileURLToPath('file:///你好.txt') // Correto:   /你好.txt (POSIX)

new URL('file:///hello world').pathname // Incorreto: /hello%20world
fileURLToPath('file:///hello world') // Correto:   /hello world (POSIX)

const { fileURLToPath } = require('node:url')
new URL('file:///C:/path/').pathname // Incorreto: /C:/path/
fileURLToPath('file:///C:/path/') // Correto:   C:\path\ (Windows)

new URL('file://nas/foo.txt').pathname // Incorreto: /foo.txt
fileURLToPath('file://nas/foo.txt') // Correto:   \\nas\foo.txt (Windows)

new URL('file:///你好.txt').pathname // Incorreto: /%E4%BD%A0%E5%A5%BD.txt
fileURLToPath('file:///你好.txt') // Correto:   /你好.txt (POSIX)

new URL('file:///hello world').pathname // Incorreto: /hello%20world
fileURLToPath('file:///hello world') // Correto:   /hello world (POSIX)

`url.format(URL[, options])`

Adicionado em: v7.6.0

URL <URL> Um objeto WHATWG URL
options <Object>
- auth <boolean> true se a string de URL serializada deve incluir o nome de usuário e a senha, false caso contrário. Padrão: true.
- fragment <boolean> true se a string de URL serializada deve incluir o fragmento, false caso contrário. Padrão: true.
- search <boolean> true se a string de URL serializada deve incluir a consulta de pesquisa, false caso contrário. Padrão: true.
- unicode <boolean> true se os caracteres Unicode que aparecem no componente host da string de URL devem ser codificados diretamente, em oposição a serem codificados em Punycode. Padrão: false.
Retorna: <string>

Retorna uma serialização personalizável de uma representação String de URL de um objeto WHATWG URL.

O objeto URL possui tanto um método toString() quanto uma propriedade href que retornam serializações de string da URL. No entanto, essas não são personalizáveis de forma alguma. O método url.format(URL[, options]) permite a personalização básica da saída.

ESMCJS

import url from 'node:url'
const myURL = new URL('https://a:b@測試?abc#foo')

console.log(myURL.href)
// Imprime https://a:b@xn--g6w251d/?abc#foo

console.log(myURL.toString())
// Imprime https://a:b@xn--g6w251d/?abc#foo

console.log(url.format(myURL, { fragment: false, unicode: true, auth: false }))
// Imprime 'https://測試/?abc'

const url = require('node:url')
const myURL = new URL('https://a:b@測試?abc#foo')

console.log(myURL.href)
// Imprime https://a:b@xn--g6w251d/?abc#foo

console.log(myURL.toString())
// Imprime https://a:b@xn--g6w251d/?abc#foo

console.log(url.format(myURL, { fragment: false, unicode: true, auth: false }))
// Imprime 'https://測試/?abc'

`url.pathToFileURL(path[, options])`

[Histórico]

Versão	Alterações
v22.1.0, v20.13.0	O argumento `options` agora pode ser usado para determinar como retornar o valor `path`.
v10.12.0	Adicionado em: v10.12.0

path <string> O caminho a ser convertido para uma URL de arquivo.
options <Object>
- windows <boolean> | <undefined> true se o path deve ser tratado como um caminho de arquivo Windows, false para posix e undefined para o padrão do sistema. Padrão: undefined.
Retorna: <URL> O objeto URL do arquivo.

Esta função garante que path seja resolvido absolutamente e que os caracteres de controle da URL sejam codificados corretamente ao converter para uma URL de arquivo.

ESMCJS

import { pathToFileURL } from 'node:url'

new URL('/foo#1', 'file:') // Incorreto: file:///foo#1
pathToFileURL('/foo#1') // Correto:   file:///foo%231 (POSIX)

new URL('/some/path%.c', 'file:') // Incorreto: file:///some/path%.c
pathToFileURL('/some/path%.c') // Correto:   file:///some/path%25.c (POSIX)

const { pathToFileURL } = require('node:url')
new URL(__filename) // Incorreto: lança exceção (POSIX)
new URL(__filename) // Incorreto: C:\... (Windows)
pathToFileURL(__filename) // Correto:   file:///... (POSIX)
pathToFileURL(__filename) // Correto:   file:///C:/... (Windows)

new URL('/foo#1', 'file:') // Incorreto: file:///foo#1
pathToFileURL('/foo#1') // Correto:   file:///foo%231 (POSIX)

new URL('/some/path%.c', 'file:') // Incorreto: file:///some/path%.c
pathToFileURL('/some/path%.c') // Correto:   file:///some/path%25.c (POSIX)

`url.urlToHttpOptions(url)`

[Histórico]

Versão	Alterações
v19.9.0, v18.17.0	O objeto retornado também conterá todas as propriedades enumeráveis próprias do argumento `url`.
v15.7.0, v14.18.0	Adicionado em: v15.7.0, v14.18.0

url <URL> O objeto WHATWG URL a ser convertido em um objeto de opções.
Retorna: <Object> Objeto de opções
- protocol <string> Protocolo a ser usado.
- hostname <string> Um nome de domínio ou endereço IP do servidor para o qual enviar a solicitação.
- hash <string> A parte de fragmento da URL.
- search <string> A parte de consulta serializada da URL.
- pathname <string> A parte de caminho da URL.
- path <string> Caminho da solicitação. Deve incluir a string de consulta, se houver. Ex.: '/index.html?page=12'. Uma exceção é lançada quando o caminho da solicitação contém caracteres ilegais. Atualmente, apenas espaços são rejeitados, mas isso pode mudar no futuro.
- href <string> A URL serializada.
- port <number> Porta do servidor remoto.
- auth <string> Autenticação básica, ou seja, 'user:password' para calcular um cabeçalho de Autorização.

Esta função utilitária converte um objeto URL em um objeto de opções comum, conforme esperado pelas APIs http.request() e https.request().

ESMCJS

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'
}
*/

API de URL Legado

[Histórico]

Versão	Alterações
v15.13.0, v14.17.0	Descontinuação revogada. Status alterado para "Legado".
v11.0.0	Esta API está descontinuada.

[Estável: 3 - Legado]

Estável: 3 Estabilidade: 3 - Legado: Utilize a API WHATWG URL em vez disso.

`urlObject` Legado

[Histórico]

Versão	Alterações
v15.13.0, v14.17.0	Descontinuação revogada. Status alterado para "Legado".
v11.0.0	A API de URL Legado está descontinuada. Utilize a API WHATWG URL.

[Estável: 3 - Legado]

Estável: 3 Estabilidade: 3 - Legado: Utilize a API WHATWG URL em vez disso.

O urlObject legado (require('node:url').Url ou import { Url } from 'node:url') é criado e retornado pela função url.parse().

`urlObject.auth`

A propriedade auth é a parte de nome de usuário e senha da URL, também referida como userinfo. Este subconjunto de string segue o protocol e as barras duplas (se presentes) e precede o componente host, delimitado por @. A string é o nome de usuário, ou é o nome de usuário e a senha separados por :.

Por exemplo: 'user:pass'.

`urlObject.hash`

A propriedade hash é a parte do identificador de fragmento da URL, incluindo o caractere # inicial.

Por exemplo: '#hash'.

`urlObject.host`

A propriedade host é a parte completa do host em minúsculas da URL, incluindo a port se especificada.

Por exemplo: 'sub.example.com:8080'.

`urlObject.hostname`

A propriedade hostname é a parte do nome do host em minúsculas do componente host sem a port incluída.

Por exemplo: 'sub.example.com'.

`urlObject.href`

A propriedade href é a string completa da URL que foi analisada, com os componentes protocol e host convertidos para minúsculas.

Por exemplo: 'http://user:[email protected]:8080/p/a/t/h?query=string#hash'.

`urlObject.path`

A propriedade path é uma concatenação dos componentes pathname e search.

Por exemplo: '/p/a/t/h?query=string'.

Nenhuma decodificação do path é realizada.

`urlObject.pathname`

A propriedade pathname consiste em toda a seção de caminho da URL. Isso é tudo o que segue o host (incluindo a port) e antes do início dos componentes query ou hash, delimitado pelos caracteres de ponto de interrogação ASCII (?) ou cerquilha (#).

Por exemplo: '/p/a/t/h'.

Nenhuma decodificação da string de caminho é realizada.

`urlObject.port`

A propriedade port é a parte numérica da porta do componente host.

Por exemplo: '8080'.

`urlObject.protocol`

A propriedade protocol identifica o esquema de protocolo em minúsculas da URL.

Por exemplo: 'http:'.

`urlObject.query`

A propriedade query é a string de consulta sem o ponto de interrogação ASCII inicial (?), ou um objeto retornado pelo método parse() do módulo querystring. Se a propriedade query é uma string ou um objeto é determinado pelo argumento parseQueryString passado para url.parse().

Por exemplo: 'query=string' ou {'query': 'string'}.

Se retornado como uma string, nenhuma decodificação da string de consulta é realizada. Se retornado como um objeto, as chaves e os valores são decodificados.

`urlObject.search`

A propriedade search consiste em toda a parte da "string de consulta" da URL, incluindo o caractere de ponto de interrogação ASCII inicial (?).

Por exemplo: '?query=string'.

Nenhuma decodificação da string de consulta é realizada.

`urlObject.slashes`

A propriedade slashes é um booleano com o valor true se dois caracteres de barra invertida ASCII (/) forem necessários após os dois pontos no protocol.

`url.format(urlObject)`

[Histórico]

Versão	Alterações
v17.0.0	Agora lança uma exceção `ERR_INVALID_URL` quando a conversão Punycode de um nome de host introduz alterações que podem fazer com que a URL seja analisada novamente de forma diferente.
v15.13.0, v14.17.0	Retirada da depreciação. Status alterado para "Legado".
v11.0.0	A API de URL Legada está depreciada. Use a API de URL WHATWG.
v7.0.0	URLs com um esquema `file:` agora sempre usarão o número correto de barras, independentemente da opção `slashes`. Uma opção `slashes` falsa sem protocolo também é respeitada o tempo todo.
v0.1.25	Adicionado em: v0.1.25

[Estável: 3 - Legado]

Estável: 3 Estabilidade: 3 - Legado: Use a API de URL WHATWG em vez disso.

urlObject <Object> | <string> Um objeto URL (como retornado por url.parse() ou construído de outra forma). Se uma string, ela é convertida em um objeto passando-a para url.parse().

O método url.format() retorna uma string de URL formatada derivada de 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'

Se urlObject não for um objeto ou uma string, url.format() lançará um TypeError.

O processo de formatação opera da seguinte maneira:

Uma nova string vazia result é criada.
Se urlObject.protocol for uma string, ela será anexada como está a result.
Caso contrário, se urlObject.protocol não for undefined e não for uma string, um Error será lançado.
Para todos os valores de string de urlObject.protocol que não terminam com um caractere de dois pontos ASCII (:) , a string literal : será anexada a result.
Se alguma das seguintes condições for verdadeira, a string literal // será anexada a result:
- A propriedade urlObject.slashes é verdadeira;
- urlObject.protocol começa com http, https, ftp, gopher ou file;
Se o valor da propriedade urlObject.auth for verdadeiro, e urlObject.host ou urlObject.hostname não forem undefined, o valor de urlObject.auth será convertido em uma string e anexado a result seguido pela string literal @.
Se a propriedade urlObject.host for undefined, então:
- Se o urlObject.hostname for uma string, ele será anexado a result.
- Caso contrário, se urlObject.hostname não for undefined e não for uma string, um Error será lançado.
- Se o valor da propriedade urlObject.port for verdadeiro, e urlObject.hostname não for undefined:
- A string literal : será anexada a result, e
- O valor de urlObject.port é convertido em uma string e anexado a result.
Caso contrário, se o valor da propriedade urlObject.host for verdadeiro, o valor de urlObject.host será convertido em uma string e anexado a result.
Se a propriedade urlObject.pathname for uma string que não seja uma string vazia:
- Se o urlObject.pathname não começar com uma barra invertida ASCII (/), então a string literal '/' será anexada a result.
- O valor de urlObject.pathname é anexado a result.
Caso contrário, se urlObject.pathname não for undefined e não for uma string, um Error será lançado.
Se a propriedade urlObject.search for undefined e se a propriedade urlObject.query for um Object, a string literal ? será anexada a result seguida pela saída da chamada do método stringify() do módulo querystring passando o valor de urlObject.query.
Caso contrário, se urlObject.search for uma string:
- Se o valor de urlObject.search não começar com o caractere de ponto de interrogação ASCII (?), a string literal ? será anexada a result.
- O valor de urlObject.search é anexado a result.
Caso contrário, se urlObject.search não for undefined e não for uma string, um Error será lançado.
Se a propriedade urlObject.hash for uma string:
- Se o valor de urlObject.hash não começar com o caractere de cerquilha ASCII (#), a string literal # será anexada a result.
- O valor de urlObject.hash é anexado a result.
Caso contrário, se a propriedade urlObject.hash não for undefined e não for uma string, um Error será lançado.
result é retornado.

`url.parse(urlString[, parseQueryString[, slashesDenoteHost]])`

[Histórico]

Versão	Alterações
v19.0.0, v18.13.0	Depreciação apenas na documentação.
v15.13.0, v14.17.0	Depreciação revogada. Status alterado para "Legado".
v11.14.0	A propriedade `pathname` no objeto URL retornado agora é `/` quando não há caminho e o esquema do protocolo é `ws:` ou `wss:`.
v11.0.0	A API de URL Legada está depreciada. Use a API WHATWG URL.
v9.0.0	A propriedade `search` no objeto URL retornado agora é `null` quando nenhuma string de consulta está presente.
v0.1.25	Adicionada em: v0.1.25

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto: Use a API WHATWG URL em vez disso.

urlString <string> A string de URL a ser analisada.
parseQueryString <boolean> Se true, a propriedade query sempre será definida como um objeto retornado pelo método parse() do módulo querystring. Se false, a propriedade query no objeto URL retornado será uma string não analisada e não decodificada. Padrão: false.
slashesDenoteHost <boolean> Se true, o primeiro token após a string literal // e antes do próximo / será interpretado como o host. Por exemplo, dado //foo/bar, o resultado seria {host: 'foo', pathname: '/bar'} em vez de {pathname: '//foo/bar'}. Padrão: false.

O método url.parse() recebe uma string de URL, a analisa e retorna um objeto URL.

Um TypeError é lançado se urlString não for uma string.

Um URIError é lançado se a propriedade auth estiver presente, mas não puder ser decodificada.

url.parse() usa um algoritmo tolerante e não padrão para analisar strings de URL. É propenso a problemas de segurança, como spoofing de nome de host e tratamento incorreto de nomes de usuário e senhas. Não use com entrada não confiável. CVEs não são emitidos para vulnerabilidades url.parse(). Use a API WHATWG URL em vez disso.

`url.resolve(from, to)`

[Histórico]

Versão	Alterações
v15.13.0, v14.17.0	Retirada da depreciação. Status alterado para "Legado".
v11.0.0	A API de URL Legada está depreciada. Use a API de URL WHATWG.
v6.6.0	Os campos `auth` agora são mantidos intactos quando `from` e `to` se referem ao mesmo host.
v6.0.0	O campo `auth` é limpo agora que o parâmetro `to` contém um nome de host.
v6.5.0, v4.6.2	O campo `port` agora é copiado corretamente.
v0.1.25	Adicionado em: v0.1.25

[Estável: 3 - Legado]

Estável: 3 Estabilidade: 3 - Legado: Use a API de URL WHATWG em vez disso.

from <string> A URL base a ser usada se to for uma URL relativa.
to <string> A URL de destino a ser resolvida.

O método url.resolve() resolve uma URL de destino em relação a uma URL base de maneira semelhante à de um navegador da web resolvendo uma tag de âncora.

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'

Para alcançar o mesmo resultado usando a API de URL WHATWG:

function resolve(from, to) {
  const resolvedUrl = new URL(to, new URL(from, 'resolve://'))
  if (resolvedUrl.protocol === 'resolve:') {
    // `from` é uma URL relativa.
    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'

Percent-encoding em URLs

URLs só podem conter um determinado intervalo de caracteres. Qualquer caractere que esteja fora desse intervalo deve ser codificado. Como esses caracteres são codificados e quais caracteres devem ser codificados dependem inteiramente de onde o caractere está localizado na estrutura da URL.

API Legado

Dentro da API Legada, espaços (' ') e os seguintes caracteres serão automaticamente escapados nas propriedades dos objetos URL:

text

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

Por exemplo, o caractere de espaço ASCII (' ') é codificado como %20. O caractere de barra (/) ASCII é codificado como %3C.

API WHATWG

O Padrão WHATWG URL usa uma abordagem mais seletiva e granular para selecionar caracteres codificados do que aquela usada pela API Legada.

O algoritmo WHATWG define quatro "conjuntos de codificação percentual" que descrevem intervalos de caracteres que devem ser codificados percentualmente:

O conjunto de codificação percentual de controle C0 inclui pontos de código no intervalo U+0000 a U+001F (inclusive) e todos os pontos de código maiores que U+007E (~).
O conjunto de codificação percentual de fragmento inclui o conjunto de codificação percentual de controle C0 e os pontos de código U+0020 ESPAÇO, U+0022 ("), U+003C (<), U+003E (>), e U+0060 (`).
O conjunto de codificação percentual de caminho inclui o conjunto de codificação percentual de controle C0 e os pontos de código U+0020 ESPAÇO, U+0022 ("), U+0023 (#), U+003C (<), U+003E (>), U+003F (?), U+0060 (`), U+007B ({), e U+007D (}).
O conjunto de codificação percentual de informações do usuário inclui o conjunto de codificação percentual de caminho e os pontos de código U+002F (/), U+003A (😃, U+003B (😉, U+003D (=), U+0040 (@), U+005B ([) a U+005E (^), e U+007C (|).

O conjunto de codificação percentual de informações do usuário é usado exclusivamente para nomes de usuário e senhas codificados dentro da URL. O conjunto de codificação percentual de caminho é usado para o caminho da maioria das URLs. O conjunto de codificação percentual de fragmento é usado para fragmentos de URL. O conjunto de codificação percentual de controle C0 é usado para host e caminho sob certas condições específicas, além de todos os outros casos.

Quando caracteres não-ASCII aparecem dentro de um nome de host, o nome de host é codificado usando o algoritmo Punycode. Observe, no entanto, que um nome de host pode conter tanto caracteres codificados Punycode quanto caracteres codificados percentualmente:

const myURL = new URL('https://%CF%80.example.com/foo')
console.log(myURL.href)
// Imprime https://xn--1xa.example.com/foo
console.log(myURL.origin)
// Imprime https://xn--1xa.example.com

URL ​

Strings de URL e objetos URL ​

Construindo uma URL a partir de partes componentes e obtendo a string construída ​

A API WHATWG URL ​

Classe: URL ​

new URL(input[, base]) ​

url.hash ​

url.host ​

url.hostname ​

url.href ​

url.origin ​

url.password ​

url.pathname ​

url.port ​

url.protocol ​

Esquemas especiais ​

url.search ​

url.searchParams ​

url.username ​

url.toString() ​

url.toJSON() ​

URL.createObjectURL(blob) ​

URL.revokeObjectURL(id) ​

URL.canParse(input[, base]) ​

URL.parse(input[, base]) ​

Classe: 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[, options]) ​

url.format(URL[, options]) ​

url.pathToFileURL(path[, options]) ​

url.urlToHttpOptions(url) ​

API de URL Legado ​

urlObject Legado ​

urlObject.auth ​

urlObject.hash ​

urlObject.host ​

urlObject.hostname ​

urlObject.href ​

urlObject.path ​

urlObject.pathname ​

urlObject.port ​

urlObject.protocol ​

urlObject.query ​

urlObject.search ​

urlObject.slashes ​

url.format(urlObject) ​

url.parse(urlString[, parseQueryString[, slashesDenoteHost]]) ​

url.resolve(from, to) ​

Percent-encoding em URLs ​

API Legado ​

API WHATWG ​

URL

Strings de URL e objetos URL

Construindo uma URL a partir de partes componentes e obtendo a string construída

A API WHATWG URL

Classe: `URL`

`new URL(input[, base])`

`url.hash`

`url.host`

`url.hostname`

`url.href`

`url.origin`

`url.password`

`url.pathname`

`url.port`

`url.protocol`

Esquemas especiais

`url.search`

`url.searchParams`

`url.username`

`url.toString()`

`url.toJSON()`

`URL.createObjectURL(blob)`

`URL.revokeObjectURL(id)`

`URL.canParse(input[, base])`

`URL.parse(input[, base])`

Classe: `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[, options])`

`url.format(URL[, options])`

`url.pathToFileURL(path[, options])`

`url.urlToHttpOptions(url)`

API de URL Legado

`urlObject` Legado

`urlObject.auth`

`urlObject.hash`

`urlObject.host`

`urlObject.hostname`

`urlObject.href`

`urlObject.path`

`urlObject.pathname`

`urlObject.port`

`urlObject.protocol`

`urlObject.query`

`urlObject.search`

`urlObject.slashes`

`url.format(urlObject)`

`url.parse(urlString[, parseQueryString[, slashesDenoteHost]])`

`url.resolve(from, to)`

Percent-encoding em URLs

API Legado

API WHATWG