Skip to content

URL

[Estable: 2 - Estable]

Estable: 2 Estabilidad: 2 - Estable

Código fuente: lib/url.js

El módulo node:url proporciona utilidades para la resolución y el análisis de URLs. Se puede acceder utilizando:

js
import url from 'node:url'
js
const url = require('node:url')

Cadenas de URL y objetos de URL

Una cadena de URL es una cadena estructurada que contiene múltiples componentes significativos. Cuando se analiza, se devuelve un objeto de URL que contiene propiedades para cada uno de estos componentes.

El módulo node:url proporciona dos API para trabajar con URLs: una API heredada que es específica de Node.js y una API más nueva que implementa el mismo Estándar de URL de WHATWG utilizado por los navegadores web.

A continuación, se proporciona una comparación entre las API de WHATWG y la heredada. Encima de la URL 'https://user:[email protected]:8080/p/a/t/h?query=string#hash', se muestran las propiedades de un objeto devuelto por la función heredada url.parse(). Debajo se encuentran las propiedades de un objeto URL de WHATWG.

La propiedad origin de la URL de WHATWG incluye protocol y host, pero no username o 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 los espacios en la línea "" deben ignorarse. Son puramente para formatear).

Análisis de la cadena de URL utilizando la API de WHATWG:

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

Análisis de la cadena de URL utilizando la API heredada:

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

Construcción de una URL a partir de partes componentes y obtención de la cadena construida

Es posible construir una URL WHATWG a partir de partes componentes utilizando los setters de propiedad o una cadena literal de plantilla:

js
const myURL = new URL('https://example.org')
myURL.pathname = '/a/b/c'
myURL.search = '?d=e'
myURL.hash = '#fgh'
js
const pathname = '/a/b/c'
const search = '?d=e'
const hash = '#fgh'
const myURL = new URL(`https://example.org${pathname}${search}${hash}`)

Para obtener la cadena URL construida, utilice el accesor de propiedad href:

js
console.log(myURL.href)

La API URL WHATWG

Clase: URL

[Historial]

VersiónCambios
v10.0.0La clase ahora está disponible en el objeto global.
v7.0.0, v6.13.0Añadido en: v7.0.0, v6.13.0

Clase URL compatible con el navegador, implementada siguiendo el Estándar de URL WHATWG. Ejemplos de URL analizadas se pueden encontrar en el propio Estándar. La clase URL también está disponible en el objeto global.

De acuerdo con las convenciones del navegador, todas las propiedades de los objetos URL se implementan como getters y setters en el prototipo de la clase, en lugar de como propiedades de datos en el propio objeto. Por lo tanto, a diferencia de los legados urlObject, el uso de la palabra clave delete en cualquier propiedad de los objetos URL (por ejemplo, delete myURL.protocol, delete myURL.pathname, etc) no tiene ningún efecto, pero seguirá devolviendo true.

new URL(input[, base])

[Historial]

VersiónCambios
v20.0.0, v18.17.0Se eliminó el requisito de ICU.
  • input <string> La URL de entrada absoluta o relativa que se va a analizar. Si input es relativa, entonces base es obligatoria. Si input es absoluta, la base se ignora. Si input no es una cadena, primero se convierte a una cadena.
  • base <string> La URL base con la que se resolverá si la input no es absoluta. Si base no es una cadena, primero se convierte a una cadena.

Crea un nuevo objeto URL analizando la input en relación con la base. Si base se pasa como una cadena, se analizará de forma equivalente a new URL(base).

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

El constructor de URL es accesible como una propiedad en el objeto global. También se puede importar desde el módulo url incorporado:

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

Se lanzará un TypeError si la input o la base no son URLs válidas. Tenga en cuenta que se hará un esfuerzo para forzar los valores dados a cadenas. Por ejemplo:

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

Los caracteres Unicode que aparezcan en el nombre de host de input se convertirán automáticamente a ASCII utilizando el algoritmo Punycode.

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

En los casos en los que no se sabe de antemano si input es una URL absoluta y se proporciona una base, se aconseja validar que el origin del objeto URL es el esperado.

js
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

Obtiene y establece la parte de fragmento de la URL.

js
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

Los caracteres de URL no válidos incluidos en el valor asignado a la propiedad hash son codificados por porcentaje. La selección de qué caracteres codificar por porcentaje puede variar un poco de lo que los métodos url.parse() y url.format() producirían.

url.host

Obtiene y establece la parte del host de la URL.

js
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

Los valores de host no válidos asignados a la propiedad host se ignoran.

url.hostname

Obtiene y establece la parte del nombre de host de la URL. La diferencia clave entre url.host y url.hostname es que url.hostname no incluye el puerto.

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

// Establecer el nombre de host no cambia el puerto
myURL.hostname = 'example.com'
console.log(myURL.href)
// Imprime https://example.com:81/foo

// Usa myURL.host para cambiar el nombre de host y el puerto
myURL.host = 'example.org:82'
console.log(myURL.href)
// Imprime https://example.org:82/foo

Los valores de nombre de host no válidos asignados a la propiedad hostname se ignoran.

url.href

Obtiene y establece la URL serializada.

js
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

Obtener el valor de la propiedad href es equivalente a llamar a url.toString().

Establecer el valor de esta propiedad a un nuevo valor es equivalente a crear un nuevo objeto URL usando new URL(value). Cada una de las propiedades del objeto URL se modificará.

Si el valor asignado a la propiedad href no es una URL válida, se lanzará un TypeError.

url.origin

[Historial]

VersiónCambios
v15.0.0El esquema "gopher" ya no es especial y url.origin ahora devuelve 'null' para él.

Obtiene la serialización de solo lectura del origen de la URL.

js
const myURL = new URL('https://example.org/foo/bar?baz')
console.log(myURL.origin)
// Imprime https://example.org
js
const idnURL = new URL('https://測試')
console.log(idnURL.origin)
// Imprime https://xn--g6w251d

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

url.password

Obtiene y establece la parte de la contraseña de la URL.

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

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

Los caracteres de URL no válidos incluidos en el valor asignado a la propiedad password están codificados por porcentaje. La selección de qué caracteres codificar por porcentaje puede variar un poco de lo que los métodos url.parse() y url.format() producirían.

url.pathname

Obtiene y establece la parte de la ruta de la URL.

js
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

Los caracteres de URL no válidos incluidos en el valor asignado a la propiedad pathname se codifican por porcentaje. La selección de qué caracteres codificar por porcentaje puede variar un poco de lo que los métodos url.parse() y url.format() producirían.

url.port

[Historial]

VersiónCambios
v15.0.0El esquema "gopher" ya no es especial.

Obtiene y establece la parte del puerto de la URL.

El valor del puerto puede ser un número o una cadena que contenga un número en el rango de 0 a 65535 (inclusive). Establecer el valor al puerto predeterminado de los objetos URL dado el protocolo hará que el valor del puerto se convierta en la cadena vacía ('').

El valor del puerto puede ser una cadena vacía, en cuyo caso el puerto depende del protocolo/esquema:

protocolopuerto
"ftp"21
"file"
"http"80
"https"443
"ws"80
"wss"443

Al asignar un valor al puerto, el valor primero se convertirá en una cadena usando .toString().

Si esa cadena no es válida pero comienza con un número, el número inicial se asigna al puerto. Si el número se encuentra fuera del rango indicado anteriormente, se ignora.

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

// Los puertos predeterminados se transforman automáticamente en la cadena vacía
// (El puerto predeterminado del protocolo HTTPS es 443)
myURL.port = '443'
console.log(myURL.port)
// Imprime la cadena vacía
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/

// Las cadenas de puerto completamente no válidas se ignoran
myURL.port = 'abcd'
console.log(myURL.port)
// Imprime 1234

// Los números iniciales se tratan como un número de puerto
myURL.port = '5678abcd'
console.log(myURL.port)
// Imprime 5678

// Los números no enteros se truncan
myURL.port = 1234.5678
console.log(myURL.port)
// Imprime 1234

// Los números fuera de rango que no están representados en notación científica
// serán ignorados.
myURL.port = 1e10 // 10000000000, se verificará el rango como se describe a continuación
console.log(myURL.port)
// Imprime 1234

Los números que contienen un punto decimal, como los números de punto flotante o los números en notación científica, no son una excepción a esta regla. Los números iniciales hasta el punto decimal se establecerán como el puerto de la URL, suponiendo que sean válidos:

js
myURL.port = 4.567e21
console.log(myURL.port)
// Imprime 4 (porque es el número inicial en la cadena '4.567e21')

url.protocol

Obtiene y establece la parte del protocolo de la URL.

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

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

Los valores de protocolo de URL no válidos asignados a la propiedad protocol se ignoran.

Esquemas especiales

[Historial]

VersiónCambios
v15.0.0El esquema "gopher" ya no es especial.

El Estándar de URL de WHATWG considera que un puñado de esquemas de protocolo de URL son especiales en términos de cómo se analizan y serializan. Cuando se analiza una URL utilizando uno de estos protocolos especiales, la propiedad url.protocol se puede cambiar a otro protocolo especial, pero no se puede cambiar a un protocolo no especial, y viceversa.

Por ejemplo, cambiar de http a https funciona:

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

Sin embargo, cambiar de http a un hipotético protocolo fish no funciona porque el nuevo protocolo no es especial.

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

Del mismo modo, tampoco está permitido cambiar de un protocolo no especial a un protocolo especial:

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

Según el Estándar de URL de WHATWG, los esquemas de protocolo especiales son ftp, file, http, https, ws y wss.

url.search

Obtiene y establece la porción de consulta serializada de la URL.

js
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

Cualquier carácter de URL inválido que aparezca en el valor asignado a la propiedad search será codificado por porcentaje. La selección de qué caracteres codificar por porcentaje puede variar un poco de lo que producirían los métodos url.parse() y url.format().

url.searchParams

Obtiene el objeto URLSearchParams que representa los parámetros de consulta de la URL. Esta propiedad es de solo lectura, pero el objeto URLSearchParams que proporciona se puede utilizar para mutar la instancia de URL; para reemplazar la totalidad de los parámetros de consulta de la URL, utilice el establecedor url.search. Consulte la documentación de URLSearchParams para obtener más detalles.

Tenga cuidado al usar .searchParams para modificar la URL porque, según la especificación de WHATWG, el objeto URLSearchParams usa diferentes reglas para determinar qué caracteres codificar por porcentaje. Por ejemplo, el objeto URL no codificará por porcentaje el carácter ASCII tilde (~), mientras que URLSearchParams siempre lo codificará:

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

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

// Modificar la URL a través de searchParams...
myURL.searchParams.sort()

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

url.username

Obtiene y establece la parte del nombre de usuario de la URL.

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

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

Cualquier carácter de URL no válido que aparezca en el valor asignado a la propiedad username se codificará mediante porcentajes. La selección de qué caracteres codificar mediante porcentajes puede variar un poco de lo que producirían los métodos url.parse() y url.format().

url.toString()

El método toString() en el objeto URL devuelve la URL serializada. El valor devuelto es equivalente al de url.href y url.toJSON().

url.toJSON()

Agregado en: v7.7.0, v6.13.0

El método toJSON() en el objeto URL devuelve la URL serializada. El valor devuelto es equivalente al de url.href y url.toString().

Este método se llama automáticamente cuando un objeto URL se serializa con JSON.stringify().

js
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)

Agregado en: v16.7.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

Crea una cadena de URL 'blob:nodedata:...' que representa el objeto <Blob> dado y se puede utilizar para recuperar el Blob más adelante.

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

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

// más tarde...

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

Los datos almacenados por el <Blob> registrado se conservarán en la memoria hasta que se llame a URL.revokeObjectURL() para eliminarlos.

Los objetos Blob se registran dentro del hilo actual. Si se utilizan Worker Threads, los objetos Blob registrados dentro de un Worker no estarán disponibles para otros workers ni para el hilo principal.

URL.revokeObjectURL(id)

Añadido en: v16.7.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1 - Experimental

  • id <string> Una cadena URL 'blob:nodedata:... devuelta por una llamada anterior a URL.createObjectURL().

Elimina el <Blob> almacenado identificado por el ID dado. Intentar revocar un ID que no esté registrado fallará silenciosamente.

URL.canParse(input[, base])

Añadido en: v19.9.0, v18.17.0

  • input <string> La URL de entrada absoluta o relativa que se va a analizar. Si input es relativa, entonces base es obligatoria. Si input es absoluta, se ignora base. Si input no es una cadena, primero se convierte en una cadena.
  • base <string> La URL base con la que se va a resolver si input no es absoluta. Si base no es una cadena, primero se convierte en una cadena.
  • Devuelve: <boolean>

Comprueba si una input relativa a la base se puede analizar a una URL.

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

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

URL.parse(input[, base])

Añadido en: v22.1.0

  • input <string> La URL de entrada absoluta o relativa para analizar. Si input es relativa, entonces base es obligatoria. Si input es absoluta, se ignora base. Si input no es una cadena, primero se convierte en una cadena.
  • base <string> La URL base para resolver si la input no es absoluta. Si base no es una cadena, primero se convierte en una cadena.
  • Devuelve: <URL> | <null>

Analiza una cadena como una URL. Si se proporciona base, se utilizará como la URL base con el fin de resolver las URL input no absolutas. Devuelve null si input no es válida.

Clase: URLSearchParams

[Historial]

VersiónCambios
v10.0.0La clase ahora está disponible en el objeto global.
v7.5.0, v6.13.0Añadido en: v7.5.0, v6.13.0

La API URLSearchParams proporciona acceso de lectura y escritura a la consulta de una URL. La clase URLSearchParams también se puede usar de forma independiente con uno de los cuatro constructores siguientes. La clase URLSearchParams también está disponible en el objeto global.

La interfaz WHATWG URLSearchParams y el módulo querystring tienen un propósito similar, pero el propósito del módulo querystring es más general, ya que permite la personalización de los caracteres delimitadores (& y =). Por otro lado, esta API está diseñada puramente para cadenas de consulta de URL.

js
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)
// Lo anterior es 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() se llama implícitamente
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 un nuevo objeto URLSearchParams vacío.

new URLSearchParams(string)

Analiza la string como una cadena de consulta, y la usa para instanciar un nuevo objeto URLSearchParams. El carácter '?' inicial, si está presente, se ignora.

js
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)

Añadido en: v7.10.0, v6.13.0

  • obj <Object> Un objeto que representa una colección de pares clave-valor

Instancia un nuevo objeto URLSearchParams con un mapa hash de consulta. La clave y el valor de cada propiedad de obj siempre se fuerzan a cadenas.

A diferencia del módulo querystring, no se permiten claves duplicadas en forma de valores de array. Los arrays se convierten en cadenas usando array.toString(), que simplemente une todos los elementos del array con comas.

js
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)

Añadido en: v7.10.0, v6.13.0

  • iterable <Iterable> Un objeto iterable cuyos elementos son pares clave-valor

Instancia un nuevo objeto URLSearchParams con un mapa iterable de manera similar al constructor de Map. iterable puede ser un Array o cualquier objeto iterable. Eso significa que iterable puede ser otro URLSearchParams, en cuyo caso el constructor simplemente creará un clon del URLSearchParams proporcionado. Los elementos de iterable son pares clave-valor, y a su vez pueden ser cualquier objeto iterable.

Se permiten claves duplicadas.

js
let params

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

// Usando un 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 una función generadora
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 clave-valor debe tener exactamente dos elementos
new URLSearchParams([['user', 'abc', 'error']])
// Lanza TypeError [ERR_INVALID_TUPLE]:
//        Cada par de consulta debe ser una tupla iterable [nombre, valor]

urlSearchParams.append(name, value)

Agrega un nuevo par nombre-valor a la cadena de consulta.

urlSearchParams.delete(name[, value])

[Historial]

VersiónCambios
v20.2.0, v18.18.0Añade soporte para el argumento opcional value.

Si se proporciona value, elimina todos los pares nombre-valor donde el nombre es name y el valor es value.

Si no se proporciona value, elimina todos los pares nombre-valor cuyo nombre es name.

urlSearchParams.entries()

Devuelve un Iterator ES6 sobre cada uno de los pares nombre-valor en la consulta. Cada elemento del iterador es un Array de JavaScript. El primer elemento del Array es el nombre, el segundo elemento del Array es el valor.

Alias para urlSearchParams[@@iterator]().

urlSearchParams.forEach(fn[, thisArg])

[Historial]

VersiónCambios
v18.0.0Pasar una devolución de llamada no válida al argumento fn ahora lanza ERR_INVALID_ARG_TYPE en lugar de ERR_INVALID_CALLBACK.
  • fn <Function> Se invoca para cada par nombre-valor en la consulta
  • thisArg <Object> Se utilizará como valor this cuando se llame a fn

Itera sobre cada par nombre-valor en la consulta e invoca la función dada.

js
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>
  • Devuelve: <string> | <null> Una cadena o null si no hay ningún par nombre-valor con el name dado.

Devuelve el valor del primer par nombre-valor cuyo nombre es name. Si no hay tales pares, se devuelve null.

urlSearchParams.getAll(name)

Devuelve los valores de todos los pares nombre-valor cuyo nombre es name. Si no hay tales pares, se devuelve un array vacío.

urlSearchParams.has(name[, value])

[Historial]

VersiónCambios
v20.2.0, v18.18.0Se añade soporte para el argumento opcional value.

Comprueba si el objeto URLSearchParams contiene uno o más pares clave-valor basados en name y un argumento value opcional.

Si se proporciona value, devuelve true cuando existe un par nombre-valor con el mismo name y value.

Si no se proporciona value, devuelve true si hay al menos un par nombre-valor cuyo nombre sea name.

urlSearchParams.keys()

Devuelve un Iterator de ES6 sobre los nombres de cada par nombre-valor.

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

urlSearchParams.set(name, value)

Establece el valor en el objeto URLSearchParams asociado con name a value. Si existen pares nombre-valor preexistentes cuyos nombres sean name, establece el valor del primer par a value y elimina todos los demás. Si no, agrega el par nombre-valor a la cadena de consulta.

js
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

Agregado en: v19.8.0, v18.16.0

El número total de entradas de parámetros.

urlSearchParams.sort()

Agregado en: v7.7.0, v6.13.0

Ordena todos los pares nombre-valor existentes en el mismo lugar por sus nombres. La ordenación se realiza con un algoritmo de ordenación estable, por lo que se conserva el orden relativo entre los pares nombre-valor con el mismo nombre.

Este método se puede utilizar, en particular, para aumentar los aciertos de caché.

js
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()

Devuelve los parámetros de búsqueda serializados como una cadena, con los caracteres codificados en porcentaje cuando sea necesario.

urlSearchParams.values()

Devuelve un Iterator ES6 sobre los valores de cada par nombre-valor.

urlSearchParams[Symbol.iterator]()

Devuelve un Iterador ES6 sobre cada uno de los pares nombre-valor en la cadena de consulta. Cada elemento del iterador es un Array de JavaScript. El primer elemento del Array es el nombre, el segundo elemento del Array es el valor.

Alias para urlSearchParams.entries().

js
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)

[Historial]

VersiónCambios
v20.0.0, v18.17.0Se elimina el requisito de ICU.
v7.4.0, v6.13.0Añadido en: v7.4.0, v6.13.0

Devuelve la serialización ASCII Punycode del dominio. Si domain es un dominio inválido, se devuelve la cadena vacía.

Realiza la operación inversa a url.domainToUnicode().

js
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 una cadena vacía
js
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 una cadena vacía

url.domainToUnicode(domain)

[Historial]

VersiónCambios
v20.0.0, v18.17.0Se eliminó el requisito de ICU.
v7.4.0, v6.13.0Añadido en: v7.4.0, v6.13.0

Devuelve la serialización Unicode del dominio. Si domain no es un dominio válido, se devuelve una cadena vacía.

Realiza la operación inversa a url.domainToASCII().

js
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 una cadena vacía
js
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 una cadena vacía

url.fileURLToPath(url[, options])

[Historial]

VersiónCambios
v22.1.0, v20.13.0El argumento options ahora se puede usar para determinar cómo analizar el argumento path.
v10.12.0Añadido en: v10.12.0
  • url <URL> | <string> La cadena de URL de archivo u objeto URL para convertir a una ruta.
  • options <Object>
    • windows <boolean> | <undefined> true si la path debe devolverse como una ruta de archivo de Windows, false para posix y undefined para el valor predeterminado del sistema. Predeterminado: undefined.
  • Devuelve: <string> La ruta de archivo de Node.js específica de la plataforma totalmente resuelta.

Esta función garantiza las decodificaciones correctas de los caracteres codificados en porcentaje, así como garantizar una cadena de ruta absoluta válida multiplataforma.

js
import { fileURLToPath } from 'node:url'

const __filename = fileURLToPath(import.meta.url)

new URL('file:///C:/path/').pathname // Incorrecto: /C:/path/
fileURLToPath('file:///C:/path/') // Correcto:   C:\path\ (Windows)

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

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

new URL('file:///hello world').pathname // Incorrecto: /hello%20world
fileURLToPath('file:///hello world') // Correcto:   /hello world (POSIX)
js
const { fileURLToPath } = require('node:url')
new URL('file:///C:/path/').pathname // Incorrecto: /C:/path/
fileURLToPath('file:///C:/path/') // Correcto:   C:\path\ (Windows)

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

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

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

url.format(URL[, options])

Añadido en: v7.6.0

  • URL <URL> Un objeto URL WHATWG
  • options <Objeto>
    • auth <booleano> true si la cadena URL serializada debe incluir el nombre de usuario y la contraseña, false de lo contrario. Predeterminado: true.
    • fragment <booleano> true si la cadena URL serializada debe incluir el fragmento, false de lo contrario. Predeterminado: true.
    • search <booleano> true si la cadena URL serializada debe incluir la consulta de búsqueda, false de lo contrario. Predeterminado: true.
    • unicode <booleano> true si los caracteres Unicode que aparecen en el componente host de la cadena URL se deben codificar directamente en lugar de codificarse como Punycode. Predeterminado: false.
  • Devuelve: <cadena>

Devuelve una serialización personalizable de una representación de Cadena URL de un objeto URL WHATWG.

El objeto URL tiene tanto un método toString() como una propiedad href que devuelven serializaciones de cadena de la URL. Sin embargo, estos no son personalizables de ninguna manera. El método url.format(URL[, options]) permite una personalización básica de la salida.

js
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'
js
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])

[Historial]

VersiónCambios
v22.1.0, v20.13.0El argumento options ahora se puede utilizar para determinar cómo devolver el valor path.
v10.12.0Añadido en: v10.12.0
  • path <string> La ruta para convertir a una URL de archivo.

  • options <Object>

    • windows <boolean> | <undefined> true si la path debe tratarse como una ruta de archivo de Windows, false para posix y undefined para el valor predeterminado del sistema. Predeterminado: undefined.
  • Devuelve: <URL> El objeto URL de archivo.

Esta función asegura que la path se resuelva de forma absoluta y que los caracteres de control de la URL se codifiquen correctamente al convertir a una URL de archivo.

js
import { pathToFileURL } from 'node:url'

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

new URL('/some/path%.c', 'file:') // Incorrecto: file:///some/path%.c
pathToFileURL('/some/path%.c') // Correcto:   file:///some/path%25.c (POSIX)
js
const { pathToFileURL } = require('node:url')
new URL(__filename) // Incorrecto: lanza una excepción (POSIX)
new URL(__filename) // Incorrecto: C:\... (Windows)
pathToFileURL(__filename) // Correcto:   file:///... (POSIX)
pathToFileURL(__filename) // Correcto:   file:///C:/... (Windows)

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

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

url.urlToHttpOptions(url)

[Historial]

VersiónCambios
v19.9.0, v18.17.0El objeto devuelto también contendrá todas las propiedades enumerables propias del argumento url.
v15.7.0, v14.18.0Añadido en: v15.7.0, v14.18.0
  • url <URL> El objeto WHATWG URL para convertirlo en un objeto de opciones.
  • Devuelve: <Object> Objeto de opciones
    • protocol <string> Protocolo a usar.
    • hostname <string> Un nombre de dominio o dirección IP del servidor al que se debe enviar la solicitud.
    • hash <string> La porción de fragmento de la URL.
    • search <string> La porción de consulta serializada de la URL.
    • pathname <string> La porción de ruta de la URL.
    • path <string> Ruta de la solicitud. Debería incluir la cadena de consulta si existe. Ej. '/index.html?page=12'. Se produce una excepción cuando la ruta de la solicitud contiene caracteres ilegales. Actualmente, solo se rechazan los espacios, pero eso puede cambiar en el futuro.
    • href <string> La URL serializada.
    • port <number> Puerto del servidor remoto.
    • auth <string> Autenticación básica, p. ej. 'usuario:contraseña' para calcular un encabezado de autorización.

Esta función de utilidad convierte un objeto URL en un objeto de opciones ordinario como se espera en las API http.request() y https.request().

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

[Historial]

VersiónCambios
v15.13.0, v14.17.0Revocada la obsolescencia. El estado cambió a "Heredado".
v11.0.0Esta API está obsoleta.

[Estable: 3 - Heredado]

Estable: 3 Estabilidad: 3 - Heredado: Use la API de URL WHATWG en su lugar.

urlObject heredado

[Historial]

VersiónCambios
v15.13.0, v14.17.0Revocada la obsolescencia. El estado cambió a "Heredado".
v11.0.0La API de URL heredada está obsoleta. Use la API de URL WHATWG.

[Estable: 3 - Heredado]

Estable: 3 Estabilidad: 3 - Heredado: Use la API de URL WHATWG en su lugar.

El urlObject heredado (require('node:url').Url o import { Url } from 'node:url') es creado y devuelto por la función url.parse().

urlObject.auth

La propiedad auth es la porción de nombre de usuario y contraseña de la URL, también conocida como userinfo. Esta subcadena sigue al protocol y a las dobles barras (si están presentes) y precede al componente host, delimitado por @. La cadena es el nombre de usuario, o es el nombre de usuario y la contraseña separados por :.

Por ejemplo: 'usuario:contraseña'.

urlObject.hash

La propiedad hash es la porción del identificador de fragmento de la URL, incluyendo el carácter # inicial.

Por ejemplo: '#hash'.

urlObject.host

La propiedad host es la porción completa del host en minúsculas de la URL, incluyendo el port si se especifica.

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

urlObject.hostname

La propiedad hostname es la porción del nombre de host en minúsculas del componente host sin incluir el port.

Por ejemplo: 'sub.example.com'.

urlObject.href

La propiedad href es la cadena de URL completa que se analizó con los componentes protocol y host convertidos a minúsculas.

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

urlObject.path

La propiedad path es una concatenación de los componentes pathname y search.

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

No se realiza ninguna decodificación del path.

urlObject.pathname

La propiedad pathname consiste en la sección de ruta completa de la URL. Esto es todo lo que sigue al host (incluyendo el port) y antes del inicio de los componentes query o hash, delimitado por el signo de interrogación ASCII (?) o los caracteres de hash (#).

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

No se realiza ninguna decodificación de la cadena de ruta.

urlObject.port

La propiedad port es la porción numérica del puerto del componente host.

Por ejemplo: '8080'.

urlObject.protocol

La propiedad protocol identifica el esquema del protocolo de la URL en minúsculas.

Por ejemplo: 'http:'.

urlObject.query

La propiedad query es la cadena de consulta sin el signo de interrogación ASCII inicial (?), o un objeto devuelto por el método parse() del módulo querystring. Si la propiedad query es una cadena o un objeto, se determina por el argumento parseQueryString pasado a url.parse().

Por ejemplo: 'query=string' o {'query': 'string'}.

Si se devuelve como una cadena, no se realiza ninguna decodificación de la cadena de consulta. Si se devuelve como un objeto, tanto las claves como los valores se decodifican.

urlObject.search

La propiedad search consiste en la porción completa de "cadena de consulta" de la URL, incluido el carácter de signo de interrogación ASCII inicial (?).

Por ejemplo: '?query=string'.

No se realiza ninguna decodificación de la cadena de consulta.

urlObject.slashes

La propiedad slashes es un boolean con un valor de true si se requieren dos caracteres de barra inclinada ASCII (/) después de los dos puntos en el protocol.

url.format(urlObject)

[Historial]

VersiónCambios
v17.0.0Ahora arroja una excepción ERR_INVALID_URL cuando la conversión de Punycode de un nombre de host introduce cambios que podrían provocar que la URL se vuelva a analizar de manera diferente.
v15.13.0, v14.17.0Revocación de la obsolescencia. El estado cambió a "Legado".
v11.0.0La API de URL heredada está obsoleta. Utilice la API de URL WHATWG.
v7.0.0Las URL con un esquema file: ahora siempre usarán el número correcto de barras inclinadas independientemente de la opción slashes. Una opción slashes falsa sin protocolo ahora también se respeta en todo momento.
v0.1.25Añadido en: v0.1.25

[Estable: 3 - Legado]

Estable: 3 Estabilidad: 3 - Legado: Utilice la API de URL WHATWG en su lugar.

  • urlObject <Object> | <string> Un objeto URL (como el devuelto por url.parse() o construido de otra manera). Si es una cadena, se convierte en un objeto pasándolo a url.parse().

El método url.format() devuelve una cadena URL formateada derivada de urlObject.

js
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'

Si urlObject no es un objeto o una cadena, url.format() arrojará un TypeError.

El proceso de formateo funciona de la siguiente manera:

  • Se crea una nueva cadena vacía result.

  • Si urlObject.protocol es una cadena, se agrega tal cual a result.

  • De lo contrario, si urlObject.protocol no es undefined y no es una cadena, se arroja un Error.

  • Para todos los valores de cadena de urlObject.protocol que no terminan con un carácter de dos puntos ASCII (:), la cadena literal : se agregará a result.

  • Si se cumple alguna de las siguientes condiciones, la cadena literal // se agregará a result:

    • La propiedad urlObject.slashes es verdadera;
    • urlObject.protocol comienza con http, https, ftp, gopher o file;
  • Si el valor de la propiedad urlObject.auth es verdadero, y urlObject.host o urlObject.hostname no son undefined, el valor de urlObject.auth se convertirá en una cadena y se agregará a result seguido de la cadena literal @.

  • Si la propiedad urlObject.host es undefined entonces:

    • Si urlObject.hostname es una cadena, se agrega a result.
    • De lo contrario, si urlObject.hostname no es undefined y no es una cadena, se arroja un Error.
    • Si el valor de la propiedad urlObject.port es verdadero, y urlObject.hostname no es undefined:
    • La cadena literal : se agrega a result, y
    • El valor de urlObject.port se convierte en una cadena y se agrega a result.
  • De lo contrario, si el valor de la propiedad urlObject.host es verdadero, el valor de urlObject.host se convierte en una cadena y se agrega a result.

  • Si la propiedad urlObject.pathname es una cadena que no es una cadena vacía:

    • Si urlObject.pathname no comienza con una barra inclinada ASCII (/), entonces la cadena literal '/' se agrega a result.
    • El valor de urlObject.pathname se agrega a result.
  • De lo contrario, si urlObject.pathname no es undefined y no es una cadena, se arroja un Error.

  • Si la propiedad urlObject.search es undefined y si la propiedad urlObject.query es un Object, la cadena literal ? se agrega a result seguido de la salida de llamar al método stringify() del módulo querystring pasando el valor de urlObject.query.

  • De lo contrario, si urlObject.search es una cadena:

    • Si el valor de urlObject.search no comienza con el carácter de signo de interrogación ASCII (?), la cadena literal ? se agrega a result.
    • El valor de urlObject.search se agrega a result.
  • De lo contrario, si urlObject.search no es undefined y no es una cadena, se arroja un Error.

  • Si la propiedad urlObject.hash es una cadena:

    • Si el valor de urlObject.hash no comienza con el carácter hash ASCII (#), la cadena literal # se agrega a result.
    • El valor de urlObject.hash se agrega a result.
  • De lo contrario, si la propiedad urlObject.hash no es undefined y no es una cadena, se arroja un Error.

  • Se devuelve result.

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

[Historial]

VersiónCambios
v19.0.0, v18.13.0Deprecación solo de documentación.
v15.13.0, v14.17.0Deprecación revocada. Estado cambiado a "Legado".
v11.14.0La propiedad pathname en el objeto URL devuelto ahora es / cuando no hay ruta y el esquema del protocolo es ws: o wss:.
v11.0.0La API de URL heredada está obsoleta. Utilice la API de URL WHATWG.
v9.0.0La propiedad search en el objeto URL devuelto ahora es null cuando no hay una cadena de consulta presente.
v0.1.25Agregado en: v0.1.25

[Estable: 0 - Obsoleto]

Estable: 0 Estabilidad: 0 - Obsoleto: Utilice la API de URL WHATWG en su lugar.

  • urlString <string> La cadena de URL a analizar.
  • parseQueryString <boolean> Si es true, la propiedad query siempre se establecerá en un objeto devuelto por el método parse() del módulo querystring. Si es false, la propiedad query en el objeto URL devuelto será una cadena sin analizar ni decodificar. Predeterminado: false.
  • slashesDenoteHost <boolean> Si es true, el primer token después de la cadena literal // y antes del siguiente / se interpretará como el host. Por ejemplo, dado //foo/bar, el resultado sería {host: 'foo', pathname: '/bar'} en lugar de {pathname: '//foo/bar'}. Predeterminado: false.

El método url.parse() toma una cadena de URL, la analiza y devuelve un objeto URL.

Se lanza un TypeError si urlString no es una cadena.

Se lanza un URIError si la propiedad auth está presente pero no se puede decodificar.

url.parse() utiliza un algoritmo tolerante y no estándar para analizar cadenas de URL. Es propenso a problemas de seguridad como la suplantación de nombres de host y el manejo incorrecto de nombres de usuario y contraseñas. No usar con entradas no confiables. No se emiten CVE para vulnerabilidades de url.parse(). Utilice la API WHATWG URL en su lugar.

url.resolve(from, to)

[Historial]

VersiónCambios
v15.13.0, v14.17.0Deprecación revocada. Estado cambiado a "Legado".
v11.0.0La API de URL heredada está en desuso. Use la API de URL WHATWG.
v6.6.0Los campos auth ahora se mantienen intactos cuando from y to se refieren al mismo host.
v6.0.0Los campos auth ahora se borran cuando el parámetro to contiene un nombre de host.
v6.5.0, v4.6.2El campo port ahora se copia correctamente.
v0.1.25Agregado en: v0.1.25

[Estable: 3 - Legado]

Estable: 3 Estabilidad: 3 - Legado: Use la API de URL WHATWG en su lugar.

  • from <string> La URL base para usar si to es una URL relativa.
  • to <string> La URL de destino para resolver.

El método url.resolve() resuelve una URL de destino relativa a una URL base de una manera similar a la de un navegador web que resuelve una etiqueta de ancla.

js
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 lograr el mismo resultado usando la API de URL WHATWG:

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

Codificación de porcentaje en las URL

Las URL solo pueden contener un rango determinado de caracteres. Cualquier carácter que quede fuera de ese rango debe codificarse. La forma en que se codifican estos caracteres y qué caracteres codificar depende completamente de dónde se encuentre el carácter dentro de la estructura de la URL.

API heredada

Dentro de la API heredada, los espacios (' ') y los siguientes caracteres se escaparán automáticamente en las propiedades de los objetos URL:

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

Por ejemplo, el carácter de espacio ASCII (' ') se codifica como %20. El carácter de barra diagonal ASCII (/) se codifica como %3C.

API WHATWG

El estándar de URL de WHATWG utiliza un enfoque más selectivo y preciso para seleccionar caracteres codificados que el utilizado por la API heredada.

El algoritmo de WHATWG define cuatro "conjuntos de codificación de porcentaje" que describen rangos de caracteres que deben codificarse con porcentaje:

  • El conjunto de codificación de porcentaje de control C0 incluye puntos de código en el rango U+0000 a U+001F (inclusive) y todos los puntos de código mayores que U+007E (~).
  • El conjunto de codificación de porcentaje de fragmento incluye el conjunto de codificación de porcentaje de control C0 y los puntos de código U+0020 ESPACIO, U+0022 ("), U+003C (<), U+003E (>) y U+0060 (`).
  • El conjunto de codificación de porcentaje de ruta incluye el conjunto de codificación de porcentaje de control C0 y los puntos de código U+0020 ESPACIO, U+0022 ("), U+0023 (#), U+003C (<), U+003E (>), U+003F (?), U+0060 (`), U+007B ({) y U+007D (}).
  • El conjunto de codificación de información de usuario incluye el conjunto de codificación de porcentaje de ruta y los puntos de código U+002F (/), U+003A (😃, U+003B (😉, U+003D (=), U+0040 (@), U+005B ([) a U+005E(^) y U+007C (|).

El conjunto de codificación de porcentaje de información de usuario se utiliza exclusivamente para nombres de usuario y contraseñas codificados dentro de la URL. El conjunto de codificación de porcentaje de ruta se utiliza para la ruta de la mayoría de las URL. El conjunto de codificación de porcentaje de fragmento se utiliza para los fragmentos de URL. El conjunto de codificación de porcentaje de control C0 se utiliza para el host y la ruta en ciertas condiciones específicas, además de todos los demás casos.

Cuando aparecen caracteres no ASCII dentro de un nombre de host, el nombre de host se codifica utilizando el algoritmo Punycode. Sin embargo, tenga en cuenta que un nombre de host puede contener tanto caracteres codificados con Punycode como caracteres codificados con porcentaje:

js
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