URL

[Stable : 2 - Stable]

Source Code : lib/url.js

Le module node:url fournit des utilitaires pour la résolution et l'analyse des URL. Il est accessible via :

ESMCJS

import url from 'node:url'

const url = require('node:url')

Chaînes URL et objets URL

Une chaîne URL est une chaîne structurée contenant plusieurs composants significatifs. Lorsqu'elle est analysée, un objet URL est renvoyé contenant les propriétés de chacun de ces composants.

Le module node:url fournit deux API pour travailler avec les URL : une API héritée spécifique à Node.js et une API plus récente qui implémente la même norme URL WHATWG utilisée par les navigateurs Web.

Une comparaison entre les API WHATWG et héritées est fournie ci-dessous. Au-dessus de l'URL 'https://user:[email protected]:8080/p/a/t/h?query=string#hash', les propriétés d'un objet renvoyé par l'ancienne fonction url.parse() sont affichées. Ci-dessous, les propriétés d'un objet URL WHATWG.

La propriété origin de l'URL WHATWG inclut protocol et host, mais pas username ou password.

text

┌────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                              href                                              │
├──────────┬──┬─────────────────────┬────────────────────────┬───────────────────────────┬───────┤
│ protocol │  │        auth         │          host          │           path            │ hash  │
│          │  │                     ├─────────────────┬──────┼──────────┬────────────────┤       │
│          │  │                     │    hostname     │ port │ pathname │     search     │       │
│          │  │                     │                 │      │          ├─┬──────────────┤       │
│          │  │                     │                 │      │          │ │    query     │       │
"  https:   //    user   :   pass   @ sub.example.com : 8080   /p/a/t/h  ?  query=string   #hash "
│          │  │          │          │    hostname     │ port │          │                │       │
│          │  │          │          ├─────────────────┴──────┤          │                │       │
│ protocol │  │ username │ password │          host          │          │                │       │
├──────────┴──┼──────────┴──────────┼────────────────────────┤          │                │       │
│   origin    │                     │         origin         │ pathname │     search     │ hash  │
├─────────────┴─────────────────────┴────────────────────────┴──────────┴────────────────┴───────┤
│                                              href                                              │
└────────────────────────────────────────────────────────────────────────────────────────────────┘
(Tous les espaces dans la ligne "" doivent être ignorés. Ils ne servent qu'à la mise en forme.)

Analyse de la chaîne URL à l'aide de l'API WHATWG :

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

Analyse de la chaîne URL à l'aide de l'API héritée :

ESMCJS

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

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

Construction d'une URL à partir de composants et récupération de la chaîne construite

Il est possible de construire une URL WHATWG à partir de composants en utilisant soit les accesseurs de propriétés, soit une chaîne littérale de modèle :

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

Pour obtenir la chaîne d'URL construite, utilisez l'accesseur de propriété href :

console.log(myURL.href)

L'API WHATWG URL

Classe : `URL`

[Historique]

Version	Modifications
v10.0.0	La classe est désormais disponible sur l'objet global.
v7.0.0, v6.13.0	Ajoutée dans : v7.0.0, v6.13.0

Classe URL compatible avec les navigateurs, implémentée en suivant la norme WHATWG URL. Des exemples d'URL analysées peuvent être trouvés dans la norme elle-même. La classe URL est également disponible sur l'objet global.

Conformément aux conventions des navigateurs, toutes les propriétés des objets URL sont implémentées en tant qu'accesseurs getter et setter sur le prototype de la classe, plutôt qu'en tant que propriétés de données sur l'objet lui-même. Ainsi, contrairement aux anciens urlObject, l'utilisation du mot clé delete sur les propriétés des objets URL (par exemple, delete myURL.protocol, delete myURL.pathname, etc.) n'a aucun effet, mais renverra toujours true.

`new URL(input[, base])`

[Historique]

Version	Modifications
v20.0.0, v18.17.0	La condition requise pour ICU est supprimée.

input <string> L'URL d'entrée absolue ou relative à analyser. Si input est relatif, alors base est requis. Si input est absolu, base est ignoré. Si input n'est pas une chaîne, il est d'abord converti en chaîne.
base <string> L'URL de base à résoudre si input n'est pas absolu. Si base n'est pas une chaîne, il est d'abord converti en chaîne.

Crée un nouvel objet URL en analysant l'entrée input par rapport à la base base. Si base est passé en tant que chaîne, il sera analysé de manière équivalente à new URL(base).

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

Le constructeur URL est accessible en tant que propriété de l'objet global. Il peut également être importé à partir du module url intégré :

ESMCJS

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

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

Une erreur TypeError sera levée si input ou base ne sont pas des URL valides. Notez qu'un effort sera fait pour forcer les valeurs données en chaînes. Par exemple :

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

Les caractères Unicode apparaissant dans le nom d'hôte de input seront automatiquement convertis en ASCII à l'aide de l'algorithme Punycode.

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

Dans les cas où l'on ne sait pas à l'avance si input est une URL absolue et qu'une base base est fournie, il est conseillé de valider que l'origine de l'objet URL est celle attendue.

let myURL = new URL('http://Example.com/', 'https://example.org/')
// http://example.com/

myURL = new URL('https://Example.com/', 'https://example.org/')
// https://example.com/

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

myURL = new URL('http:Example.com/', 'https://example.org/')
// http://example.com/

myURL = new URL('https:Example.com/', 'https://example.org/')
// https://example.org/Example.com/

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

`url.hash`

<string>

Obtient et définit la partie fragment de l'URL.

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

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

Les caractères d'URL invalides inclus dans la valeur affectée à la propriété hash sont codés en pourcentage. Le choix des caractères à coder en pourcentage peut varier légèrement de ce que les méthodes url.parse() et url.format() produiraient.

`url.host`

<string>

Obtient et définit la partie hôte de l'URL.

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

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

Les valeurs d'hôte invalides affectées à la propriété host sont ignorées.

`url.hostname`

<string>

Obtient et définit la partie nom d'hôte de l'URL. La principale différence entre url.host et url.hostname est que url.hostname n'inclut pas le port.

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

// La définition du nom d'hôte ne modifie pas le port
myURL.hostname = 'example.com'
console.log(myURL.href)
// Affiche https://example.com:81/foo

// Utilisez myURL.host pour modifier le nom d'hôte et le port
myURL.host = 'example.org:82'
console.log(myURL.href)
// Affiche https://example.org:82/foo

Les valeurs de nom d'hôte invalides affectées à la propriété hostname sont ignorées.

`url.href`

<string>

Obtient et définit l'URL sérialisée.

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

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

L'obtention de la valeur de la propriété href équivaut à appeler url.toString().

L'affectation d'une nouvelle valeur à cette propriété équivaut à la création d'un nouvel objet URL à l'aide de new URL(value). Chacune des propriétés de l'objet URL sera modifiée.

Si la valeur affectée à la propriété href n'est pas une URL valide, une erreur TypeError sera levée.

`url.origin`

[Historique]

Version	Modifications
v15.0.0	Le schéma "gopher" n'est plus spécial et `url.origin` retourne maintenant `'null'` pour celui-ci.

<string>

Obtient la sérialisation en lecture seule de l'origine de l'URL.

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

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

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

`url.password`

<string>

Obtient et définit la partie mot de passe de l'URL.

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

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

Les caractères d'URL invalides inclus dans la valeur affectée à la propriété password sont encodés en pourcentage. La sélection des caractères à encoder en pourcentage peut varier légèrement de ce que les méthodes url.parse() et url.format() produiraient.

`url.pathname`

<string>

Obtient et définit la partie chemin de l'URL.

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

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

Les caractères d'URL invalides inclus dans la valeur affectée à la propriété pathname sont encodés en pourcentage. La sélection des caractères à encoder en pourcentage peut varier légèrement de ce que les méthodes url.parse() et url.format() produiraient.

`url.port`

[Historique]

Version	Modifications
v15.0.0	Le schéma "gopher" n'est plus spécial.

<chaîne de caractères>

Obtient et définit la partie port de l'URL.

La valeur du port peut être un nombre ou une chaîne de caractères contenant un nombre compris entre 0 et 65535 (inclus). Définir la valeur sur le port par défaut des objets URL étant donné le protocol entraînera une valeur de port devenant une chaîne vide ('').

La valeur du port peut être une chaîne vide, auquel cas le port dépend du protocole/schéma :

protocole	port
"ftp"	21
"file"
"http"	80
"https"	443
"ws"	80
"wss"	443

Lors de l'affectation d'une valeur au port, la valeur sera d'abord convertie en chaîne de caractères à l'aide de .toString().

Si cette chaîne est invalide mais qu'elle commence par un nombre, le nombre de tête est affecté à port. Si le nombre se situe en dehors de la plage indiquée ci-dessus, il est ignoré.

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

// Les ports par défaut sont automatiquement transformés en chaîne vide
// (le port par défaut du protocole HTTPS est 443)
myURL.port = '443'
console.log(myURL.port)
// Affiche la chaîne vide
console.log(myURL.href)
// Affiche https://example.org/

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

// Les chaînes de caractères de port complètement invalides sont ignorées
myURL.port = 'abcd'
console.log(myURL.port)
// Affiche 1234

// Les nombres de tête sont traités comme un numéro de port
myURL.port = '5678abcd'
console.log(myURL.port)
// Affiche 5678

// Les nombres non entiers sont tronqués
myURL.port = 1234.5678
console.log(myURL.port)
// Affiche 1234

// Les nombres hors plage qui ne sont pas représentés en notation scientifique
// seront ignorés.
myURL.port = 1e10 // 10000000000, sera vérifié selon la plage comme décrit ci-dessous
console.log(myURL.port)
// Affiche 1234

Les nombres contenant un point décimal, tels que les nombres à virgule flottante ou les nombres en notation scientifique, ne font pas exception à cette règle. Les nombres de tête jusqu'au point décimal seront définis comme le port de l'URL, à condition qu'ils soient valides :

myURL.port = 4.567e21
console.log(myURL.port)
// Affiche 4 (car c'est le nombre de tête dans la chaîne '4.567e21')

`url.protocol`

<string>

Obtient et définit la partie protocole de l'URL.

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

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

Les valeurs de protocole d'URL invalides affectées à la propriété protocol sont ignorées.

Schémas spéciaux

[Historique]

Version	Modifications
v15.0.0	Le schéma "gopher" n'est plus spécial.

La spécification WHATWG URL considère une poignée de schémas de protocoles URL comme spéciaux en termes de la façon dont ils sont analysés et sérialisés. Lorsqu'une URL est analysée en utilisant l'un de ces protocoles spéciaux, la propriété url.protocol peut être modifiée en un autre protocole spécial, mais ne peut pas être modifiée en un protocole non spécial, et vice versa.

Par exemple, passer de http à https fonctionne :

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

Cependant, passer de http à un protocole hypothétique fish ne fonctionne pas, car le nouveau protocole n'est pas spécial.

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

De même, passer d'un protocole non spécial à un protocole spécial n'est pas non plus autorisé :

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

Selon la spécification WHATWG URL, les schémas de protocoles spéciaux sont ftp, file, http, https, ws, et wss.

`url.search`

<string>

Obtient et définit la partie requête sérialisée de l'URL.

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

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

Tous les caractères d'URL invalides apparaissant dans la valeur affectée à la propriété search seront encodés en pourcentage. La sélection des caractères à encoder en pourcentage peut varier quelque peu de ce que les méthodes url.parse() et url.format() produiraient.

`url.searchParams`

<URLSearchParams>

Obtient l'objet URLSearchParams représentant les paramètres de requête de l'URL. Cette propriété est en lecture seule, mais l'objet URLSearchParams qu'elle fournit peut être utilisé pour modifier l'instance URL ; pour remplacer la totalité des paramètres de requête de l'URL, utilisez le setter url.search. Consultez la documentation URLSearchParams pour plus de détails.

Soyez prudent lorsque vous utilisez .searchParams pour modifier l'objet URL car, selon la spécification WHATWG, l'objet URLSearchParams utilise des règles différentes pour déterminer quels caractères doivent être encodés en pourcentage. Par exemple, l'objet URL n'encode pas en pourcentage le caractère tilde ASCII (~), tandis que URLSearchParams l'encode toujours :

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

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

// Modification de l'URL via searchParams...
myURL.searchParams.sort()

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

`url.username`

<string>

Obtient et définit la partie nom d'utilisateur de l'URL.

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

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

Tout caractère URL invalide apparaissant dans la valeur affectée à la propriété username sera encodé en pourcentage. La sélection des caractères à encoder en pourcentage peut varier quelque peu de ce que les méthodes url.parse() et url.format() produiraient.

`url.toString()`

Retourne : <string>

La méthode toString() sur l'objet URL retourne l'URL sérialisée. La valeur retournée est équivalente à celle de url.href et url.toJSON().

`url.toJSON()`

Ajouté dans : v7.7.0, v6.13.0

Retourne : <string>

La méthode toJSON() de l’objet URL retourne l’URL serialisée. La valeur retournée est équivalente à celle de url.href et url.toString().

Cette méthode est automatiquement appelée lorsqu’un objet URL est serialisé avec JSON.stringify().

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

`URL.createObjectURL(blob)`

Ajouté dans : v16.7.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

blob <Blob>
Retourne : <string>

Crée une chaîne d’URL 'blob:nodedata:...' qui représente l’objet <Blob> donné et qui peut être utilisée pour récupérer le Blob ultérieurement.

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

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

// plus tard...

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

Les données stockées par le <Blob> enregistré seront conservées en mémoire jusqu’à ce que URL.revokeObjectURL() soit appelé pour les supprimer.

Les objets Blob sont enregistrés dans le thread actuel. Si vous utilisez des threads de travail, les objets Blob enregistrés dans un thread de travail ne seront pas disponibles pour les autres threads de travail ou le thread principal.

`URL.revokeObjectURL(id)`

Ajouté dans : v16.7.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

id <string> Une chaîne d’URL 'blob:nodedata:... retournée par un appel précédent à URL.createObjectURL().

Supprime le <Blob> stocké identifié par l’ID donné. Toute tentative de révocation d’un ID qui n’est pas enregistré échouera silencieusement.

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

Ajouté dans : v19.9.0, v18.17.0

input <string> L'URL d'entrée absolue ou relative à analyser. Si input est relatif, alors base est requis. Si input est absolu, base est ignoré. Si input n'est pas une chaîne de caractères, il est d'abord converti en chaîne de caractères.
base <string> L'URL de base à utiliser pour la résolution si input n'est pas absolu. Si base n'est pas une chaîne de caractères, il est d'abord converti en chaîne de caractères.
Retourne : <boolean>

Vérifie si une input relative à base peut être analysée en une URL.

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

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

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

Ajouté dans : v22.1.0

input <string> L'URL d'entrée absolue ou relative à analyser. Si input est relatif, alors base est requis. Si input est absolu, base est ignoré. Si input n'est pas une chaîne de caractères, il est d'abord converti en chaîne de caractères.
base <string> L'URL de base à utiliser pour la résolution si input n'est pas absolu. Si base n'est pas une chaîne de caractères, il est d'abord converti en chaîne de caractères.
Retourne : <URL> | <null>

Analyse une chaîne de caractères en tant qu'URL. Si base est fourni, il sera utilisé comme URL de base pour la résolution des URLs input non absolues. Retourne null si input n'est pas valide.

Classe : `URLSearchParams`

[Historique]

Version	Modifications
v10.0.0	La classe est maintenant disponible sur l'objet global.
v7.5.0, v6.13.0	Ajoutée dans : v7.5.0, v6.13.0

L'API URLSearchParams fournit un accès en lecture et en écriture à la requête d'une URL. La classe URLSearchParams peut également être utilisée de manière autonome avec l'un des quatre constructeurs suivants. La classe URLSearchParams est également disponible sur l'objet global.

L'interface WHATWG URLSearchParams et le module querystring ont un objectif similaire, mais l'objectif du module querystring est plus général, car il permet la personnalisation des caractères de délimitation (& et =). D'autre part, cette API est conçue purement pour les chaînes de requête URL.

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

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

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

const newSearchParams = new URLSearchParams(myURL.searchParams)
// Ce qui précède est équivalent à
// const newSearchParams = new URLSearchParams(myURL.search);

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

// newSearchParams.toString() est appelé implicitement
myURL.search = newSearchParams
console.log(myURL.href)
// Affiche https://example.org/?a=b&a=c
newSearchParams.delete('a')
console.log(myURL.href)
// Affiche https://example.org/?a=b&a=c

`new URLSearchParams()`

Instancie un nouvel objet URLSearchParams vide.

`new URLSearchParams(string)`

string <string> Une chaîne de requête

Analyse la string comme une chaîne de requête et l'utilise pour instancier un nouvel objet URLSearchParams. Un '?' initial, s'il est présent, est ignoré.

let params

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

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

`new URLSearchParams(obj)`

Ajouté dans : v7.10.0, v6.13.0

obj <Objet> Un objet représentant une collection de paires clé-valeur

Instancie un nouvel objet URLSearchParams avec une table de hachage de requête. La clé et la valeur de chaque propriété de obj sont toujours converties en chaînes de caractères.

Contrairement au module querystring, les clés dupliquées sous forme de valeurs de tableau ne sont pas autorisées. Les tableaux sont convertis en chaînes à l'aide de array.toString(), qui joint simplement tous les éléments du tableau avec des virgules.

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

`new URLSearchParams(iterable)`

Ajouté dans : v7.10.0, v6.13.0

iterable <Itérable> Un objet itérable dont les éléments sont des paires clé-valeur

Instancie un nouvel objet URLSearchParams avec une map itérable d'une manière similaire au constructeur de Map. iterable peut être un Array ou tout objet itérable. Cela signifie que iterable peut être un autre URLSearchParams, auquel cas le constructeur créera simplement un clone du URLSearchParams fourni. Les éléments de iterable sont des paires clé-valeur et peuvent eux-mêmes être n'importe quel objet itérable.

Les clés dupliquées sont autorisées.

let params

// Utilisation d'un tableau
params = new URLSearchParams([
  ['user', 'abc'],
  ['query', 'first'],
  ['query', 'second'],
])
console.log(params.toString())
// Affiche 'user=abc&query=first&query=second'

// Utilisation d'un objet Map
const map = new Map()
map.set('user', 'abc')
map.set('query', 'xyz')
params = new URLSearchParams(map)
console.log(params.toString())
// Affiche 'user=abc&query=xyz'

// Utilisation d'une fonction génératrice
function* getQueryPairs() {
  yield ['user', 'abc']
  yield ['query', 'first']
  yield ['query', 'second']
}
params = new URLSearchParams(getQueryPairs())
console.log(params.toString())
// Affiche 'user=abc&query=first&query=second'

// Chaque paire clé-valeur doit avoir exactement deux éléments
new URLSearchParams([['user', 'abc', 'error']])
// Lance TypeError [ERR_INVALID_TUPLE]:
//        Chaque paire de requête doit être un tuple itérable [nom, valeur]

`urlSearchParams.append(name, value)`

name <string>
value <string>

Ajoute une nouvelle paire nom-valeur à la chaîne de requête.

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

[Historique]

Version	Modifications
v20.2.0, v18.18.0	Ajout de la prise en charge de l'argument `value` optionnel.

name <string>
value <string>

Si value est fourni, supprime toutes les paires nom-valeur où le nom est name et la valeur est value.

Si value n'est pas fourni, supprime toutes les paires nom-valeur dont le nom est name.

`urlSearchParams.entries()`

Retourne : <Iterator>

Retourne un itérateur ES6 pour chaque paire nom-valeur de la requête. Chaque élément de l'itérateur est un tableau JavaScript. Le premier élément du tableau est le name, le second élément du tableau est la value.

Alias pour urlSearchParams[@@iterator]().

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

[Historique]

Version	Modifications
v18.0.0	La transmission d'un rappel invalide à l'argument `fn` lève désormais l'exception `ERR_INVALID_ARG_TYPE` au lieu de `ERR_INVALID_CALLBACK`.

fn <Function> Invoquée pour chaque paire nom-valeur de la requête
thisArg <Object> À utiliser comme valeur this lorsque fn est appelée

Itère sur chaque paire nom-valeur de la requête et appelle la fonction donnée.

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

`urlSearchParams.get(name)`

name <string>
Retourne : <string> | <null> Une chaîne de caractères ou null s'il n'y a pas de paire nom-valeur avec le nom donné name.

Retourne la valeur de la première paire nom-valeur dont le nom est name. Si aucune paire ne correspond, null est retourné.

`urlSearchParams.getAll(name)`

name <string>
Retourne : <string[]>

Retourne les valeurs de toutes les paires nom-valeur dont le nom est name. Si aucune paire ne correspond, un tableau vide est retourné.

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

[Historique]

Version	Modifications
v20.2.0, v18.18.0	Ajout de la prise en charge de l'argument `value` optionnel.

name <string>
value <string>
Retourne : <boolean>

Vérifie si l'objet URLSearchParams contient des paires clé-valeur basées sur name et un argument value optionnel.

Si value est fourni, retourne true lorsqu'une paire nom-valeur avec le même name et value existe.

Si value n'est pas fourni, retourne true s'il existe au moins une paire nom-valeur dont le nom est name.

`urlSearchParams.keys()`

Retourne : <Iterator>

Retourne un Iterator ES6 sur les noms de chaque paire nom-valeur.

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

`urlSearchParams.set(name, value)`

name <string>
value <string>

Définit la valeur dans l'objet URLSearchParams associée à name sur value. Si des paires nom-valeur préexistantes ont pour nom name, définit la valeur de la première paire sur value et supprime toutes les autres. Sinon, ajoute la paire nom-valeur à la chaîne de requête.

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

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

`urlSearchParams.size`

Ajouté dans : v19.8.0, v18.16.0

Le nombre total d'entrées de paramètres.

`urlSearchParams.sort()`

Ajouté dans : v7.7.0, v6.13.0

Trie toutes les paires nom-valeur existantes sur place par leurs noms. Le tri est effectué avec un algorithme de tri stable, donc l'ordre relatif entre les paires nom-valeur ayant le même nom est préservé.

Cette méthode peut être utilisée, en particulier, pour augmenter les succès de cache.

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

`urlSearchParams.toString()`

Retourne : <string>

Retourne les paramètres de recherche sérialisés sous forme de chaîne, avec les caractères codés en pourcentage si nécessaire.

`urlSearchParams.values()`

Retourne : <Iterator>

Retourne un itérateur ES6 sur les valeurs de chaque paire nom-valeur.

`urlSearchParams[Symbol.iterator]()`

Retourne : <Iterator>

Retourne un itérateur ES6 sur chaque paire nom-valeur de la chaîne de requête. Chaque élément de l'itérateur est un tableau JavaScript. Le premier élément du tableau est le nom, le second est la valeur.

Alias de urlSearchParams.entries().

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

`url.domainToASCII(domain)`

[Historique]

Version	Modifications
v20.0.0, v18.17.0	L'exigence ICU est supprimée.
v7.4.0, v6.13.0	Ajouté dans : v7.4.0, v6.13.0

domain <string>
Retourne : <string>

Retourne la sérialisation ASCII Punycode du domain. Si domain est un domaine invalide, la chaîne vide est retournée.

Elle effectue l'opération inverse de url.domainToUnicode().

ESMCJS

import url from 'node:url'

console.log(url.domainToASCII('español.com'))
// Affiche xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'))
// Affiche xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'))
// Affiche une chaîne vide

const url = require('node:url')

console.log(url.domainToASCII('español.com'))
// Affiche xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'))
// Affiche xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'))
// Affiche une chaîne vide

`url.domainToUnicode(domain)`

[Historique]

Version	Modifications
v20.0.0, v18.17.0	L'exigence ICU est supprimée.
v7.4.0, v6.13.0	Ajouté dans : v7.4.0, v6.13.0

domain <string>
Retourne : <string>

Retourne la sérialisation Unicode du domain. Si domain est un domaine invalide, la chaîne vide est retournée.

Elle effectue l'opération inverse de url.domainToASCII().

ESMCJS

import url from 'node:url'

console.log(url.domainToUnicode('xn--espaol-zwa.com'))
// Affiche español.com
console.log(url.domainToUnicode('xn--fiq228c.com'))
// Affiche 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'))
// Affiche une chaîne vide

const url = require('node:url')

console.log(url.domainToUnicode('xn--espaol-zwa.com'))
// Affiche español.com
console.log(url.domainToUnicode('xn--fiq228c.com'))
// Affiche 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'))
// Affiche une chaîne vide

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

[Historique]

Version	Modifications
v22.1.0, v20.13.0	L'argument `options` peut désormais être utilisé pour déterminer comment analyser l'argument `path`.
v10.12.0	Ajouté dans : v10.12.0

url <URL> | <chaîne de caractères> La chaîne d'URL de fichier ou l'objet URL à convertir en chemin.
options <Objet>
- windows <booléen> | <indéfini> true si le path doit être renvoyé comme chemin de fichier Windows, false pour POSIX, et undefined pour la valeur par défaut du système. Par défaut : undefined.
Retourne : <chaîne de caractères> Le chemin de fichier Node.js spécifique à la plateforme entièrement résolu.

Cette fonction assure les décodages corrects des caractères encodés en pourcentage ainsi que la garantie d'une chaîne de chemin d'accès absolu valide et interplateforme.

ESMCJS

import { fileURLToPath } from 'node:url'

const __filename = fileURLToPath(import.meta.url)

new URL('file:///C:/path/').pathname // Incorrect : /C:/path/
fileURLToPath('file:///C:/path/') // Correct :   C:\path\ (Windows)

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

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

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

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

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

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

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

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

Ajouté dans : v7.6.0

URL <URL> Un objet URL WHATWG
options <Objet>
- auth <booléen> true si la chaîne d'URL sérialisée doit inclure le nom d'utilisateur et le mot de passe, false sinon. Défaut : true.
- fragment <booléen> true si la chaîne d'URL sérialisée doit inclure le fragment, false sinon. Défaut : true.
- search <booléen> true si la chaîne d'URL sérialisée doit inclure la requête de recherche, false sinon. Défaut : true.
- unicode <booléen> true si les caractères Unicode apparaissant dans le composant hôte de la chaîne d'URL doivent être codés directement au lieu d'être codés en Punycode. Défaut : false.
Retourne : <chaîne de caractères>

Retourne une sérialisation personnalisable d'une représentation String d'URL d'un objet URL WHATWG.

L'objet URL possède à la fois une méthode toString() et une propriété href qui retournent des sérialisations de chaîne de caractères de l'URL. Celles-ci ne sont cependant pas personnalisables. La méthode url.format(URL[, options]) permet une personnalisation de base de la sortie.

ESMCJS

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

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

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

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

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

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

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

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

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

[Historique]

Version	Modifications
v22.1.0, v20.13.0	L'argument `options` peut maintenant être utilisé pour déterminer comment renvoyer la valeur `path`.
v10.12.0	Ajouté dans : v10.12.0

path <string> Le chemin à convertir en URL de fichier.
options <Object>
- windows <boolean> | <undefined> true si le path doit être traité comme un chemin d'accès Windows, false pour posix, et undefined pour la valeur par défaut du système. Défaut : undefined.
Retourne : <URL> L'objet URL de fichier.

Cette fonction garantit que path est résolu absolument et que les caractères de contrôle d'URL sont correctement codés lors de la conversion en URL de fichier.

ESMCJS

import { pathToFileURL } from 'node:url'

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

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

const { pathToFileURL } = require('node:url')
new URL(__filename) // Incorrect : lève une exception (POSIX)
new URL(__filename) // Incorrect : C:\... (Windows)
pathToFileURL(__filename) // Correct :   file:///... (POSIX)
pathToFileURL(__filename) // Correct :   file:///C:/... (Windows)

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

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

`url.urlToHttpOptions(url)`

[Historique]

Version	Modifications
v19.9.0, v18.17.0	L'objet retourné contiendra également toutes les propriétés énumérables propres de l'argument `url`.
v15.7.0, v14.18.0	Ajouté dans : v15.7.0, v14.18.0

url <URL> L'objet URL WHATWG à convertir en objet d'options.
Retourne : <Objet> Objet d'options
- protocol <chaîne de caractères> Protocole à utiliser.
- hostname <chaîne de caractères> Nom de domaine ou adresse IP du serveur auquel envoyer la requête.
- hash <chaîne de caractères> La partie fragment de l'URL.
- search <chaîne de caractères> La partie requête sérialisée de l'URL.
- pathname <chaîne de caractères> La partie chemin de l'URL.
- path <chaîne de caractères> Chemin de la requête. Doit inclure la chaîne de requête le cas échéant. Par exemple : '/index.html?page=12'. Une exception est levée lorsque le chemin de la requête contient des caractères illégaux. Actuellement, seuls les espaces sont rejetés, mais cela pourrait changer à l'avenir.
- href <chaîne de caractères> L'URL sérialisée.
- port <nombre> Port du serveur distant.
- auth <chaîne de caractères> Authentification de base, c'est-à-dire 'user:password' pour calculer un en-tête d'autorisation.

Cette fonction utilitaire convertit un objet URL en un objet d'options ordinaire tel qu'attendu par les API http.request() et https.request().

ESMCJS

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

console.log(urlToHttpOptions(myURL))
/*
{
  protocol: 'https:',
  hostname: 'xn--g6w251d',
  hash: '#foo',
  search: '?abc',
  pathname: '/',
  path: '/?abc',
  href: 'https://a:b@xn--g6w251d/?abc#foo',
  auth: 'a:b'
}
*/

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

console.log(urlToHttpOptions(myURL))
/*
{
  protocol: 'https:',
  hostname: 'xn--g6w251d',
  hash: '#foo',
  search: '?abc',
  pathname: '/',
  path: '/?abc',
  href: 'https://a:b@xn--g6w251d/?abc#foo',
  auth: 'a:b'
}
*/

API URL héritée

[Historique]

Version	Modifications
v15.13.0, v14.17.0	Dépréciation révoquée. Statut changé en "Hérité".
v11.0.0	Cette API est dépréciée.

[Stable : 3 - Hérité]

Stable : 3 Stabilité : 3 - Hérité : Utilisez plutôt l’API URL WHATWG.

`urlObject` hérité

[Historique]

Version	Modifications
v15.13.0, v14.17.0	Dépréciation révoquée. Statut changé en "Hérité".
v11.0.0	L’API URL héritée est dépréciée. Utilisez l’API URL WHATWG.

[Stable : 3 - Hérité]

Stable : 3 Stabilité : 3 - Hérité : Utilisez plutôt l’API URL WHATWG.

L’objet urlObject hérité (require('node:url').Url ou import { Url } from 'node:url') est créé et retourné par la fonction url.parse().

`urlObject.auth`

La propriété auth est la partie nom d’utilisateur et mot de passe de l’URL, également appelée informations utilisateur. Ce sous-ensemble de chaîne suit le protocol et les doubles barres obliques (si présentes) et précède le composant host, délimité par @. La chaîne est soit le nom d’utilisateur, soit le nom d’utilisateur et le mot de passe séparés par :.

Par exemple : 'user:pass'.

`urlObject.hash`

La propriété hash est la partie identificateur de fragment de l’URL, y compris le caractère # initial.

Par exemple : '#hash'.

`urlObject.host`

La propriété host est la partie hôte complète en minuscules de l’URL, y compris le port si spécifié.

Par exemple : 'sub.example.com:8080'.

`urlObject.hostname`

La propriété hostname est la partie nom d’hôte en minuscules du composant host sans le port.

Par exemple : 'sub.example.com'.

`urlObject.href`

La propriété href est la chaîne d’URL complète qui a été analysée, avec les composants protocol et host convertis en minuscules.

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

`urlObject.path`

La propriété path est une concaténation des composants pathname et search.

Par exemple : '/p/a/t/h?query=string'.

Aucun décodage de path n'est effectué.

`urlObject.pathname`

La propriété pathname consiste en la section entière du chemin de l'URL. C'est tout ce qui suit le host (y compris le port) et précède le début des composants query ou hash, délimité par les caractères point d'interrogation ASCII (?) ou dièse (#).

Par exemple : '/p/a/t/h'.

Aucun décodage de la chaîne de chemin n'est effectué.

`urlObject.port`

La propriété port est la partie numérique du port du composant host.

Par exemple : '8080'.

`urlObject.protocol`

La propriété protocol identifie le schéma de protocole en minuscules de l'URL.

Par exemple : 'http:'.

`urlObject.query`

La propriété query est soit la chaîne de requête sans le point d'interrogation ASCII initial (?), soit un objet renvoyé par la méthode parse() du module querystring. Le fait que la propriété query soit une chaîne ou un objet est déterminé par l'argument parseQueryString passé à url.parse().

Par exemple : 'query=string' ou {'query': 'string'}.

Si renvoyée sous forme de chaîne, aucun décodage de la chaîne de requête n'est effectué. Si renvoyée sous forme d'objet, les clés et les valeurs sont décodées.

`urlObject.search`

La propriété search consiste en la partie entière de la "chaîne de requête" de l'URL, y compris le caractère point d'interrogation ASCII initial (?).

Par exemple : '?query=string'.

Aucun décodage de la chaîne de requête n'est effectué.

`urlObject.slashes`

La propriété slashes est un booléen de valeur true si deux caractères barre oblique ASCII (/) sont requis après les deux points dans le protocol.

`url.format(urlObject)`

[Historique]

Version	Modifications
v17.0.0	Lève désormais une exception `ERR_INVALID_URL` lorsque la conversion Punycode d'un nom d'hôte introduit des modifications qui pourraient entraîner une analyse différente de l'URL.
v15.13.0, v14.17.0	Retrait de la dépréciation. Statut modifié en "Hérité".
v11.0.0	L'API URL héritée est dépréciée. Utilisez l'API URL WHATWG.
v7.0.0	Les URL avec un schéma `file:` utiliseront désormais toujours le nombre correct de barres obliques, quelle que soit l'option `slashes`. Une option `slashes` fausse sans protocole est désormais également respectée en tout temps.
v0.1.25	Ajouté dans : v0.1.25

[Stable : 3 - Hérité]

Stable : 3 Stabilité : 3 - Hérité : Utilisez plutôt l'API URL WHATWG.

urlObject <Objet> | <chaîne de caractères> Un objet URL (tel que renvoyé par url.parse() ou construit autrement). Si c'est une chaîne, elle est convertie en objet en la passant à url.parse().

La méthode url.format() renvoie une chaîne d'URL formatée dérivée 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 n'est pas un objet ou une chaîne, url.format() lèvera une TypeError.

Le processus de formatage fonctionne comme suit :

Une nouvelle chaîne vide result est créée.
Si urlObject.protocol est une chaîne, elle est ajoutée telle quelle à result.
Sinon, si urlObject.protocol n'est pas undefined et n'est pas une chaîne, une Error est levée.
Pour toutes les valeurs de chaîne de urlObject.protocol qui ne se terminent pas par un caractère deux-points ASCII (:), la chaîne littérale : sera ajoutée à result.
Si l'une des conditions suivantes est vraie, la chaîne littérale // sera ajoutée à result :
- la propriété urlObject.slashes est vraie ;
- urlObject.protocol commence par http, https, ftp, gopher ou file ;
Si la valeur de la propriété urlObject.auth est vraie, et que urlObject.host ou urlObject.hostname ne sont pas undefined, la valeur de urlObject.auth sera convertie en chaîne et ajoutée à result suivie de la chaîne littérale @.
Si la propriété urlObject.host est undefined alors :
- Si urlObject.hostname est une chaîne, elle est ajoutée à result.
- Sinon, si urlObject.hostname n'est pas undefined et n'est pas une chaîne, une Error est levée.
- Si la valeur de la propriété urlObject.port est vraie, et que urlObject.hostname n'est pas undefined :
- La chaîne littérale : est ajoutée à result, et
- La valeur de urlObject.port est convertie en chaîne et ajoutée à result.
Sinon, si la valeur de la propriété urlObject.host est vraie, la valeur de urlObject.host est convertie en chaîne et ajoutée à result.
Si la propriété urlObject.pathname est une chaîne qui n'est pas une chaîne vide :
- Si urlObject.pathname ne commence pas par une barre oblique ASCII (/), la chaîne littérale '/' est ajoutée à result.
- La valeur de urlObject.pathname est ajoutée à result.
Sinon, si urlObject.pathname n'est pas undefined et n'est pas une chaîne, une Error est levée.
Si la propriété urlObject.search est undefined et si la propriété urlObject.query est un Objet, la chaîne littérale ? est ajoutée à result suivie de la sortie de l'appel de la méthode stringify() du module querystring en lui passant la valeur de urlObject.query.
Sinon, si urlObject.search est une chaîne :
- Si la valeur de urlObject.search ne commence pas par le caractère point d'interrogation ASCII (?), la chaîne littérale ? est ajoutée à result.
- La valeur de urlObject.search est ajoutée à result.
Sinon, si urlObject.search n'est pas undefined et n'est pas une chaîne, une Error est levée.
Si la propriété urlObject.hash est une chaîne :
- Si la valeur de urlObject.hash ne commence pas par le caractère dièse ASCII (#), la chaîne littérale # est ajoutée à result.
- La valeur de urlObject.hash est ajoutée à result.
Sinon, si la propriété urlObject.hash n'est pas undefined et n'est pas une chaîne, une Error est levée.
result est renvoyé.

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

[Historique]

Version	Modifications
v19.0.0, v18.13.0	Dépréciation uniquement pour la documentation.
v15.13.0, v14.17.0	Dépréciation révoquée. Statut changé en "Hérité".
v11.14.0	La propriété `pathname` de l'objet URL retourné est maintenant `/` lorsqu'il n'y a pas de chemin et que le schéma de protocole est `ws:` ou `wss:`.
v11.0.0	L'API URL héritée est dépréciée. Utilisez l'API URL WHATWG.
v9.0.0	La propriété `search` de l'objet URL retourné est maintenant `null` lorsqu'aucune chaîne de requête n'est présente.
v0.1.25	Ajouté dans : v0.1.25

[Stable : 0 - Déprécié]

Stable : 0 Stabilité : 0 - Déprécié : Utilisez plutôt l'API URL WHATWG.

urlString <string> La chaîne d'URL à analyser.
parseQueryString <boolean> Si true, la propriété query sera toujours définie sur un objet retourné par la méthode parse() du module querystring. Si false, la propriété query de l'objet URL retourné sera une chaîne non analysée et non décodée. Défaut : false.
slashesDenoteHost <boolean> Si true, le premier jeton après la chaîne littérale // et précédant le / suivant sera interprété comme l'host. Par exemple, étant donné //foo/bar, le résultat serait {host: 'foo', pathname: '/bar'} plutôt que {pathname: '//foo/bar'}. Défaut : false.

La méthode url.parse() prend une chaîne d'URL, l'analyse et retourne un objet URL.

Une erreur TypeError est levée si urlString n'est pas une chaîne.

Une erreur URIError est levée si la propriété auth est présente mais ne peut pas être décodée.

url.parse() utilise un algorithme indulgent et non standard pour analyser les chaînes d'URL. Il est sujet à des problèmes de sécurité tels que l'usurpation de nom d'hôte et une gestion incorrecte des noms d'utilisateur et des mots de passe. Ne pas utiliser avec des entrées non fiables. Aucune CVE n'est émise pour les vulnérabilités de url.parse(). Utilisez plutôt l'API WHATWG URL.

`url.resolve(from, to)`

[Historique]

Version	Modifications
v15.13.0, v14.17.0	Retrait de l'obsolescence. Statut changé en "Hérité".
v11.0.0	L'API URL héritée est obsolète. Utilisez l'API URL WHATWG.
v6.6.0	Les champs `auth` sont maintenant conservés intacts lorsque `from` et `to` font référence au même hôte.
v6.0.0	Le champ `auth` est maintenant effacé si le paramètre `to` contient un nom d'hôte.
v6.5.0, v4.6.2	Le champ `port` est maintenant correctement copié.
v0.1.25	Ajouté dans : v0.1.25

[Stable : 3 - Hérité]

Stable : 3 Stabilité : 3 - Hérité : Utilisez plutôt l'API URL WHATWG.

from <string> L'URL de base à utiliser si to est une URL relative.
to <string> L'URL cible à résoudre.

La méthode url.resolve() résout une URL cible par rapport à une URL de base, de manière similaire à celle d'un navigateur web résolvant une balise d'ancrage.

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'

Pour obtenir le même résultat en utilisant l'API URL WHATWG :

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

Encodage en pourcentage dans les URL

Les URL ne sont autorisées à contenir qu'une certaine plage de caractères. Tout caractère en dehors de cette plage doit être encodé. La manière dont ces caractères sont encodés et les caractères à encoder dépendent entièrement de l'emplacement du caractère dans la structure de l'URL.

API héritée

Dans l'API héritée, les espaces (' ') et les caractères suivants seront automatiquement échappés dans les propriétés des objets URL :

text

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

Par exemple, le caractère espace ASCII (' ') est encodé en %20. Le caractère barre oblique ASCII (/) est encodé en %3C.

API WHATWG

La norme WHATWG URL utilise une approche plus sélective et granulaire pour sélectionner les caractères encodés que celle utilisée par l'API héritée.

L'algorithme WHATWG définit quatre « ensembles de codage en pourcentage » qui décrivent des plages de caractères qui doivent être codés en pourcentage :

L'ensemble de codage en pourcentage de contrôle C0 inclut les points de code dans la plage U+0000 à U+001F (inclus) et tous les points de code supérieurs à U+007E (~).
L'ensemble de codage en pourcentage de fragment inclut l'ensemble de codage en pourcentage de contrôle C0 et les points de code U+0020 ESPACE, U+0022 ("), U+003C (<), U+003E (>), et U+0060 (`).
L'ensemble de codage en pourcentage de chemin inclut l'ensemble de codage en pourcentage de contrôle C0 et les points de code U+0020 ESPACE, U+0022 ("), U+0023 (#), U+003C (<), U+003E (>), U+003F (?), U+0060 (`), U+007B ({), et U+007D (}).
L'ensemble de codage d'informations utilisateur inclut l'ensemble de codage en pourcentage de chemin et les points de code U+002F (/), U+003A (😃, U+003B (😉, U+003D (=), U+0040 (@), U+005B ([) à U+005E(^), et U+007C (|).

L'ensemble de codage en pourcentage d'informations utilisateur est utilisé exclusivement pour les noms d'utilisateur et les mots de passe encodés dans l'URL. L'ensemble de codage en pourcentage de chemin est utilisé pour le chemin de la plupart des URL. L'ensemble de codage en pourcentage de fragment est utilisé pour les fragments d'URL. L'ensemble de codage en pourcentage de contrôle C0 est utilisé pour l'hôte et le chemin dans certaines conditions spécifiques, en plus de tous les autres cas.

Lorsque des caractères non ASCII apparaissent dans un nom d'hôte, le nom d'hôte est encodé à l'aide de l'algorithme Punycode. Notez cependant qu'un nom d'hôte peut contenir à la fois des caractères encodés Punycode et des caractères encodés en pourcentage :

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

URL ​

Chaînes URL et objets URL ​

Construction d'une URL à partir de composants et récupération de la chaîne construite ​

L'API WHATWG URL ​

Classe : URL ​

new URL(input[, base]) ​

url.hash ​

url.host ​

url.hostname ​

url.href ​

url.origin ​

url.password ​

url.pathname ​

url.port ​

url.protocol ​

Schémas spéciaux ​

url.search ​

url.searchParams ​

url.username ​

url.toString() ​

url.toJSON() ​

URL.createObjectURL(blob) ​

URL.revokeObjectURL(id) ​

URL.canParse(input[, base]) ​

URL.parse(input[, base]) ​

Classe : URLSearchParams ​

new URLSearchParams() ​

new URLSearchParams(string) ​

new URLSearchParams(obj) ​

new URLSearchParams(iterable) ​

urlSearchParams.append(name, value) ​

urlSearchParams.delete(name[, value]) ​

urlSearchParams.entries() ​

urlSearchParams.forEach(fn[, thisArg]) ​

urlSearchParams.get(name) ​

urlSearchParams.getAll(name) ​

urlSearchParams.has(name[, value]) ​

urlSearchParams.keys() ​

urlSearchParams.set(name, value) ​

urlSearchParams.size ​

urlSearchParams.sort() ​

urlSearchParams.toString() ​

urlSearchParams.values() ​

urlSearchParams[Symbol.iterator]() ​

url.domainToASCII(domain) ​

url.domainToUnicode(domain) ​

url.fileURLToPath(url[, options]) ​

url.format(URL[, options]) ​

url.pathToFileURL(path[, options]) ​

url.urlToHttpOptions(url) ​

API URL héritée ​

urlObject hérité ​

urlObject.auth ​

urlObject.hash ​

urlObject.host ​

urlObject.hostname ​

urlObject.href ​

urlObject.path ​

urlObject.pathname ​

urlObject.port ​

urlObject.protocol ​

urlObject.query ​

urlObject.search ​

urlObject.slashes ​

url.format(urlObject) ​

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

url.resolve(from, to) ​

Encodage en pourcentage dans les URL ​

API héritée ​

API WHATWG ​

URL

Chaînes URL et objets URL

Construction d'une URL à partir de composants et récupération de la chaîne construite

L'API WHATWG URL

Classe : `URL`

`new URL(input[, base])`

`url.hash`

`url.host`

`url.hostname`

`url.href`

`url.origin`

`url.password`

`url.pathname`

`url.port`

`url.protocol`

Schémas spéciaux

`url.search`

`url.searchParams`

`url.username`

`url.toString()`

`url.toJSON()`

`URL.createObjectURL(blob)`

`URL.revokeObjectURL(id)`

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

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

Classe : `URLSearchParams`

`new URLSearchParams()`

`new URLSearchParams(string)`

`new URLSearchParams(obj)`

`new URLSearchParams(iterable)`

`urlSearchParams.append(name, value)`

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

`urlSearchParams.entries()`

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

`urlSearchParams.get(name)`

`urlSearchParams.getAll(name)`

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

`urlSearchParams.keys()`

`urlSearchParams.set(name, value)`

`urlSearchParams.size`

`urlSearchParams.sort()`

`urlSearchParams.toString()`

`urlSearchParams.values()`

`urlSearchParams[Symbol.iterator]()`

`url.domainToASCII(domain)`

`url.domainToUnicode(domain)`

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

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

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

`url.urlToHttpOptions(url)`

API URL héritée

`urlObject` hérité

`urlObject.auth`

`urlObject.hash`

`urlObject.host`

`urlObject.hostname`

`urlObject.href`

`urlObject.path`

`urlObject.pathname`

`urlObject.port`

`urlObject.protocol`

`urlObject.query`

`urlObject.search`

`urlObject.slashes`

`url.format(urlObject)`

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

`url.resolve(from, to)`

Encodage en pourcentage dans les URL

API héritée

API WHATWG