URL

[Stabil: 2 - Stabil]

Quellcode: lib/url.js

Das Modul node:url stellt Dienstprogramme zur URL-Auflösung und -Analyse bereit. Es kann wie folgt 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 Modul node:url bietet zwei APIs für die Arbeit mit URLs: eine Legacy-API, die Node.js-spezifisch 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 ist unten dargestellt. Oberhalb der URL 'https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash' werden die Eigenschaften eines Objekts angezeigt, das von der Legacy-Funktion url.parse() zurückgegeben wird. Darunter befinden sich die 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 der URL-Zeichenfolge mit der WHATWG-API:

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

Parsen der URL-Zeichenfolge 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');

Erstellen einer URL aus Komponenten und Abrufen der erstellten Zeichenfolge

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

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-Zeichenfolge abzurufen, verwenden Sie den Eigenschafts-Accessor href:

console.log(myURL.href);

Die WHATWG URL API

Klasse: `URL`

[Historie]

Version	Änderungen
v10.0.0	Die Klasse ist jetzt im 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 im globalen Objekt verfügbar.

In Übereinstimmung mit Browserkonventionen werden alle Eigenschaften von URL-Objekten als Getter und Setter im Klassenprototyp implementiert und nicht als Dateneigenschaften des Objekts selbst. Im Gegensatz zu Legacy urlObjects hat die Verwendung des Schlüsselworts delete für Eigenschaften von URL-Objekten (z. B. delete myURL.protocol, delete myURL.pathname usw.) keine Auswirkung, gibt aber dennoch true zurück.

`new URL(input[, base])`

[Historie]

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

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

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

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 Zeichenfolgen zu konvertieren. Zum Beispiel:

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

Unicode-Zeichen, die im Hostnamen von input erscheinen, werden automatisch mit dem Punycode-Algorithmus in ASCII konvertiert.

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 dem entspricht, was erwartet wird.

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 Prozent-codiert. Die Auswahl der Zeichen, die Prozent-codiert werden sollen, kann geringfügig von dem abweichen, was die Methoden url.parse() und url.format() erzeugen würden.

`url.host`

<string>

Ruft den Host-Teil 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 Host-Werte, 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 Setzen 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 Hostname und Port zu ändern
myURL.host = 'example.org:82';
console.log(myURL.href);
// Gibt https://example.org:82/foo aus

Ungültige Hostnamen-Werte, 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 entspricht dem Aufruf von url.toString().

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

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

`url.origin`

[Historie]

Version	Änderungen
v15.0.0	Das Schema "gopher" ist nicht länger speziell und `url.origin` gibt nun `'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 in dem Wert enthalten sind, der der Eigenschaft password zugewiesen wird, werden prozentual codiert. Die Auswahl der Zeichen, die prozentual codiert werden sollen, kann sich geringfügig von dem unterscheiden, 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 in dem Wert enthalten sind, der der Eigenschaft pathname zugewiesen wird, werden prozentual codiert. Die Auswahl der Zeichen, die prozentual codiert werden sollen, kann sich geringfügig von dem unterscheiden, was die Methoden url.parse() und url.format() erzeugen würden.

`url.port`

[Verlauf]

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

<string>

Ruft den Port-Abschnitt 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. Das Setzen des Wertes auf den Standardport der gegebenen URL-Objekte protocol führt dazu, dass der port-Wert zur leeren Zeichenkette ('') wird.

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
Bei der Zuweisung eines Wertes zum Port wird der Wert zuerst mit `.toString()` in eine Zeichenkette umgewandelt.

Wenn diese Zeichenkette ungültig ist, aber mit einer Zahl beginnt, wird die führende Zahl port zugewiesen. Liegt die Zahl außerhalb des oben genannten Bereichs, 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 Port-Zeichenketten 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 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, vorausgesetzt, sie sind gültig:

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 protocol-Eigenschaft zugewiesen werden, werden ignoriert.

Spezielle Schemata

[Historie]

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 auf die Art und Weise, wie sie geparst und serialisiert werden. Wenn eine URL mit einem dieser speziellen Protokolle geparst wird, kann die Eigenschaft url.protocol in ein anderes spezielles Protokoll geändert werden, aber sie kann nicht in ein nicht-spezielles Protokoll geändert werden 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

Gemäß 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 im Wert der Eigenschaft search erscheinen, werden prozentual codiert. Die Auswahl, welche Zeichen prozentual codiert werden sollen, kann geringfügig 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 bereitgestellte URLSearchParams-Objekt kann verwendet werden, um die URL-Instanz zu verändern. Um die gesamten Abfrageparameter der URL zu ersetzen, verwenden Sie den url.search-Setter. Weitere Informationen finden Sie in der Dokumentation zu URLSearchParams.

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 prozentual kodiert werden sollen. Beispielsweise wird das ASCII-Tilde-Zeichen (~) vom URL-Objekt nicht prozentual kodiert, während es von URLSearchParams immer kodiert wird:

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

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

// Ändern Sie die 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 legt ihn fest.

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 in dem Wert erscheinen, der der username-Eigenschaft zugewiesen wird, werden prozentual kodiert. Die Auswahl der Zeichen, die prozentual kodiert werden sollen, kann von dem abweichen, was die Methoden url.parse() und url.format() erzeugen würden.

`url.toString()`

Gibt zurück: <string>

Die Methode toString() 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 Methode toJSON() 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));
// Prints ["https://www.example.com/","https://test.example.org/"]

`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 eine 'blob:nodedata:...'-URL-Zeichenfolge, die 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);

// later...

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

Die von dem registrierten <Blob> gespeicherten Daten werden im Speicher behalten, 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 innerhalb eines Workers 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> Eine 'blob:nodedata:...-URL-Zeichenfolge, die 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 analysiert 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 ein 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 analysiert 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>

Analysiert eine Zeichenkette als URL. Wenn base angegeben ist, wird diese als Basis-URL verwendet, um nicht-absolute input-URLs aufzulösen. Gibt null zurück, wenn input ungültig ist.

Klasse: `URLSearchParams`

[Historie]

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 Klasse URLSearchParams kann auch eigenständig mit einem der vier folgenden Konstruktoren verwendet werden. Die Klasse URLSearchParams 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 ausschließlich für URL-Abfragezeichenfolgen 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

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

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

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

Erzeugt 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 welchem Fall der Konstruktor einfach einen Klon des bereitgestellten URLSearchParams erstellt. Elemente von iterable sind Schlüssel-Wert-Paare und können selbst ein beliebiges iterierbares Objekt sein.

Doppelte Schlüssel sind erlaubt.

let params;

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

// Verwenden 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

// Verwenden 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'],
]);
// Wirft TypeError [ERR_INVALID_TUPLE]:
//        Jedes Query-Paar muss ein iterierbares [name, value]-Tupel sein

`urlSearchParams.append(name, value)`

name <string>
value <string>

Fügt ein neues Name-Wert-Paar zur Abfragezeichenfolge 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 ist, werden alle Name-Wert-Paare entfernt, bei denen der Name name und der Wert value ist.

Wenn value nicht angegeben ist, werden alle Name-Wert-Paare entfernt, 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 value.

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

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

[Verlauf]

Version	Änderungen
v18.0.0	Die Übergabe eines ungültigen Callbacks an das `fn`-Argument wirft jetzt `ERR_INVALID_ARG_TYPE` anstelle von `ERR_INVALID_CALLBACK`.

fn <Function> Wird für jedes Name-Wert-Paar in der Abfrage aufgerufen
thisArg <Object> 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);
});
// Prints:
//   a b true
//   c d true

`urlSearchParams.get(name)`

name <string>
Gibt zurück: <string> | <null> Eine Zeichenkette oder null, wenn kein Name-Wert-Paar mit dem gegebenen name vorhanden ist.

Gibt den Wert des ersten Name-Wert-Paares zurück, dessen Name name ist. Wenn keine solchen Paare vorhanden sind, 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 vorhanden sind, 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 ist, wird true zurückgegeben, wenn ein Name-Wert-Paar mit demselben name und value vorhanden ist.

Wenn value nicht angegeben ist, 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 assoziiert ist, auf value. Wenn es bereits Name-Wert-Paare gibt, deren Namen name sind, wird der Wert des ersten solchen Paares auf value gesetzt und alle anderen werden entfernt. Andernfalls wird das Name-Wert-Paar an die Abfragezeichenfolge angehängt.

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

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

`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 In-Place 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());
// Prints query%5B%5D=abc&query%5B%5D=123&type=search

`urlSearchParams.toString()`

Gibt zurück: <string>

Gibt die Suchparameter als Zeichenfolge serialisiert zurück, wobei Zeichen bei Bedarf prozentual kodiert 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 der Name-Wert-Paare in der Abfragezeichenfolge 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 value.

Alias für urlSearchParams.entries().

const params = new URLSearchParams('foo=bar&xyz=baz');
for (const [name, value] of params) {
  console.log(name, value);
}
// Prints:
//   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 die leere Zeichenfolge 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'));
// Prints xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'));
// Prints xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'));
// Prints an empty string

const url = require('node:url');

console.log(url.domainToASCII('español.com'));
// Prints xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'));
// Prints xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'));
// Prints an empty string

`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 die leere Zeichenfolge 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'));
// Prints español.com
console.log(url.domainToUnicode('xn--fiq228c.com'));
// Prints 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'));
// Prints an empty string

const url = require('node:url');

console.log(url.domainToUnicode('xn--espaol-zwa.com'));
// Prints español.com
console.log(url.domainToUnicode('xn--fiq228c.com'));
// Prints 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'));
// Prints an empty string

`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` analysiert 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 Decodierung 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, andernfalls false. Standard: true.
- fragment <boolean> true, wenn die serialisierte URL-Zeichenfolge das Fragment enthalten soll, andernfalls false. Standard: true.
- search <boolean> true, wenn die serialisierte URL-Zeichenfolge die Suchabfrage enthalten soll, andernfalls false. Standard: true.
- unicode <boolean> true, wenn Unicode-Zeichen, die in der Host-Komponente der URL-Zeichenfolge vorkommen, direkt codiert werden sollen, anstatt 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);
// Prints https://a:b@xn--g6w251d/?abc#foo

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

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

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

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

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

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

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

[Historie]

Version	Änderungen
v22.1.0, v20.13.0	Das `options`-Argument kann nun 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 konvertiert 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 Systemvorgabe. 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 Konvertierung in eine Datei-URL korrekt codiert werden.

ESMCJS

import { pathToFileURL } from 'node:url';

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

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

const { pathToFileURL } = require('node:url');
new URL(__filename);                  // Falsch: throws (POSIX)
new URL(__filename);                  // Falsch: C:\... (Windows)
pathToFileURL(__filename);            // Korrekt:   file:///... (POSIX)
pathToFileURL(__filename);            // Korrekt:   file:///C:/... (Windows)

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

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

`url.urlToHttpOptions(url)`

[Historie]

Version	Änderungen
v19.9.0, v18.17.0	Das zurückgegebene Objekt enthält auch alle eigenen aufzählbaren Eigenschaften des `url`-Arguments.
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> Anfragepfad. Sollte die Abfragezeichenfolge enthalten, falls vorhanden. Z.B. '/index.html?page=12'. Es wird eine Ausnahme ausgelöst, wenn der Anfragepfad ungültige Zeichen enthält. Derzeit werden nur Leerzeichen abgelehnt, dies kann sich aber 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

[History]

Version	Changes
v15.13.0, v14.17.0	Deprecation aufgehoben. Status zu "Legacy" geändert.
v11.0.0	Diese API ist veraltet.

[Stable: 3 - Legacy]

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

Legacy `urlObject`

[History]

Version	Changes
v15.13.0, v14.17.0	Deprecation aufgehoben. Status zu "Legacy" geändert.
v11.0.0	Die Legacy URL API ist veraltet. Verwenden Sie die WHATWG URL API.

[Stable: 3 - Legacy]

Stable: 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 von der Funktion url.parse() erstellt und zurückgegeben.

`urlObject.auth`

Die auth-Eigenschaft ist der Benutzername- und Passwortteil der URL, auch als userinfo bezeichnet. Diese String-Teilmenge folgt dem protocol und den doppelten Schrägstrichen (falls vorhanden) und geht der host-Komponente voraus, die durch @ begrenzt wird. Die Zeichenkette 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 führenden #-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 enthaltenen port.

Zum Beispiel: 'sub.example.com'.

`urlObject.href`

Die href-Eigenschaft ist die vollständige URL-Zeichenkette, die analysiert wurde, wobei sowohl die protocol- als auch die host-Komponente in Kleinbuchstaben umgewandelt wurden.

Zum Beispiel: 'http://user:pass@sub.example.com: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 auf den host (einschließlich des port) folgt und vor dem Beginn der query- oder hash-Komponenten liegt, die entweder durch das ASCII-Fragezeichen (?) oder das Hash-Zeichen (#) begrenzt werden.

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

Es wird keine Dekodierung der Pfadzeichenkette 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 Abfragezeichenkette ohne das führende ASCII-Fragezeichen (?) oder ein Objekt, das von der parse()-Methode des querystring-Moduls zurückgegeben wird. Ob die Eigenschaft query eine Zeichenkette 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 Zeichenkette zurückgegeben, wird keine Dekodierung der Abfragezeichenkette 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 führenden ASCII-Fragezeichens (?).

Zum Beispiel: '?query=string'.

Es wird keine Dekodierung der Abfragezeichenkette durchgeführt.

`urlObject.slashes`

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

`url.format(urlObject)`

[Verlauf]

Version	Änderungen
v17.0.0	Wirft jetzt 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	Veralterung widerrufen. Status auf "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 jetzt immer die richtige Anzahl von Schrägstrichen, unabhängig von der Option `slashes`. Eine falsche `slashes`-Option ohne Protokoll wird jetzt 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 Zeichenkette handelt, wird es durch Übergabe an url.parse() in ein Objekt konvertiert.

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

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 eine Zeichenkette ist, wirft url.format() einen TypeError.

Der Formatierungsprozess funktioniert wie folgt:

Es wird eine neue leere Zeichenkette result erstellt.
Wenn urlObject.protocol eine Zeichenkette ist, wird sie unverändert an result angehängt.
Andernfalls wird, wenn urlObject.protocol nicht undefined und keine Zeichenkette ist, ein Error ausgelöst.
Für alle Zeichenkettenwerte von urlObject.protocol, die nicht mit einem ASCII-Doppelpunkt-Zeichen (:) enden, wird die Literalzeichenkette : an result angehängt.
Wenn eine der folgenden Bedingungen zutrifft, wird die Literalzeichenkette // an result angehängt:
- Die Eigenschaft urlObject.slashes ist true;
- urlObject.protocol beginnt mit http, https, ftp, gopher oder file;
Wenn der Wert der Eigenschaft urlObject.auth truthy ist und entweder urlObject.host oder urlObject.hostname nicht undefined sind, wird der Wert von urlObject.auth in eine Zeichenkette umgewandelt und an result angehängt, gefolgt von der Literalzeichenkette @.
Wenn die Eigenschaft urlObject.host undefined ist, dann:
- Wenn urlObject.hostname eine Zeichenkette ist, wird sie an result angehängt.
- Andernfalls wird, wenn urlObject.hostname nicht undefined und keine Zeichenkette ist, ein Error ausgelöst.
- Wenn der Eigenschaftswert urlObject.port truthy ist und urlObject.hostname nicht undefined ist:
- Wird die Literalzeichenkette : an result angehängt, und
- Der Wert von urlObject.port wird in eine Zeichenkette umgewandelt und an result angehängt.
Andernfalls wird, wenn der Eigenschaftswert urlObject.host truthy ist, der Wert von urlObject.host in eine Zeichenkette umgewandelt und an result angehängt.
Wenn die Eigenschaft urlObject.pathname eine Zeichenkette ist, die keine leere Zeichenkette ist:
- Wenn urlObject.pathname nicht mit einem ASCII-Schrägstrich (/) beginnt, wird die Literalzeichenkette '/' an result angehängt.
- Der Wert von urlObject.pathname wird an result angehängt.
Andernfalls wird, wenn urlObject.pathname nicht undefined und keine Zeichenkette ist, ein Error ausgelöst.
Wenn die Eigenschaft urlObject.search undefined ist und wenn die Eigenschaft urlObject.query ein Object ist, wird die Literalzeichenkette ? an result angehängt, gefolgt von der Ausgabe des Aufrufs der stringify()-Methode des querystring-Moduls, die den Wert von urlObject.query übergibt.
Andernfalls, wenn urlObject.search eine Zeichenkette ist:
- Wenn der Wert von urlObject.search nicht mit dem ASCII-Fragezeichen (?) beginnt, wird die Literalzeichenkette ? an result angehängt.
- Der Wert von urlObject.search wird an result angehängt.
Andernfalls wird, wenn urlObject.search nicht undefined und keine Zeichenkette ist, ein Error ausgelöst.
Wenn die Eigenschaft urlObject.hash eine Zeichenkette ist:
- Wenn der Wert von urlObject.hash nicht mit dem ASCII-Hash-Zeichen (#) beginnt, wird die Literalzeichenkette # an result angehängt.
- Der Wert von urlObject.hash wird an result angehängt.
Andernfalls wird, wenn die Eigenschaft urlObject.hash nicht undefined und keine Zeichenkette ist, ein Error ausgelöst.
result wird zurückgegeben.

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

[Historie]

Version	Änderungen
v19.0.0, v18.13.0	Nur Dokumentations-Veraltung.
v15.13.0, v14.17.0	Veraltung widerrufen. Status geändert zu "Legacy".
v11.14.0	Die `pathname`-Eigenschaft des zurückgegebenen URL-Objekts ist jetzt `/`, 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 `search`-Eigenschaft des zurückgegebenen URL-Objekts ist jetzt `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 query-Eigenschaft immer auf ein Objekt gesetzt, das von der parse()-Methode des querystring-Moduls zurückgegeben wird. Wenn false, ist die query-Eigenschaft des zurückgegebenen URL-Objekts eine nicht geparste, nicht dekodierte Zeichenfolge. Standard: false.
slashesDenoteHost <boolean> Wenn true, wird das erste Token nach der Literalzeichenfolge // und vor dem nächsten / als der host interpretiert. Zum Beispiel würde bei //foo/bar das Ergebnis {host: 'foo', pathname: '/bar'} anstatt {pathname: '//foo/bar'} sein. Standard: false.

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

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

Ein URIError wird ausgelöst, wenn die auth-Eigenschaft vorhanden ist, aber nicht dekodiert werden kann.

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

`url.resolve(from, to)`

[Historie]

Version	Änderungen
v15.13.0, v14.17.0	Veraltung aufgehoben. Status geändert zu "Legacy".
v11.0.0	Die Legacy URL API ist veraltet. Verwenden Sie die WHATWG URL API.
v6.6.0	Die `auth`-Felder bleiben nun intakt, wenn `from` und `to` sich auf denselben Host beziehen.
v6.0.0	Die `auth`-Felder werden nun gelöscht, wenn der Parameter `to` einen Hostnamen enthält.
v6.5.0, v4.6.2	Das `port`-Feld wird nun 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 werden soll, wenn to eine relative URL ist.
to <string> Die Ziel-URL, die aufgelöst werden soll.

Die url.resolve()-Methode 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'

Prozentkodierung in URLs

URLs dürfen nur einen bestimmten Bereich von Zeichen enthalten. Jedes Zeichen, das außerhalb dieses Bereichs liegt, muss kodiert werden. Wie solche Zeichen kodiert werden und welche Zeichen zu kodieren sind, 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 automatisch in den Eigenschaften von URL-Objekten 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 kodierter Zeichen als die Legacy-API.

Der WHATWG-Algorithmus definiert vier "Prozentkodierungs-Sets", die Bereiche von Zeichen beschreiben, die prozentkodiert werden müssen:

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

Das Userinfo-Prozentkodierungs-Set wird ausschließlich für Benutzernamen und Passwörter verwendet, die innerhalb der URL kodiert sind. Das Pfad-Prozentkodierungs-Set wird für den Pfad der meisten URLs verwendet. Das Fragment-Prozentkodierungs-Set wird für URL-Fragmente verwendet. Das C0-Steuerzeichen-Prozentkodierungs-Set wird zusätzlich zu allen anderen Fällen unter bestimmten spezifischen Bedingungen für Host und Pfad 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 prozentkodierte 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 ​

Erstellen einer URL aus Komponenten und Abrufen der erstellten Zeichenfolge ​

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

Prozentkodierung in URLs ​

Legacy-API ​

WHATWG-API ​

URL

URL-Strings und URL-Objekte

Erstellen einer URL aus Komponenten und Abrufen der erstellten Zeichenfolge

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

Prozentkodierung in URLs

Legacy-API

WHATWG-API