URL

[Stable: 2 - Stable]

Quellcode: lib/url.js

Das node:url-Modul stellt Hilfsfunktionen zur URL-Auflösung und -Analyse bereit. Es kann über Folgendes aufgerufen werden:

ESMCJS

import url from 'node:url'

const url = require('node:url')

URL-Strings und URL-Objekte

Ein URL-String ist ein strukturierter String, der mehrere aussagekräftige Komponenten enthält. Beim Parsen wird ein URL-Objekt zurückgegeben, das Eigenschaften für jede dieser Komponenten enthält.

Das node:url-Modul bietet zwei APIs für die Arbeit mit URLs: eine Legacy-API, die spezifisch für Node.js ist, und eine neuere API, die denselben WHATWG URL-Standard implementiert, der von Webbrowsern verwendet wird.

Ein Vergleich zwischen der WHATWG- und der Legacy-API wird unten bereitgestellt. Oberhalb der URL 'https://user:[email protected]:8080/p/a/t/h?query=string#hash' werden Eigenschaften eines Objekts angezeigt, das von der Legacy-Funktion url.parse() zurückgegeben wird. Darunter befinden sich Eigenschaften eines WHATWG URL-Objekts.

Die origin-Eigenschaft der WHATWG-URL enthält protocol und host, aber nicht username oder 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                                              │
└────────────────────────────────────────────────────────────────────────────────────────────────┘
(Alle Leerzeichen in der ""-Zeile sollten ignoriert werden. Sie dienen lediglich der Formatierung.)

Parsen des URL-Strings mit der WHATWG-API:

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

Parsen des URL-Strings mit der Legacy-API:

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

Konstruieren einer URL aus Komponenten und Abrufen der erstellten Zeichenkette

Es ist möglich, eine WHATWG-URL aus Komponenten entweder mithilfe der Eigenschafts-Setter oder einer Template-Literal-Zeichenkette zu konstruieren:

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

Um die erstellte URL-Zeichenkette zu erhalten, verwenden Sie den href-Eigenschafts-Accessor:

console.log(myURL.href)

Die WHATWG URL API

Klasse: `URL`

[Verlauf]

Version	Änderungen
v10.0.0	Die Klasse ist nun auf dem globalen Objekt verfügbar.
v7.0.0, v6.13.0	Hinzugefügt in: v7.0.0, v6.13.0

Browserkompatible URL-Klasse, implementiert gemäß dem WHATWG URL Standard. Beispiele für geparste URLs finden Sie im Standard selbst. Die URL-Klasse ist auch auf dem globalen Objekt verfügbar.

In Übereinstimmung mit den Browserkonventionen werden alle Eigenschaften von URL-Objekten als Getter und Setter auf dem Klassenprototyp implementiert, anstatt als Dateneigenschaften auf dem Objekt selbst. Im Gegensatz zu legacy urlObjects hat die Verwendung des delete-Schlüsselwortes für jegliche Eigenschaften von URL-Objekten (z.B. delete myURL.protocol, delete myURL.pathname, usw.) keinen Effekt, gibt aber dennoch true zurück.

`new URL(input[, base])`

[Verlauf]

Version	Änderungen
v20.0.0, v18.17.0	Die ICU-Anforderung wurde entfernt.

input <string> Die absolute oder relative Eingabe-URL, die geparst werden soll. Wenn input relativ ist, ist base erforderlich. Wenn input absolut ist, wird base ignoriert. Wenn input keine Zeichenkette ist, wird sie zuerst in eine Zeichenkette umgewandelt.
base <string> Die Basis-URL, gegen die aufgelöst werden soll, wenn die input nicht absolut ist. Wenn base keine Zeichenkette ist, wird sie zuerst in eine Zeichenkette umgewandelt.

Erstellt ein neues URL-Objekt, indem die input relativ zur base geparst wird. Wenn base als Zeichenkette übergeben wird, wird sie äquivalent zu new URL(base) geparst.

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

Der URL-Konstruktor ist als Eigenschaft des globalen Objekts zugänglich. Er kann auch aus dem eingebauten URL-Modul importiert werden:

ESMCJS

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

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

Ein TypeError wird ausgelöst, wenn die input oder base keine gültigen URLs sind. Beachten Sie, dass versucht wird, die angegebenen Werte in Zeichenketten zu konvertieren. Zum Beispiel:

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

Unicode-Zeichen, die im Hostnamen der input vorkommen, werden automatisch mit dem Punycode Algorithmus in ASCII umgewandelt.

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

In Fällen, in denen im Voraus nicht bekannt ist, ob input eine absolute URL ist und eine base angegeben wird, wird empfohlen, zu validieren, ob der origin des URL-Objekts das erwartete ist.

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>

Ruft den Fragmentteil der URL ab und legt ihn fest.

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

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

Ungültige URL-Zeichen, die im Wert enthalten sind, der der Eigenschaft hash zugewiesen wird, werden prozentcodiert. Die Auswahl, welche Zeichen prozentcodiert werden sollen, kann etwas von dem abweichen, was die Methoden url.parse() und url.format() erzeugen würden.

`url.host`

<string>

Ruft den Hostteil der URL ab und legt ihn fest.

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

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

Ungültige Hostwerte, die der Eigenschaft host zugewiesen werden, werden ignoriert.

`url.hostname`

<string>

Ruft den Hostnamen-Teil der URL ab und legt ihn fest. Der Hauptunterschied zwischen url.host und url.hostname besteht darin, dass url.hostname den Port nicht enthält.

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

// Das Festlegen des Hostnamens ändert den Port nicht
myURL.hostname = 'example.com'
console.log(myURL.href)
// Gibt https://example.com:81/foo aus

// Verwenden Sie myURL.host, um den Hostnamen und den Port zu ändern
myURL.host = 'example.org:82'
console.log(myURL.href)
// Gibt https://example.org:82/foo aus

Ungültige Hostnamenwerte, die der Eigenschaft hostname zugewiesen werden, werden ignoriert.

`url.href`

<string>

Ruft die serialisierte URL ab und legt sie fest.

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

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

Das Abrufen des Werts der Eigenschaft href ist gleichbedeutend mit dem Aufruf von url.toString().

Das Festlegen des Werts dieser Eigenschaft auf einen neuen Wert ist gleichbedeutend mit dem Erstellen eines neuen URL-Objekts mithilfe von new URL(value). Jede der Eigenschaften des URL-Objekts wird geändert.

Wenn der Wert, der der Eigenschaft href zugewiesen wird, keine gültige URL ist, wird ein TypeError ausgelöst.

`url.origin`

[Verlauf]

Version	Änderungen
v15.0.0	Das Schema „gopher“ ist nicht mehr speziell und `url.origin` gibt jetzt `'null'` dafür zurück.

<string>

Ruft die schreibgeschützte Serialisierung des Ursprungs der URL ab.

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

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

console.log(idnURL.hostname)
// Gibt xn--g6w251d aus

`url.password`

<string>

Ruft den Passwortteil der URL ab und legt ihn fest.

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

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

Ungültige URL-Zeichen, die im Wert enthalten sind, der der password-Eigenschaft zugewiesen wird, werden prozentual codiert. Die Auswahl, welche Zeichen prozentual codiert werden sollen, kann etwas von dem abweichen, was die Methoden url.parse() und url.format() erzeugen würden.

`url.pathname`

<string>

Ruft den Pfadteil der URL ab und legt ihn fest.

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

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

Ungültige URL-Zeichen, die im Wert enthalten sind, der der pathname-Eigenschaft zugewiesen wird, werden prozentual codiert. Die Auswahl, welche Zeichen prozentual codiert werden sollen, kann etwas von dem abweichen, was die Methoden url.parse() und url.format() erzeugen würden.

`url.port`

[Geschichte]

Version	Änderungen
v15.0.0	Das Schema "gopher" ist nicht mehr speziell.

<string>

Ruft den Portteil der URL ab und legt ihn fest.

Der Portwert kann eine Zahl oder eine Zeichenkette sein, die eine Zahl im Bereich von 0 bis 65535 (einschließlich) enthält. Wenn der Wert auf den Standardport der URL-Objekte des angegebenen Protokolls gesetzt wird, wird der port-Wert zur leeren Zeichenkette ('').

Der Portwert kann eine leere Zeichenkette sein, in diesem Fall hängt der Port vom Protokoll/Schema ab:

Protokoll	Port
"ftp"	21
"file"
"http"	80
"https"	443
"ws"	80
"wss"	443

Beim Zuweisen eines Wertes zum Port wird der Wert zunächst mit .toString() in eine Zeichenkette umgewandelt.

Wenn diese Zeichenkette ungültig ist, aber mit einer Zahl beginnt, wird die führende Zahl port zugewiesen. Wenn die Zahl außerhalb des oben genannten Bereichs liegt, wird sie ignoriert.

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

// Standardports werden automatisch in die leere Zeichenkette umgewandelt
// (Der Standardport des HTTPS-Protokolls ist 443)
myURL.port = '443'
console.log(myURL.port)
// Gibt die leere Zeichenkette aus
console.log(myURL.href)
// Gibt https://example.org/ aus

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

// Vollständig ungültige Portzeichenketten werden ignoriert
myURL.port = 'abcd'
console.log(myURL.port)
// Gibt 1234 aus

// Führende Zahlen werden als Portnummer behandelt
myURL.port = '5678abcd'
console.log(myURL.port)
// Gibt 5678 aus

// Nicht-Ganzzahlen werden abgeschnitten
myURL.port = 1234.5678
console.log(myURL.port)
// Gibt 1234 aus

// Zahlen außerhalb des Bereichs, die nicht in wissenschaftlicher Notation dargestellt werden
// werden ignoriert.
myURL.port = 1e10 // 10000000000, wird wie unten beschrieben auf den Bereich geprüft
console.log(myURL.port)
// Gibt 1234 aus

Zahlen, die einen Dezimalpunkt enthalten, wie z. B. Gleitkommazahlen oder Zahlen in wissenschaftlicher Notation, sind keine Ausnahme von dieser Regel. Führende Zahlen bis zum Dezimalpunkt werden als Port der URL festgelegt, sofern sie gültig sind:

myURL.port = 4.567e21
console.log(myURL.port)
// Gibt 4 aus (weil es die führende Zahl in der Zeichenkette '4.567e21' ist)

`url.protocol`

<string>

Ruft den Protokollteil der URL ab und legt ihn fest.

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

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

Ungültige URL-Protokollwerte, die der Eigenschaft protocol zugewiesen werden, werden ignoriert.

Spezielle Schemata

[Geschichte]

Version	Änderungen
v15.0.0	Das Schema "gopher" ist nicht mehr speziell.

Der WHATWG-URL-Standard betrachtet eine Handvoll URL-Protokollschemata als speziell in Bezug darauf, wie sie analysiert und serialisiert werden. Wenn eine URL mit einem dieser speziellen Protokolle analysiert wird, kann die Eigenschaft url.protocol in ein anderes spezielles Protokoll geändert werden, aber nicht in ein nicht-spezielles Protokoll und umgekehrt.

Zum Beispiel funktioniert die Änderung von http zu https:

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

Die Änderung von http zu einem hypothetischen fish-Protokoll funktioniert jedoch nicht, da das neue Protokoll nicht speziell ist.

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

Ebenso ist die Änderung von einem nicht-speziellen Protokoll zu einem speziellen Protokoll ebenfalls nicht zulässig:

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

Laut dem WHATWG-URL-Standard sind spezielle Protokollschemata ftp, file, http, https, ws und wss.

`url.search`

<string>

Ruft den serialisierten Abfrageteil der URL ab und legt ihn fest.

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

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

Alle ungültigen URL-Zeichen, die in dem der search-Eigenschaft zugewiesenen Wert erscheinen, werden prozentual codiert. Die Auswahl, welche Zeichen prozentual codiert werden sollen, kann etwas von dem abweichen, was die Methoden url.parse() und url.format() erzeugen würden.

`url.searchParams`

<URLSearchParams>

Ruft das URLSearchParams-Objekt ab, das die Abfrageparameter der URL repräsentiert. Diese Eigenschaft ist schreibgeschützt, aber das von ihr bereitgestellte URLSearchParams-Objekt kann verwendet werden, um die URL-Instanz zu verändern; um die Gesamtheit der Abfrageparameter der URL zu ersetzen, verwenden Sie den Setter url.search. Siehe die URLSearchParams-Dokumentation für Details.

Seien Sie vorsichtig bei der Verwendung von .searchParams zum Ändern der URL, da das URLSearchParams-Objekt gemäß der WHATWG-Spezifikation unterschiedliche Regeln verwendet, um zu bestimmen, welche Zeichen prozentcodiert werden sollen. Zum Beispiel wird das URL-Objekt das ASCII-Tilde-Zeichen (~) nicht prozentcodieren, während URLSearchParams es immer codieren wird:

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

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

// Ändern der URL über searchParams...
myURL.searchParams.sort()

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

`url.username`

<string>

Ruft den Benutzernamen-Teil der URL ab und setzt ihn.

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

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

Alle ungültigen URL-Zeichen, die im Wert der Eigenschaft username erscheinen, werden prozentcodiert. Die Auswahl der zu prozentcodierenden Zeichen kann etwas von dem abweichen, was die Methoden url.parse() und url.format() erzeugen würden.

`url.toString()`

Gibt zurück: <string>

Die toString()-Methode des URL-Objekts gibt die serialisierte URL zurück. Der zurückgegebene Wert entspricht dem von url.href und url.toJSON().

`url.toJSON()`

Hinzugefügt in: v7.7.0, v6.13.0

Gibt zurück: <string>

Die toJSON()-Methode des URL-Objekts gibt die serialisierte URL zurück. Der zurückgegebene Wert entspricht dem von url.href und url.toString().

Diese Methode wird automatisch aufgerufen, wenn ein URL-Objekt mit JSON.stringify() serialisiert wird.

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

`URL.createObjectURL(blob)`

Hinzugefügt in: v16.7.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

blob <Blob>
Gibt zurück: <string>

Erstellt einen 'blob:nodedata:...'-URL-String, der das angegebene <Blob>-Objekt darstellt und verwendet werden kann, um das Blob später abzurufen.

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

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

// später...

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

Die Daten, die von dem registrierten <Blob> gespeichert werden, bleiben im Speicher erhalten, bis URL.revokeObjectURL() aufgerufen wird, um sie zu entfernen.

Blob-Objekte werden innerhalb des aktuellen Threads registriert. Bei Verwendung von Worker-Threads sind Blob-Objekte, die in einem Worker registriert sind, nicht für andere Worker oder den Haupt-Thread verfügbar.

`URL.revokeObjectURL(id)`

Hinzugefügt in: v16.7.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

id <string> Ein 'blob:nodedata:... URL-String, der von einem vorherigen Aufruf von URL.createObjectURL() zurückgegeben wurde.

Entfernt das gespeicherte <Blob>, das durch die angegebene ID identifiziert wird. Der Versuch, eine ID zu widerrufen, die nicht registriert ist, schlägt stillschweigend fehl.

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

Hinzugefügt in: v19.9.0, v18.17.0

input <string> Die absolute oder relative Eingabe-URL, die geparst werden soll. Wenn input relativ ist, ist base erforderlich. Wenn input absolut ist, wird base ignoriert. Wenn input keine Zeichenkette ist, wird sie zuerst in eine Zeichenkette konvertiert.
base <string> Die Basis-URL, gegen die aufgelöst werden soll, wenn input nicht absolut ist. Wenn base keine Zeichenkette ist, wird sie zuerst in eine Zeichenkette konvertiert.
Gibt zurück: <boolean>

Prüft, ob eine input relativ zu base in eine URL geparst werden kann.

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

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

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

Hinzugefügt in: v22.1.0

input <string> Die absolute oder relative Eingabe-URL, die geparst werden soll. Wenn input relativ ist, ist base erforderlich. Wenn input absolut ist, wird base ignoriert. Wenn input keine Zeichenkette ist, wird sie zuerst in eine Zeichenkette konvertiert.
base <string> Die Basis-URL, gegen die aufgelöst werden soll, wenn input nicht absolut ist. Wenn base keine Zeichenkette ist, wird sie zuerst in eine Zeichenkette konvertiert.
Gibt zurück: <URL> | <null>

Parst eine Zeichenkette als URL. Wenn base angegeben wird, wird sie als Basis-URL für die Auflösung nicht-absoluter input-URLs verwendet. Gibt null zurück, wenn input nicht gültig ist.

Klasse: `URLSearchParams`

[Verlauf]

Version	Änderungen
v10.0.0	Die Klasse ist jetzt im globalen Objekt verfügbar.
v7.5.0, v6.13.0	Hinzugefügt in: v7.5.0, v6.13.0

Die URLSearchParams-API bietet Lese- und Schreibzugriff auf die Abfrage einer URL. Die URLSearchParams-Klasse kann auch eigenständig mit einem der vier folgenden Konstruktoren verwendet werden. Die URLSearchParams-Klasse ist auch im globalen Objekt verfügbar.

Die WHATWG URLSearchParams-Schnittstelle und das querystring-Modul haben einen ähnlichen Zweck, aber der Zweck des querystring-Moduls ist allgemeiner, da es die Anpassung von Trennzeichen (& und =) ermöglicht. Andererseits ist diese API rein für URL-Abfragestrings konzipiert.

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

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

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

const newSearchParams = new URLSearchParams(myURL.searchParams)
// Das Obige ist äquivalent zu
// const newSearchParams = new URLSearchParams(myURL.search);

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

// newSearchParams.toString() wird implizit aufgerufen
myURL.search = newSearchParams
console.log(myURL.href)
// Gibt https://example.org/?a=b&a=c aus
newSearchParams.delete('a')
console.log(myURL.href)
// Gibt https://example.org/?a=b&a=c aus

`new URLSearchParams()`

Erstellt ein neues leeres URLSearchParams-Objekt.

`new URLSearchParams(string)`

string <string> Eine Abfragezeichenfolge

Analysiert die string als Abfragezeichenfolge und verwendet sie, um ein neues URLSearchParams-Objekt zu instanziieren. Ein führendes '?', falls vorhanden, wird ignoriert.

let params

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

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

`new URLSearchParams(obj)`

Hinzugefügt in: v7.10.0, v6.13.0

obj <Object> Ein Objekt, das eine Sammlung von Schlüssel-Wert-Paaren darstellt

Instanziieren Sie ein neues URLSearchParams-Objekt mit einer Abfrage-Hash-Map. Der Schlüssel und der Wert jeder Eigenschaft von obj werden immer in Strings umgewandelt.

Im Gegensatz zum Modul querystring sind doppelte Schlüssel in Form von Array-Werten nicht zulässig. Arrays werden mit array.toString() in Strings umgewandelt, wodurch einfach alle Array-Elemente mit Kommas verbunden werden.

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

`new URLSearchParams(iterable)`

Hinzugefügt in: v7.10.0, v6.13.0

iterable <Iterable> Ein iterierbares Objekt, dessen Elemente Schlüssel-Wert-Paare sind

Instanziieren Sie ein neues URLSearchParams-Objekt mit einer iterierbaren Map auf eine Weise, die dem Konstruktor von Map ähnelt. iterable kann ein Array oder ein beliebiges iterierbares Objekt sein. Das bedeutet, dass iterable ein anderes URLSearchParams sein kann, in diesem Fall erstellt der Konstruktor einfach einen Klon des bereitgestellten URLSearchParams. Elemente von iterable sind Schlüssel-Wert-Paare und können selbst beliebige iterierbare Objekte sein.

Doppelte Schlüssel sind zulässig.

let params

// Verwendung eines Arrays
params = new URLSearchParams([
  ['user', 'abc'],
  ['query', 'first'],
  ['query', 'second'],
])
console.log(params.toString())
// Gibt 'user=abc&query=first&query=second' aus

// Verwendung eines Map-Objekts
const map = new Map()
map.set('user', 'abc')
map.set('query', 'xyz')
params = new URLSearchParams(map)
console.log(params.toString())
// Gibt 'user=abc&query=xyz' aus

// Verwendung einer Generatorfunktion
function* getQueryPairs() {
  yield ['user', 'abc']
  yield ['query', 'first']
  yield ['query', 'second']
}
params = new URLSearchParams(getQueryPairs())
console.log(params.toString())
// Gibt 'user=abc&query=first&query=second' aus

// Jedes Schlüssel-Wert-Paar muss genau zwei Elemente haben
new URLSearchParams([['user', 'abc', 'error']])
// Löst TypeError [ERR_INVALID_TUPLE] aus:
//        Jedes Abfragepaar muss ein iterierbares [Name, Wert]-Tupel sein

`urlSearchParams.append(name, value)`

name <string>
value <string>

Fügt der Query-String ein neues Name-Wert-Paar hinzu.

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

[Verlauf]

Version	Änderungen
v20.2.0, v18.18.0	Unterstützung für optionales `value`-Argument hinzugefügt.

name <string>
value <string>

Wenn value angegeben wird, entfernt alle Name-Wert-Paare, bei denen der Name name und der Wert value ist.

Wenn value nicht angegeben wird, entfernt alle Name-Wert-Paare, deren Name name ist.

`urlSearchParams.entries()`

Gibt zurück: <Iterator>

Gibt einen ES6 Iterator über jedes der Name-Wert-Paare in der Abfrage zurück. Jedes Element des Iterators ist ein JavaScript Array. Das erste Element des Array ist der Name, das zweite Element des Array ist der Wert.

Alias für urlSearchParams[@@iterator]().

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

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das Argument `fn` wirft nun `ERR_INVALID_ARG_TYPE` anstelle von `ERR_INVALID_CALLBACK`.

fn <Funktion> Wird für jedes Name-Wert-Paar in der Abfrage aufgerufen.
thisArg <Objekt> Soll als this-Wert verwendet werden, wenn fn aufgerufen wird

Iteriert über jedes Name-Wert-Paar in der Abfrage und ruft die angegebene Funktion auf.

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

`urlSearchParams.get(name)`

name <string>
Gibt zurück: <string> | <null> Ein String oder null, wenn kein Name-Wert-Paar mit dem angegebenen name existiert.

Gibt den Wert des ersten Name-Wert-Paares zurück, dessen Name name ist. Wenn keine solchen Paare existieren, wird null zurückgegeben.

`urlSearchParams.getAll(name)`

name <string>
Gibt zurück: <string[]>

Gibt die Werte aller Name-Wert-Paare zurück, deren Name name ist. Wenn keine solchen Paare existieren, wird ein leeres Array zurückgegeben.

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

[Verlauf]

Version	Änderungen
v20.2.0, v18.18.0	Unterstützung für optionales `value`-Argument hinzugefügt.

name <string>
value <string>
Gibt zurück: <boolean>

Prüft, ob das URLSearchParams-Objekt Schlüssel-Wert-Paare basierend auf name und einem optionalen value-Argument enthält.

Wenn value angegeben wird, wird true zurückgegeben, wenn ein Name-Wert-Paar mit demselben name und value existiert.

Wenn value nicht angegeben wird, wird true zurückgegeben, wenn mindestens ein Name-Wert-Paar vorhanden ist, dessen Name name ist.

`urlSearchParams.keys()`

Gibt zurück: <Iterator>

Gibt einen ES6 Iterator über die Namen jedes Name-Wert-Paares zurück.

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

`urlSearchParams.set(name, value)`

name <string>
value <string>

Setzt den Wert im URLSearchParams-Objekt, der mit name verbunden ist, auf value. Wenn es bereits Name-Wert-Paare gibt, deren Namen name sind, setze den Wert des ersten solchen Paares auf value und entferne alle anderen. Wenn nicht, hänge das Name-Wert-Paar an die Abfragezeichenfolge an.

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

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

`urlSearchParams.size`

Hinzugefügt in: v19.8.0, v18.16.0

Die Gesamtzahl der Parametereinträge.

`urlSearchParams.sort()`

Hinzugefügt in: v7.7.0, v6.13.0

Sortiert alle vorhandenen Name-Wert-Paare an Ort und Stelle nach ihren Namen. Die Sortierung erfolgt mit einem stabilen Sortieralgorithmus, sodass die relative Reihenfolge zwischen Name-Wert-Paaren mit demselben Namen erhalten bleibt.

Diese Methode kann insbesondere verwendet werden, um Cache-Treffer zu erhöhen.

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

`urlSearchParams.toString()`

Gibt zurück: <string>

Gibt die Suchparameter als Zeichenkette serialisiert zurück, wobei Zeichen bei Bedarf prozentcodiert werden.

`urlSearchParams.values()`

Gibt zurück: <Iterator>

Gibt einen ES6 Iterator über die Werte jedes Name-Wert-Paares zurück.

`urlSearchParams[Symbol.iterator]()`

Gibt zurück: <Iterator>

Gibt einen ES6 Iterator über jedes Name-Wert-Paar in der Query-String zurück. Jedes Element des Iterators ist ein JavaScript Array. Das erste Element des Arrays ist der Name, das zweite Element des Arrays ist der Wert.

Alias für urlSearchParams.entries().

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

`url.domainToASCII(domain)`

[Verlauf]

Version	Änderungen
v20.0.0, v18.17.0	ICU-Anforderung wurde entfernt.
v7.4.0, v6.13.0	Hinzugefügt in: v7.4.0, v6.13.0

domain <string>
Gibt zurück: <string>

Gibt die Punycode ASCII-Serialisierung der domain zurück. Wenn domain eine ungültige Domain ist, wird der leere String zurückgegeben.

Es führt die inverse Operation zu url.domainToUnicode() aus.

ESMCJS

import url from 'node:url'

console.log(url.domainToASCII('español.com'))
// Gibt aus xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'))
// Gibt aus xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'))
// Gibt einen leeren String aus

const url = require('node:url')

console.log(url.domainToASCII('español.com'))
// Gibt aus xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'))
// Gibt aus xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'))
// Gibt einen leeren String aus

`url.domainToUnicode(domain)`

[Verlauf]

Version	Änderungen
v20.0.0, v18.17.0	ICU-Anforderung wurde entfernt.
v7.4.0, v6.13.0	Hinzugefügt in: v7.4.0, v6.13.0

domain <string>
Gibt zurück: <string>

Gibt die Unicode-Serialisierung der domain zurück. Wenn domain eine ungültige Domain ist, wird der leere String zurückgegeben.

Es führt die inverse Operation zu url.domainToASCII() aus.

ESMCJS

import url from 'node:url'

console.log(url.domainToUnicode('xn--espaol-zwa.com'))
// Gibt aus español.com
console.log(url.domainToUnicode('xn--fiq228c.com'))
// Gibt aus 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'))
// Gibt einen leeren String aus

const url = require('node:url')

console.log(url.domainToUnicode('xn--espaol-zwa.com'))
// Gibt aus español.com
console.log(url.domainToUnicode('xn--fiq228c.com'))
// Gibt aus 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'))
// Gibt einen leeren String aus

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

[Verlauf]

Version	Änderungen
v22.1.0, v20.13.0	Das Argument `options` kann jetzt verwendet werden, um zu bestimmen, wie das Argument `path` geparst werden soll.
v10.12.0	Hinzugefügt in: v10.12.0

url <URL> | <string> Die Datei-URL-Zeichenkette oder das URL-Objekt, das in einen Pfad konvertiert werden soll.
options <Object>
- windows <boolean> | <undefined> true, wenn der path als Windows-Dateipfad zurückgegeben werden soll, false für posix und undefined für die Systemstandardeinstellung. Standard: undefined.
Gibt zurück: <string> Der vollständig aufgelöste plattformspezifische Node.js-Dateipfad.

Diese Funktion stellt die korrekte Dekodierung von prozentual kodierten Zeichen sicher und gewährleistet eine plattformübergreifend gültige absolute Pfadzeichenkette.

ESMCJS

import { fileURLToPath } from 'node:url'

const __filename = fileURLToPath(import.meta.url)

new URL('file:///C:/path/').pathname // Falsch: /C:/path/
fileURLToPath('file:///C:/path/') // Korrekt:   C:\path\ (Windows)

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

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

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

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

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

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

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

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

Hinzugefügt in: v7.6.0

URL <URL> Ein WHATWG URL-Objekt
options <Object>
- auth <boolean> true, wenn die serialisierte URL-Zeichenfolge den Benutzernamen und das Passwort enthalten soll, false andernfalls. Standard: true.
- fragment <boolean> true, wenn die serialisierte URL-Zeichenfolge das Fragment enthalten soll, false andernfalls. Standard: true.
- search <boolean> true, wenn die serialisierte URL-Zeichenfolge die Suchanfrage enthalten soll, false andernfalls. Standard: true.
- unicode <boolean> true, wenn Unicode-Zeichen, die in der Hostkomponente der URL-Zeichenfolge erscheinen, direkt codiert werden sollen, anstatt als Punycode codiert zu werden. Standard: false.
Gibt zurück: <string>

Gibt eine anpassbare Serialisierung einer URL String-Darstellung eines WHATWG URL-Objekts zurück.

Das URL-Objekt verfügt sowohl über eine toString()-Methode als auch über eine href-Eigenschaft, die String-Serialisierungen der URL zurückgeben. Diese sind jedoch in keiner Weise anpassbar. Die Methode url.format(URL[, options]) ermöglicht eine grundlegende Anpassung der Ausgabe.

ESMCJS

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

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

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

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

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

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

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

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

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

[Verlauf]

Version	Änderungen
v22.1.0, v20.13.0	Das `options`-Argument kann jetzt verwendet werden, um zu bestimmen, wie der `path`-Wert zurückgegeben werden soll.
v10.12.0	Hinzugefügt in: v10.12.0

path <string> Der Pfad, der in eine Datei-URL umgewandelt werden soll.
options <Object>
- windows <boolean> | <undefined> true, wenn der path als Windows-Dateipfad behandelt werden soll, false für posix und undefined für die Systemstandardeinstellung. Standard: undefined.
Gibt zurück: <URL> Das Datei-URL-Objekt.

Diese Funktion stellt sicher, dass path absolut aufgelöst wird und dass die URL-Steuerzeichen bei der Umwandlung in eine Datei-URL korrekt kodiert werden.

ESMCJS

import { pathToFileURL } from 'node:url'

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

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

const { pathToFileURL } = require('node:url')
new URL(__filename) // Falsch: wirft Fehler (POSIX)
new URL(__filename) // Falsch: C:\... (Windows)
pathToFileURL(__filename) // Richtig:   file:///... (POSIX)
pathToFileURL(__filename) // Richtig:   file:///C:/... (Windows)

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

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

`url.urlToHttpOptions(url)`

[Verlauf]

Version	Änderungen
v19.9.0, v18.17.0	Das zurückgegebene Objekt enthält auch alle eigenen aufzählbaren Eigenschaften des Arguments `url`.
v15.7.0, v14.18.0	Hinzugefügt in: v15.7.0, v14.18.0

url <URL> Das WHATWG URL-Objekt, das in ein Options-Objekt konvertiert werden soll.
Gibt zurück: <Object> Options-Objekt
- protocol <string> Zu verwendendes Protokoll.
- hostname <string> Ein Domänenname oder eine IP-Adresse des Servers, an den die Anfrage gesendet werden soll.
- hash <string> Der Fragmentteil der URL.
- search <string> Der serialisierte Abfrageteil der URL.
- pathname <string> Der Pfadteil der URL.
- path <string> Anforderungspfad. Sollte die Abfragezeichenfolge, falls vorhanden, enthalten. Z.B. '/index.html?page=12'. Eine Ausnahme wird ausgelöst, wenn der Anforderungspfad ungültige Zeichen enthält. Derzeit werden nur Leerzeichen abgelehnt, dies kann sich jedoch in Zukunft ändern.
- href <string> Die serialisierte URL.
- port <number> Port des Remote-Servers.
- auth <string> Basisauthentifizierung, d.h. 'user:password', um einen Authorization-Header zu berechnen.

Diese Hilfsfunktion konvertiert ein URL-Objekt in ein gewöhnliches Options-Objekt, wie es von den APIs http.request() und https.request() erwartet wird.

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

Legacy URL API

[Verlauf]

Version	Änderungen
v15.13.0, v14.17.0	Veraltung aufgehoben. Status auf "Legacy" geändert.
v11.0.0	Diese API ist veraltet.

[Stabil: 3 - Legacy]

Stabil: 3 Stabilität: 3 - Legacy: Verwenden Sie stattdessen die WHATWG URL API.

Legacy `urlObject`

[Verlauf]

Version	Änderungen
v15.13.0, v14.17.0	Veraltung aufgehoben. Status auf "Legacy" geändert.
v11.0.0	Die Legacy URL API ist veraltet. Verwenden Sie die WHATWG URL API.

[Stabil: 3 - Legacy]

Stabil: 3 Stabilität: 3 - Legacy: Verwenden Sie stattdessen die WHATWG URL API.

Das Legacy urlObject (require('node:url').Url oder import { Url } from 'node:url') wird durch die Funktion url.parse() erstellt und zurückgegeben.

`urlObject.auth`

Die auth-Eigenschaft ist der Benutzername- und Passwortteil der URL, der auch als Benutzerinfo bezeichnet wird. Diese String-Teilmenge folgt dem Protokoll und den doppelten Schrägstrichen (falls vorhanden) und geht der Host-Komponente voran, die durch @ begrenzt wird. Der String ist entweder der Benutzername oder der Benutzername und das Passwort, getrennt durch :.

Zum Beispiel: 'user:pass'.

`urlObject.hash`

Die hash-Eigenschaft ist der Fragmentbezeichnerteil der URL, einschließlich des vorangestellten #-Zeichens.

Zum Beispiel: '#hash'.

`urlObject.host`

Die host-Eigenschaft ist der vollständige, kleingeschriebene Host-Teil der URL, einschließlich des Port, falls angegeben.

Zum Beispiel: 'sub.example.com:8080'.

`urlObject.hostname`

Die hostname-Eigenschaft ist der kleingeschriebene Hostname-Teil der host-Komponente ohne den Port.

Zum Beispiel: 'sub.example.com'.

`urlObject.href`

Die href-Eigenschaft ist der vollständige URL-String, der analysiert wurde, wobei sowohl die protocol- als auch die host-Komponenten in Kleinbuchstaben konvertiert wurden.

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

`urlObject.path`

Die Eigenschaft path ist eine Verkettung der Komponenten pathname und search.

Zum Beispiel: '/p/a/t/h?query=string'.

Es wird keine Dekodierung des path durchgeführt.

`urlObject.pathname`

Die Eigenschaft pathname besteht aus dem gesamten Pfadabschnitt der URL. Dies ist alles, was nach dem host (einschließlich des port) und vor dem Beginn der query- oder hash-Komponenten kommt, die entweder durch das ASCII-Fragezeichen (?) oder das Hash-Zeichen (#) begrenzt werden.

Zum Beispiel: '/p/a/t/h'.

Es wird keine Dekodierung der Pfadzeichenfolge durchgeführt.

`urlObject.port`

Die Eigenschaft port ist der numerische Port-Abschnitt der host-Komponente.

Zum Beispiel: '8080'.

`urlObject.protocol`

Die Eigenschaft protocol identifiziert das kleingeschriebene Protokollschema der URL.

Zum Beispiel: 'http:'.

`urlObject.query`

Die Eigenschaft query ist entweder die Query-Zeichenfolge ohne das vorangestellte ASCII-Fragezeichen (?) oder ein Objekt, das von der Methode parse() des querystring-Moduls zurückgegeben wird. Ob die Eigenschaft query eine Zeichenfolge oder ein Objekt ist, wird durch das Argument parseQueryString bestimmt, das an url.parse() übergeben wird.

Zum Beispiel: 'query=string' oder {'query': 'string'}.

Wenn als Zeichenfolge zurückgegeben, wird keine Dekodierung der Query-Zeichenfolge durchgeführt. Wenn als Objekt zurückgegeben, werden sowohl Schlüssel als auch Werte dekodiert.

`urlObject.search`

Die Eigenschaft search besteht aus dem gesamten "Query-String"-Abschnitt der URL, einschließlich des vorangestellten ASCII-Fragezeichens (?).

Zum Beispiel: '?query=string'.

Es wird keine Dekodierung der Query-Zeichenfolge durchgeführt.

`urlObject.slashes`

Die Eigenschaft slashes ist ein boolean-Wert mit dem Wert true, wenn nach dem Doppelpunkt im protocol zwei ASCII-Schrägstrichzeichen (/) erforderlich sind.

`url.format(urlObject)`

[Verlauf]

Version	Änderungen
v17.0.0	Wirft nun eine `ERR_INVALID_URL`-Ausnahme, wenn die Punycode-Konvertierung eines Hostnamens Änderungen einführt, die dazu führen könnten, dass die URL unterschiedlich neu geparst wird.
v15.13.0, v14.17.0	Die Veraltung wurde aufgehoben. Status wurde in "Legacy" geändert.
v11.0.0	Die Legacy URL API ist veraltet. Verwenden Sie die WHATWG URL API.
v7.0.0	URLs mit einem `file:`-Schema verwenden nun immer die korrekte Anzahl von Schrägstrichen, unabhängig von der Option `slashes`. Eine falsche `slashes`-Option ohne Protokoll wird nun auch jederzeit berücksichtigt.
v0.1.25	Hinzugefügt in: v0.1.25

[Stabil: 3 - Legacy]

Stabil: 3 Stabilität: 3 - Legacy: Verwenden Sie stattdessen die WHATWG URL API.

urlObject <Object> | <string> Ein URL-Objekt (wie von url.parse() zurückgegeben oder anderweitig konstruiert). Wenn es sich um eine Zeichenfolge handelt, wird es in ein Objekt umgewandelt, indem es an url.parse() übergeben wird.

Die Methode url.format() gibt eine formatierte URL-Zeichenfolge zurück, die von urlObject abgeleitet wurde.

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'

Wenn urlObject kein Objekt oder keine Zeichenfolge ist, wirft url.format() einen TypeError.

Der Formatierungsprozess funktioniert wie folgt:

Eine neue leere Zeichenfolge result wird erstellt.
Wenn urlObject.protocol eine Zeichenfolge ist, wird sie unverändert an result angehängt.
Andernfalls, wenn urlObject.protocol nicht undefined ist und keine Zeichenfolge ist, wird ein Error geworfen.
Für alle Zeichenfolgenwerte von urlObject.protocol, die nicht mit einem ASCII-Doppelpunkt (:) enden, wird die Literalzeichenfolge : an result angehängt.
Wenn eine der folgenden Bedingungen zutrifft, wird die Literalzeichenfolge // an result angehängt:
- Die Eigenschaft urlObject.slashes ist wahr;
- urlObject.protocol beginnt mit http, https, ftp, gopher oder file;
Wenn der Wert der Eigenschaft urlObject.auth wahrheitsgemäß ist und entweder urlObject.host oder urlObject.hostname nicht undefined sind, wird der Wert von urlObject.auth in eine Zeichenfolge umgewandelt und an result angehängt, gefolgt von der Literalzeichenfolge @.
Wenn die Eigenschaft urlObject.host undefined ist, dann:
- Wenn urlObject.hostname eine Zeichenfolge ist, wird sie an result angehängt.
- Andernfalls, wenn urlObject.hostname nicht undefined ist und keine Zeichenfolge ist, wird ein Error geworfen.
- Wenn der Eigenschaftswert urlObject.port wahrheitsgemäß ist und urlObject.hostname nicht undefined ist:
- Die Literalzeichenfolge : wird an result angehängt, und
- Der Wert von urlObject.port wird in eine Zeichenfolge umgewandelt und an result angehängt.
Andernfalls, wenn der Eigenschaftswert urlObject.host wahrheitsgemäß ist, wird der Wert von urlObject.host in eine Zeichenfolge umgewandelt und an result angehängt.
Wenn die Eigenschaft urlObject.pathname eine Zeichenfolge ist, die keine leere Zeichenfolge ist:
- Wenn urlObject.pathname nicht mit einem ASCII-Schrägstrich (/) beginnt, wird die Literalzeichenfolge '/' an result angehängt.
- Der Wert von urlObject.pathname wird an result angehängt.
Andernfalls, wenn urlObject.pathname nicht undefined ist und keine Zeichenfolge ist, wird ein Error geworfen.
Wenn die Eigenschaft urlObject.search undefined ist und die Eigenschaft urlObject.query ein Object ist, wird die Literalzeichenfolge ? an result angehängt, gefolgt von der Ausgabe des Aufrufs der Methode stringify() des querystring-Moduls, wobei der Wert von urlObject.query übergeben wird.
Andernfalls, wenn urlObject.search eine Zeichenfolge ist:
- Wenn der Wert von urlObject.search nicht mit dem ASCII-Fragezeichen (?) beginnt, wird die Literalzeichenfolge ? an result angehängt.
- Der Wert von urlObject.search wird an result angehängt.
Andernfalls, wenn urlObject.search nicht undefined ist und keine Zeichenfolge ist, wird ein Error geworfen.
Wenn die Eigenschaft urlObject.hash eine Zeichenfolge ist:
- Wenn der Wert von urlObject.hash nicht mit dem ASCII-Hashzeichen (#) beginnt, wird die Literalzeichenfolge # an result angehängt.
- Der Wert von urlObject.hash wird an result angehängt.
Andernfalls, wenn die Eigenschaft urlObject.hash nicht undefined ist und keine Zeichenfolge ist, wird ein Error geworfen.
result wird zurückgegeben.

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

[Verlauf]

Version	Änderungen
v19.0.0, v18.13.0	Nur Dokumentations-Deprecation.
v15.13.0, v14.17.0	Deprecation widerrufen. Status auf "Legacy" geändert.
v11.14.0	Die Eigenschaft `pathname` des zurückgegebenen URL-Objekts ist nun `/`, wenn kein Pfad vorhanden ist und das Protokollschema `ws:` oder `wss:` ist.
v11.0.0	Die Legacy-URL-API ist veraltet. Verwenden Sie die WHATWG-URL-API.
v9.0.0	Die Eigenschaft `search` des zurückgegebenen URL-Objekts ist nun `null`, wenn keine Abfragezeichenfolge vorhanden ist.
v0.1.25	Hinzugefügt in: v0.1.25

[Stabil: 0 - Veraltet]

Stabil: 0 Stabilität: 0 - Veraltet: Verwenden Sie stattdessen die WHATWG-URL-API.

urlString <string> Die zu parsende URL-Zeichenfolge.
parseQueryString <boolean> Wenn true, wird die Eigenschaft query immer auf ein Objekt gesetzt, das von der Methode parse() des Moduls querystring zurückgegeben wird. Wenn false, ist die Eigenschaft query des zurückgegebenen URL-Objekts eine unparsierte, uncodierte Zeichenfolge. Standard: false.
slashesDenoteHost <boolean> Wenn true, wird das erste Token nach der Literalzeichenfolge // und vor dem nächsten / als host interpretiert. Zum Beispiel wäre bei //foo/bar das Ergebnis {host: 'foo', pathname: '/bar'} anstelle von {pathname: '//foo/bar'}. Standard: false.

Die Methode url.parse() nimmt eine URL-Zeichenfolge, parst sie und gibt ein URL-Objekt zurück.

Es wird ein TypeError ausgelöst, wenn urlString keine Zeichenfolge ist.

Es wird ein URIError ausgelöst, wenn die Eigenschaft auth vorhanden ist, aber nicht decodiert werden kann.

url.parse() verwendet einen nachsichtigen, nicht standardmäßigen Algorithmus zum Parsen von URL-Zeichenfolgen. Es ist anfällig für Sicherheitsprobleme wie Spoofing von Hostnamen und die fehlerhafte Behandlung von Benutzernamen und Passwörtern. Nicht mit nicht vertrauenswürdigen Eingaben verwenden. Für url.parse()-Schwachstellen werden keine CVEs ausgestellt. Verwenden Sie stattdessen die WHATWG URL-API.

`url.resolve(from, to)`

[Verlauf]

Version	Änderungen
v15.13.0, v14.17.0	Veraltung aufgehoben. Status auf "Legacy" geändert.
v11.0.0	Die Legacy-URL-API ist veraltet. Verwenden Sie die WHATWG-URL-API.
v6.6.0	Die Felder `auth` bleiben jetzt intakt, wenn `from` und `to` sich auf denselben Host beziehen.
v6.0.0	Die Felder `auth` werden jetzt gelöscht, wenn der Parameter `to` einen Hostnamen enthält.
v6.5.0, v4.6.2	Das Feld `port` wird jetzt korrekt kopiert.
v0.1.25	Hinzugefügt in: v0.1.25

[Stabil: 3 - Legacy]

Stabil: 3 Stabilität: 3 - Legacy: Verwenden Sie stattdessen die WHATWG-URL-API.

from <string> Die Basis-URL, die verwendet wird, wenn to eine relative URL ist.
to <string> Die Ziel-URL, die aufgelöst werden soll.

Die Methode url.resolve() löst eine Ziel-URL relativ zu einer Basis-URL auf, ähnlich wie ein Webbrowser ein Anker-Tag auflöst.

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'

Um das gleiche Ergebnis mit der WHATWG-URL-API zu erzielen:

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

Prozentcodierung in URLs

URLs dürfen nur einen bestimmten Bereich von Zeichen enthalten. Alle Zeichen, die außerhalb dieses Bereichs liegen, müssen codiert werden. Wie solche Zeichen codiert werden und welche Zeichen codiert werden müssen, hängt vollständig davon ab, wo sich das Zeichen innerhalb der Struktur der URL befindet.

Legacy-API

Innerhalb der Legacy-API werden Leerzeichen (' ') und die folgenden Zeichen in den Eigenschaften von URL-Objekten automatisch maskiert:

text

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

Beispielsweise wird das ASCII-Leerzeichen (' ') als %20 kodiert. Der ASCII-Schrägstrich (/) wird als %3C kodiert.

WHATWG-API

Der WHATWG URL Standard verwendet einen selektiveren und feiner abgestuften Ansatz zur Auswahl der kodierten Zeichen als die Legacy-API.

Der WHATWG-Algorithmus definiert vier "Prozentkodierungssätze", die Bereiche von Zeichen beschreiben, die prozentual kodiert werden müssen:

Der C0-Steuerzeichen-Prozentkodierungssatz umfasst Codepunkte im Bereich von U+0000 bis U+001F (einschließlich) und alle Codepunkte größer als U+007E (~).
Der Fragment-Prozentkodierungssatz enthält den C0-Steuerzeichen-Prozentkodierungssatz und die Codepunkte U+0020 LEERZEICHEN, U+0022 ("), U+003C (<), U+003E (>) und U+0060 (`).
Der Pfad-Prozentkodierungssatz enthält den C0-Steuerzeichen-Prozentkodierungssatz und die Codepunkte U+0020 LEERZEICHEN, U+0022 ("), U+0023 (#), U+003C (<), U+003E (>), U+003F (?), U+0060 (`), U+007B ({) und U+007D (}).
Der Benutzerinfo-Kodierungssatz enthält den Pfad-Prozentkodierungssatz und die Codepunkte U+002F (/), U+003A (😃, U+003B (😉, U+003D (=), U+0040 (@), U+005B ([) bis U+005E(^) und U+007C (|).

Der Benutzerinfo-Prozentkodierungssatz wird ausschließlich für Benutzernamen und Passwörter verwendet, die in der URL kodiert sind. Der Pfad-Prozentkodierungssatz wird für den Pfad der meisten URLs verwendet. Der Fragment-Prozentkodierungssatz wird für URL-Fragmente verwendet. Der C0-Steuerzeichen-Prozentkodierungssatz wird zusätzlich zu allen anderen Fällen für Host und Pfad unter bestimmten Bedingungen verwendet.

Wenn Nicht-ASCII-Zeichen in einem Hostnamen vorkommen, wird der Hostname mit dem Punycode-Algorithmus kodiert. Beachten Sie jedoch, dass ein Hostname sowohl Punycode-kodierte als auch Prozent-kodierte Zeichen enthalten kann:

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

URL ​

URL-Strings und URL-Objekte ​

Konstruieren einer URL aus Komponenten und Abrufen der erstellten Zeichenkette ​

Die WHATWG URL API ​

Klasse: URL ​

new URL(input[, base]) ​

url.hash ​

url.host ​

url.hostname ​

url.href ​

url.origin ​

url.password ​

url.pathname ​

url.port ​

url.protocol ​

Spezielle Schemata ​

url.search ​

url.searchParams ​

url.username ​

url.toString() ​

url.toJSON() ​

URL.createObjectURL(blob) ​

URL.revokeObjectURL(id) ​

URL.canParse(input[, base]) ​

URL.parse(input[, base]) ​

Klasse: 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) ​

Legacy URL API ​

Legacy urlObject ​

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

Prozentcodierung in URLs ​

Legacy-API ​

WHATWG-API ​

URL

URL-Strings und URL-Objekte

Konstruieren einer URL aus Komponenten und Abrufen der erstellten Zeichenkette

Die WHATWG URL API

Klasse: `URL`

`new URL(input[, base])`

`url.hash`

`url.host`

`url.hostname`

`url.href`

`url.origin`

`url.password`

`url.pathname`

`url.port`

`url.protocol`

Spezielle Schemata

`url.search`

`url.searchParams`

`url.username`

`url.toString()`

`url.toJSON()`

`URL.createObjectURL(blob)`

`URL.revokeObjectURL(id)`

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

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

Klasse: `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)`

Legacy URL API

Legacy `urlObject`

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

Prozentcodierung in URLs

Legacy-API

WHATWG-API