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:
import url from 'node:url'
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
.
┌────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 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:
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:
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')
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:
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 obtener la cadena URL construida, utilice el accesor de propiedad href
:
console.log(myURL.href)
La API URL WHATWG
Clase: URL
[Historial]
Versión | Cambios |
---|---|
v10.0.0 | La clase ahora está disponible en el objeto global. |
v7.0.0, v6.13.0 | Añ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ón | Cambios |
---|---|
v20.0.0, v18.17.0 | Se eliminó el requisito de ICU. |
input
<string> La URL de entrada absoluta o relativa que se va a analizar. Siinput
es relativa, entoncesbase
es obligatoria. Siinput
es absoluta, labase
se ignora. Siinput
no es una cadena, primero se convierte a una cadena.base
<string> La URL base con la que se resolverá si lainput
no es absoluta. Sibase
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)
.
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:
import { URL } from 'node:url'
console.log(URL === globalThis.URL) // Imprime 'true'.
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:
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.
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.
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.
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.
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.
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.
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ón | Cambios |
---|---|
v15.0.0 | El 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.
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
Obtiene y establece la parte de la contraseña de la URL.
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.
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ón | Cambios |
---|---|
v15.0.0 | El 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:
protocolo | puerto |
---|---|
"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.
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:
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.
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ón | Cambios |
---|---|
v15.0.0 | El 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:
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.
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:
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.
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á:
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.
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()
- Devuelve: <string>
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
- Devuelve: <string>
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()
.
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.
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 aURL.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. Siinput
es relativa, entoncesbase
es obligatoria. Siinput
es absoluta, se ignorabase
. Siinput
no es una cadena, primero se convierte en una cadena.base
<string> La URL base con la que se va a resolver siinput
no es absoluta. Sibase
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
.
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. Siinput
es relativa, entoncesbase
es obligatoria. Siinput
es absoluta, se ignorabase
. Siinput
no es una cadena, primero se convierte en una cadena.base
<string> La URL base para resolver si lainput
no es absoluta. Sibase
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ón | Cambios |
---|---|
v10.0.0 | La clase ahora está disponible en el objeto global. |
v7.5.0, v6.13.0 | Añ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.
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)
string
<string> Una cadena de consulta
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.
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.
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.
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ón | Cambios |
---|---|
v20.2.0, v18.18.0 | Añ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: <Iterator>
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ón | Cambios |
---|---|
v18.0.0 | Pasar 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 consultathisArg
<Object> Se utilizará como valorthis
cuando se llame afn
Itera sobre cada par nombre-valor en la consulta e invoca la función dada.
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 elname
dado.
Devuelve el valor del primer par nombre-valor cuyo nombre es name
. Si no hay tales pares, se devuelve null
.
urlSearchParams.getAll(name)
name
<string>- Devuelve: <string[]>
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ón | Cambios |
---|---|
v20.2.0, v18.18.0 | Se 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: <Iterator>
Devuelve un Iterator
de ES6 sobre los nombres de cada par nombre-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)
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.
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é.
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: <string>
Devuelve los parámetros de búsqueda serializados como una cadena, con los caracteres codificados en porcentaje cuando sea necesario.
urlSearchParams.values()
- Devuelve: <Iterator>
Devuelve un Iterator
ES6 sobre los valores de cada par nombre-valor.
urlSearchParams[Symbol.iterator]()
- Devuelve: <Iterador>
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()
.
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ón | Cambios |
---|---|
v20.0.0, v18.17.0 | Se elimina el requisito de ICU. |
v7.4.0, v6.13.0 | Añ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()
.
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
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ón | Cambios |
---|---|
v20.0.0, v18.17.0 | Se eliminó el requisito de ICU. |
v7.4.0, v6.13.0 | Añ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()
.
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
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ón | Cambios |
---|---|
v22.1.0, v20.13.0 | El argumento options ahora se puede usar para determinar cómo analizar el argumento path . |
v10.12.0 | Añ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 lapath
debe devolverse como una ruta de archivo de Windows,false
para posix yundefined
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.
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)
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 WHATWGoptions
<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.
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])
[Historial]
Versión | Cambios |
---|---|
v22.1.0, v20.13.0 | El argumento options ahora se puede utilizar para determinar cómo devolver el valor path . |
v10.12.0 | Añadido en: v10.12.0 |
path
<string> La ruta para convertir a una URL de archivo.options
<Object>windows
<boolean> | <undefined>true
si lapath
debe tratarse como una ruta de archivo de Windows,false
para posix yundefined
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.
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)
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ón | Cambios |
---|---|
v19.9.0, v18.17.0 | El objeto devuelto también contendrá todas las propiedades enumerables propias del argumento url . |
v15.7.0, v14.18.0 | Añ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()
.
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 heredada
[Historial]
Versión | Cambios |
---|---|
v15.13.0, v14.17.0 | Revocada la obsolescencia. El estado cambió a "Heredado". |
v11.0.0 | Esta API está obsoleta. |
[Estable: 3 - Heredado]
Estable: 3 Estabilidad: 3 - Heredado: Use la API de URL WHATWG en su lugar.
urlObject
heredado
[Historial]
Versión | Cambios |
---|---|
v15.13.0, v14.17.0 | Revocada la obsolescencia. El estado cambió a "Heredado". |
v11.0.0 | La 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ón | Cambios |
---|---|
v17.0.0 | Ahora 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.0 | Revocación de la obsolescencia. El estado cambió a "Legado". |
v11.0.0 | La API de URL heredada está obsoleta. Utilice la API de URL WHATWG. |
v7.0.0 | Las 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.25 | Añ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 porurl.parse()
o construido de otra manera). Si es una cadena, se convierte en un objeto pasándolo aurl.parse()
.
El método url.format()
devuelve una cadena URL formateada 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'
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 aresult
.De lo contrario, si
urlObject.protocol
no esundefined
y no es una cadena, se arroja unError
.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á aresult
.Si se cumple alguna de las siguientes condiciones, la cadena literal
//
se agregará aresult
:- La propiedad
urlObject.slashes
es verdadera; urlObject.protocol
comienza conhttp
,https
,ftp
,gopher
ofile
;
- La propiedad
Si el valor de la propiedad
urlObject.auth
es verdadero, yurlObject.host
ourlObject.hostname
no sonundefined
, el valor deurlObject.auth
se convertirá en una cadena y se agregará aresult
seguido de la cadena literal@
.Si la propiedad
urlObject.host
esundefined
entonces:- Si
urlObject.hostname
es una cadena, se agrega aresult
. - De lo contrario, si
urlObject.hostname
no esundefined
y no es una cadena, se arroja unError
. - Si el valor de la propiedad
urlObject.port
es verdadero, yurlObject.hostname
no esundefined
: - La cadena literal
:
se agrega aresult
, y - El valor de
urlObject.port
se convierte en una cadena y se agrega aresult
.
- Si
De lo contrario, si el valor de la propiedad
urlObject.host
es verdadero, el valor deurlObject.host
se convierte en una cadena y se agrega aresult
.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 aresult
. - El valor de
urlObject.pathname
se agrega aresult
.
- Si
De lo contrario, si
urlObject.pathname
no esundefined
y no es una cadena, se arroja unError
.Si la propiedad
urlObject.search
esundefined
y si la propiedadurlObject.query
es unObject
, la cadena literal?
se agrega aresult
seguido de la salida de llamar al métodostringify()
del móduloquerystring
pasando el valor deurlObject.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 aresult
. - El valor de
urlObject.search
se agrega aresult
.
- Si el valor de
De lo contrario, si
urlObject.search
no esundefined
y no es una cadena, se arroja unError
.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 aresult
. - El valor de
urlObject.hash
se agrega aresult
.
- Si el valor de
De lo contrario, si la propiedad
urlObject.hash
no esundefined
y no es una cadena, se arroja unError
.Se devuelve
result
.
url.parse(urlString[, parseQueryString[, slashesDenoteHost]])
[Historial]
Versión | Cambios |
---|---|
v19.0.0, v18.13.0 | Deprecación solo de documentación. |
v15.13.0, v14.17.0 | Deprecación revocada. Estado cambiado a "Legado". |
v11.14.0 | La propiedad pathname en el objeto URL devuelto ahora es / cuando no hay ruta y el esquema del protocolo es ws: o wss: . |
v11.0.0 | La API de URL heredada está obsoleta. Utilice la API de URL WHATWG. |
v9.0.0 | La propiedad search en el objeto URL devuelto ahora es null cuando no hay una cadena de consulta presente. |
v0.1.25 | Agregado 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 estrue
, la propiedadquery
siempre se establecerá en un objeto devuelto por el métodoparse()
del móduloquerystring
. Si esfalse
, la propiedadquery
en el objeto URL devuelto será una cadena sin analizar ni decodificar. Predeterminado:false
.slashesDenoteHost
<boolean> Si estrue
, el primer token después de la cadena literal//
y antes del siguiente/
se interpretará como elhost
. 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ón | Cambios |
---|---|
v15.13.0, v14.17.0 | Deprecación revocada. Estado cambiado a "Legado". |
v11.0.0 | La API de URL heredada está en desuso. Use la API de URL WHATWG. |
v6.6.0 | Los campos auth ahora se mantienen intactos cuando from y to se refieren al mismo host. |
v6.0.0 | Los campos auth ahora se borran cuando el parámetro to contiene un nombre de host. |
v6.5.0, v4.6.2 | El campo port ahora se copia correctamente. |
v0.1.25 | Agregado 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 sito
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.
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:
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:
< > " ` \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:
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